returns: 3 models — Shiller bootstrap (default), manual %, Wealthfolio history

Adds a "Returns model" picker on /what-if that switches how the
simulator's `paths` (n_paths × n_years × 3) is built:

1. shiller (default) — current behaviour, block-bootstrap of the
   Shiller 1871+ historical series (or its synthetic-calibrated
   fallback when the CSV isn't mounted).

2. manual — every year of every path = the user's "real return %"
   input. Deterministic, no fan, useful for sanity checks. New
   helper `constant_real_return_paths` constructs the (n_paths,
   n_years, 3) tensor with stock=bond=real, cpi=0 so the simulator's
   `(1+nominal)/(1+cpi)-1` short-circuits to exactly the input.

3. wealthfolio — pulls daily_account_valuation from the wealthfolio_sync
   PG mirror, sums total_value + net_contribution across accounts per
   day (FX-adjusted), strips contribution deltas to isolate market
   return, compounds daily returns into per-calendar-year samples,
   block-bootstraps with block_size=1 (only ~6 distinct samples
   available, no serial-correlation signal to preserve). Glide path
   is a no-op in this mode — the user's actual blended portfolio is
   treated as a single asset.

API: SimulateRequest gains `returns_mode` ("shiller"|"manual"|
"wealthfolio") + `manual_real_return_pct`. simulate.py's `_build_paths`
dispatches; wealthfolio mode opens a transient session against the
mirror DB.

UI: new Field on the form (next to Strategy / Glide path) with a
contextual hint that explains each option's tradeoff. The "About the
model" panel at the bottom now has a "Returns model" section
mirroring the same content. The Manual % input only shows when
returns_mode='manual'.

10 new tests on the Wealthfolio helper (contribution-stripping,
multi-account aggregation, FX, partial-year drop, TOTAL filter,
empty-input, plus 3 deterministic-paths tests). 198 backend tests +
7 frontend tests. mypy strict + ruff + tsc strict all pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

fire_planner/api/simulate.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 import numpy as np
 from fastapi import APIRouter, HTTPException
+from sqlalchemy.ext.asyncio import async_sessionmaker
 
 from fire_planner.api.schemas import (
     CompareRequest,
@@ -25,9 +26,14 @@ from fire_planner.api.schemas import (
     SimulateResult,
 )
 from fire_planner.glide_path import get as get_glide
+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.returns.bootstrap import block_bootstrap
 from fire_planner.returns.shiller import load_from_csv, synthetic_returns
+from fire_planner.returns.wealthfolio_returns import (
+    compute_annual_returns_from_pg,
+    constant_real_return_paths,
+)
 from fire_planner.scenarios import build_regime_schedule, build_strategy
 from fire_planner.simulator import SimulationResult, simulate
 
@@ -36,14 +42,51 @@ router = APIRouter(tags=["simulate"])
 _RETURNS_CSV = Path("/data/shiller_returns.csv")
 
 
-def _load_paths(seed: int, n_paths: int, n_years: int) -> np.ndarray:
+def _shiller_paths(seed: int, n_paths: int, n_years: int) -> np.ndarray:
     bundle = (load_from_csv(_RETURNS_CSV) if _RETURNS_CSV.exists() else synthetic_returns(seed=42))
     rng = np.random.default_rng(seed)
     return block_bootstrap(bundle, n_paths=n_paths, n_years=n_years, block_size=5, rng=rng)
 
 
-def _project(req: SimulateRequest) -> tuple[SimulationResult, float]:
-    paths = _load_paths(req.seed, req.n_paths, req.horizon_years)
+async def _wealthfolio_paths(seed: int, n_paths: int, n_years: int) -> np.ndarray:
+    """Block-bootstrap the user's actual blended real returns. With
+    typically <10 distinct annual samples, block_size=1 is appropriate
+    — there's no serial-correlation signal to preserve."""
+    eng = create_wf_sync_engine_from_env()
+    try:
+        factory = async_sessionmaker(eng, expire_on_commit=False)
+        async with factory() as wf_sess:
+            bundle = await compute_annual_returns_from_pg(wf_sess)
+    finally:
+        await eng.dispose()
+    rng = np.random.default_rng(seed)
+    return block_bootstrap(bundle, n_paths=n_paths, n_years=n_years, block_size=1, rng=rng)
+
+
+async def _build_paths(req: SimulateRequest) -> np.ndarray:
+    if req.returns_mode == "manual":
+        if req.manual_real_return_pct is None:
+            raise HTTPException(
+                status_code=400,
+                detail="manual_real_return_pct is required when returns_mode='manual'",
+            )
+        return constant_real_return_paths(
+            n_paths=req.n_paths,
+            n_years=req.horizon_years,
+            real_return_pct=float(req.manual_real_return_pct),
+        )
+    if req.returns_mode == "wealthfolio":
+        try:
+            return await _wealthfolio_paths(req.seed, req.n_paths, req.horizon_years)
+        except ValueError as e:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Wealthfolio history insufficient: {e}",
+            ) from e
+    return _shiller_paths(req.seed, req.n_paths, req.horizon_years)
+
+
+def _project(req: SimulateRequest, paths: np.ndarray) -> tuple[SimulationResult, float]:
     annual_savings = (np.full(req.horizon_years, float(req.savings_per_year_gbp), dtype=np.float64)
                       if req.savings_per_year_gbp > 0 else None)
     floor = float(req.floor_gbp) if req.floor_gbp is not None else None
@@ -120,8 +163,9 @@ def _to_response(result: SimulationResult, elapsed: float) -> SimulateResult:
 @router.post("/simulate", response_model=SimulateResult)
 async def simulate_one(req: SimulateRequest) -> SimulateResult:
     """Run one scenario synchronously, no DB write. ~1-3s for 5k paths."""
+    paths = await _build_paths(req)
     try:
-        result, elapsed = await asyncio.to_thread(_project, req)
+        result, elapsed = await asyncio.to_thread(_project, req, paths)
     except KeyError as e:
         raise HTTPException(status_code=400, detail=f"Unknown name: {e}") from None
     return _to_response(result, elapsed)
@@ -131,7 +175,8 @@ async def simulate_one(req: SimulateRequest) -> SimulateResult:
 async def compare_scenarios(req: CompareRequest) -> CompareResult:
     """Run 2-5 scenarios in parallel, return all results."""
     async def one(s: SimulateRequest) -> SimulateResult:
-        result, elapsed = await asyncio.to_thread(_project, s)
+        paths = await _build_paths(s)
+        result, elapsed = await asyncio.to_thread(_project, s, paths)
         return _to_response(result, elapsed)
 
     try: