fire-planner: Wave 2 chart-first — flex spending, categorised life

events, interactive Visx Gantt + spending-profile chart

Charts are now the primary editor for life events. The Plan-tab body
re-orders to make charts ~80% of viewport real-estate; legacy form
sections are collapsed into a drawer.

Backend:
- alembic 0004: life_event.category enum (essential / discretionary /
  not_spending). Defaults to essential so existing rows keep their
  full spending impact.
- Simulator gains discretionary_outflows + flex_rules params. Tracks
  per-path running ATH, applies the deepest applicable cut to
  discretionary outflows when portfolio drops vs ATH (PLab-style flex
  spending). Cut amount stays in the portfolio (refund pattern).
- New flex_spending module with FlexRule + applicable_cut +
  cuts_per_year (vectorised). Sortable rules; "deepest cut wins" so
  users specify cumulative cuts at each tier.
- New /scenarios/{id}/spending-profile endpoint returning per-year
  base / essential / discretionary / flex_cut / total breakdown.
- SimulateRequest gains flex_rules + life_event.category roundtrip.
- 8 new tests; 246 total pytest pass; mypy + ruff clean.

Frontend (Visx + ECharts):
- Installed @visx/{scale,shape,group,axis,event,responsive,tooltip}
  for native SVG drag interactions.
- New <SpendingProfileChart> — Visx stacked-area of base/essential/
  discretionary with red flex-cut overlay, hover tooltip, click-to-
  scrub-year.
- New <EventGantt> — interactive Visx Gantt:
    * Click empty space → popover create at that year (default
      essential spending event)
    * Click a bar → inline edit popover (name, kind, range, £/y,
      category) with delete button
    * Drag bar middle → moves the whole event (year-resolution snap)
    * Drag bar edges → resizes year_start / year_end
    * All gestures persist via PATCH /life-events/{id}
- New <FlexRulesEditor> — list of {from_ath_pct, cut} tiers, save-on-
  change to scenario.config_json.flex_rules.
- Plan-tab redesign: NW fan dominant top with floating stat badges
  (Year/Age/NW/Δ NW/Spending/Eff. tax) over the chart; spending-
  profile chart middle; Gantt bottom; flex-rules editor; legacy form
  sections in a collapsed <details> drawer.
- Frontend typecheck + 7 vitest tests + production build all clean.

fire_planner/api/schemas.py

@@ -185,6 +185,9 @@ class AnnualSpending(BaseModel):
 # ── life events ──────────────────────────────────────────────────────
 
 
+_CATEGORY_PATTERN = "^(essential|discretionary|not_spending)$"
+
+
 class LifeEventOut(_Base):
     id: int
     scenario_id: int
@@ -194,6 +197,7 @@ class LifeEventOut(_Base):
     year_end: int | None
     delta_gbp_per_year: Decimal
     one_time_amount_gbp: Decimal | None
+    category: str = "essential"
     enabled: bool
     payload: dict[str, Any] | None
     created_at: datetime
@@ -206,6 +210,7 @@ class LifeEventCreate(BaseModel):
     year_end: int | None = Field(default=None, ge=0, le=100)
     delta_gbp_per_year: Decimal = Decimal("0")
     one_time_amount_gbp: Decimal | None = None
+    category: str = Field(default="essential", pattern=_CATEGORY_PATTERN)
     enabled: bool = True
     payload: dict[str, Any] | None = None
 
@@ -217,6 +222,7 @@ class LifeEventPatch(BaseModel):
     year_end: int | None = None
     delta_gbp_per_year: Decimal | None = None
     one_time_amount_gbp: Decimal | None = None
+    category: str | None = Field(default=None, pattern=_CATEGORY_PATTERN)
     enabled: bool | None = None
     payload: dict[str, Any] | None = None
 
@@ -386,9 +392,46 @@ class LifeEventInput(BaseModel):
     year_end: int | None = Field(default=None, ge=0, le=100)
     delta_gbp_per_year: Decimal = Decimal("0")
     one_time_amount_gbp: Decimal | None = None
+    category: str = Field(default="essential", pattern=_CATEGORY_PATTERN)
     enabled: bool = True
 
 
+class FlexRule(BaseModel):
+    """ProjectionLab-style flex-spending rule.
+
+    When the portfolio falls ``from_ath_pct`` below its running all-time-high,
+    cut discretionary spending by ``cut_discretionary_pct``. Multiple rules
+    stack via "worst applicable threshold wins" — at -30% from ATH a rule
+    keyed at -10% AND a rule keyed at -25% both apply, but only the deeper
+    cut takes effect (so users specify *cumulative* cuts, not per-tier).
+
+    `from_ath_pct` is the absolute drop magnitude as a positive fraction:
+    0.30 means "the portfolio is 30% below its ATH". This matches the way
+    PLab labels its sliders ("if down 30%, cut 60%").
+    """
+    from_ath_pct: Decimal = Field(ge=0, le=1)
+    cut_discretionary_pct: Decimal = Field(ge=0, le=1)
+
+
+# ── spending profile ────────────────────────────────────────────────
+
+
+class SpendingProfilePoint(BaseModel):
+    year_idx: int
+    base_gbp: Decimal
+    essential_gbp: Decimal
+    discretionary_gbp: Decimal
+    not_spending_gbp: Decimal
+    flex_cut_gbp: Decimal
+    total_gbp: Decimal
+
+
+class SpendingProfileResponse(BaseModel):
+    scenario_id: int
+    horizon_years: int
+    points: list[SpendingProfilePoint]
+
+
 class SimulateRequest(BaseModel):
     """Sync, non-persisted simulate. Used by the React UI for what-if.
 
@@ -422,6 +465,7 @@ class SimulateRequest(BaseModel):
     manual_real_return_pct: Decimal | None = None
     income_streams: list[IncomeStreamInput] = Field(default_factory=list)
     goals: list[GoalCreate] = Field(default_factory=list)
+    flex_rules: list[FlexRule] = Field(default_factory=list)
     # Rates settings (Wave 1.D.3). When `rates_mode='fixed'`, the engine
     # synthesises a deterministic real-return path from the per-asset
     # growth + dividend + inflation rates below, weighted by the static

fire_planner/api/simulate.py

@@ -26,11 +26,16 @@ from fire_planner.api.schemas import (
     SimulateRequest,
     SimulateResult,
 )
+from fire_planner.flex_spending import FlexRule as EngineFlexRule
 from fire_planner.glide_path import static
 from fire_planner.goals_eval import evaluate_goals
 from fire_planner.income_streams import IncomeStreamInput, streams_to_arrays
 from fire_planner.ingest.wealthfolio_pg import create_wf_sync_engine_from_env
-from fire_planner.life_events import EventInput, events_to_cashflow_array
+from fire_planner.life_events import (
+    EventInput,
+    events_to_cashflow_array,
+    events_to_category_outflows,
+)
 from fire_planner.returns.bootstrap import block_bootstrap
 from fire_planner.returns.shiller import load_from_csv, synthetic_returns
 from fire_planner.returns.wealthfolio_returns import (
@@ -105,6 +110,7 @@ def _project(req: SimulateRequest, paths: np.ndarray) -> tuple[SimulationResult,
     floor = float(req.floor_gbp) if req.floor_gbp is not None else None
 
     cashflow_adjustments = None
+    discretionary_outflows = None
     if req.life_events:
         engine_events = [
             EventInput(
@@ -113,10 +119,20 @@ def _project(req: SimulateRequest, paths: np.ndarray) -> tuple[SimulationResult,
                 delta_gbp_per_year=float(ev.delta_gbp_per_year),
                 one_time_amount_gbp=(float(ev.one_time_amount_gbp)
                                      if ev.one_time_amount_gbp is not None else None),
+                category=ev.category,
                 enabled=ev.enabled,
             ) for ev in req.life_events
         ]
         cashflow_adjustments = events_to_cashflow_array(engine_events, req.horizon_years)
+        category_outflows = events_to_category_outflows(engine_events, req.horizon_years)
+        discretionary_outflows = category_outflows.get("discretionary")
+
+    engine_flex = [
+        EngineFlexRule(
+            from_ath_pct=float(r.from_ath_pct),
+            cut_discretionary_pct=float(r.cut_discretionary_pct),
+        ) for r in req.flex_rules
+    ] if req.flex_rules else None
 
     income_inflows = None
     income_taxable = None
@@ -158,6 +174,8 @@ def _project(req: SimulateRequest, paths: np.ndarray) -> tuple[SimulationResult,
         cashflow_adjustments=cashflow_adjustments,
         income_inflows=income_inflows,
         income_taxable=income_taxable,
+        discretionary_outflows=discretionary_outflows,
+        flex_rules=engine_flex,
     )
     elapsed = time.perf_counter() - started
     return result, elapsed

fire_planner/api/spending_profile.py

@@ -0,0 +1,185 @@
+"""Per-year spending breakdown — drives the Visx stacked-area chart on
+the Plan tab.
+
+Returns one ``SpendingProfilePoint`` per year of the scenario horizon:
+
+  base_gbp           — scenario-level baseline spending (real GBP)
+  essential_gbp      — sum of |delta| from active essential life events
+  discretionary_gbp  — sum of |delta| from active discretionary events
+  not_spending_gbp   — informational events that have a delta_gbp_per_year
+                       but are tagged ``not_spending`` (rare, but possible)
+  flex_cut_gbp       — discretionary £ trimmed by flex rules at p50 portfolio
+                       drawdown vs running ATH (0 when no rules / no
+                       drawdown).
+  total_gbp          — base + essential + discretionary − flex_cut
+
+The flex-cut estimate uses the persisted p50 portfolio path (from
+``projection_yearly``) because the user's scenario.config_json may carry
+``flex_rules`` they've configured but not yet re-run a recompute against.
+This gives an honest preview of how the rules would shape spending; the
+exact per-path cut shows up in the next live ``POST /simulate``.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from decimal import Decimal
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from fire_planner.api.dependencies import get_session
+from fire_planner.api.schemas import (
+    SpendingProfilePoint,
+    SpendingProfileResponse,
+)
+from fire_planner.db import LifeEvent, McRun, ProjectionYearly, Scenario
+
+router = APIRouter(prefix="/scenarios", tags=["spending-profile"])
+
+
+def _category_outflow_at(events: Sequence[LifeEvent], year_idx: int,
+                         category: str) -> Decimal:
+    total = Decimal("0")
+    for ev in events:
+        if not ev.enabled or ev.category != category:
+            continue
+        if year_idx < ev.year_start:
+            continue
+        end = ev.year_end if ev.year_end is not None else ev.year_start
+        if year_idx > end:
+            continue
+        delta = Decimal(str(ev.delta_gbp_per_year or 0))
+        if delta < 0:
+            total += -delta
+        if year_idx == ev.year_start and ev.one_time_amount_gbp is not None:
+            ot = Decimal(str(ev.one_time_amount_gbp))
+            if ot < 0:
+                total += -ot
+    return total
+
+
+def _category_inflow_at(events: Sequence[LifeEvent], year_idx: int,
+                        category: str) -> Decimal:
+    """Positive deltas are inflows — surface them as a negative spending
+    contribution so the stacked area sums correctly."""
+    total = Decimal("0")
+    for ev in events:
+        if not ev.enabled or ev.category != category:
+            continue
+        if year_idx < ev.year_start:
+            continue
+        end = ev.year_end if ev.year_end is not None else ev.year_start
+        if year_idx > end:
+            continue
+        delta = Decimal(str(ev.delta_gbp_per_year or 0))
+        if delta > 0:
+            total += delta
+    return total
+
+
+def _flex_rules_for(scenario: Scenario) -> list[dict[str, float]]:
+    blob = scenario.config_json or {}
+    rules = blob.get("flex_rules") if isinstance(blob, dict) else None
+    if not isinstance(rules, list):
+        return []
+    out: list[dict[str, float]] = []
+    for r in rules:
+        if not isinstance(r, dict):
+            continue
+        try:
+            out.append({
+                "from_ath_pct": float(r.get("from_ath_pct", 0)),
+                "cut_discretionary_pct": float(r.get("cut_discretionary_pct", 0)),
+            })
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+def _flex_cut_at_year(year: ProjectionYearly, ath_so_far_gbp: Decimal,
+                      rules: list[dict[str, float]],
+                      discretionary_gbp: Decimal) -> Decimal:
+    if not rules or discretionary_gbp <= 0 or ath_so_far_gbp <= 0:
+        return Decimal("0")
+    p50 = Decimal(str(year.p50_portfolio_gbp))
+    drawdown = max(Decimal("0"), Decimal("1") - p50 / ath_so_far_gbp)
+    best = Decimal("0")
+    for rule in rules:
+        thr = Decimal(str(rule["from_ath_pct"]))
+        cut = Decimal(str(rule["cut_discretionary_pct"]))
+        if drawdown >= thr and cut > best:
+            best = cut
+    return (discretionary_gbp * best).quantize(Decimal("0.01"))
+
+
+@router.get("/{scenario_id}/spending-profile",
+            response_model=SpendingProfileResponse)
+async def get_spending_profile(
+    scenario_id: int,
+    session: AsyncSession = Depends(get_session),
+) -> SpendingProfileResponse:
+    scen = await session.get(Scenario, scenario_id)
+    if scen is None:
+        raise HTTPException(status_code=404, detail="Scenario not found")
+
+    events = list((await session.execute(
+        select(LifeEvent).where(LifeEvent.scenario_id == scenario_id))).scalars().all())
+
+    yearly_rows: list[ProjectionYearly] = []
+    run = (await session.execute(
+        select(McRun).where(McRun.scenario_id == scenario_id).order_by(
+            McRun.run_at.desc()).limit(1))).scalar_one_or_none()
+    if run is not None:
+        rows = (await session.execute(
+            select(ProjectionYearly).where(ProjectionYearly.mc_run_id == run.id).order_by(
+                ProjectionYearly.year_idx))).scalars().all()
+        yearly_rows = list(rows)
+
+    rules = _flex_rules_for(scen)
+    base = Decimal(str(scen.spending_gbp))
+    horizon = scen.horizon_years
+    by_year = {row.year_idx: row for row in yearly_rows}
+
+    points: list[SpendingProfilePoint] = []
+    ath = Decimal(str(scen.nw_seed_gbp))
+    for year_idx in range(horizon):
+        essential = _category_outflow_at(events, year_idx, "essential")
+        discretionary = _category_outflow_at(events, year_idx, "discretionary")
+        not_spending = _category_outflow_at(events, year_idx, "not_spending")
+
+        # Income-shaped life events (positive delta) reduce the net spend
+        # the user must sustain. We don't subtract them from any single
+        # bucket — they net against `base` for the chart's footprint.
+        ess_inflow = _category_inflow_at(events, year_idx, "essential")
+        disc_inflow = _category_inflow_at(events, year_idx, "discretionary")
+        net_base = base - ess_inflow - disc_inflow
+        if net_base < 0:
+            net_base = Decimal("0")
+
+        flex_cut = Decimal("0")
+        row = by_year.get(year_idx)
+        if row is not None:
+            ath = max(ath, Decimal(str(row.p50_portfolio_gbp)))
+            flex_cut = _flex_cut_at_year(row, ath, rules, discretionary)
+
+        total = net_base + essential + discretionary - flex_cut
+        if total < 0:
+            total = Decimal("0")
+
+        points.append(
+            SpendingProfilePoint(
+                year_idx=year_idx,
+                base_gbp=net_base,
+                essential_gbp=essential,
+                discretionary_gbp=discretionary,
+                not_spending_gbp=not_spending,
+                flex_cut_gbp=flex_cut,
+                total_gbp=total,
+            ))
+
+    return SpendingProfileResponse(
+        scenario_id=scenario_id,
+        horizon_years=horizon,
+        points=points,
+    )