feat: scenario simulation what-if planning full version (#223)

[w7-mgfcode]

Summary

Implements PRP-27 — Scenario Simulation / What-If Planning (Full Version) (#223), the 4-phase increment on the shipped scenarios MVP. Delivered as one branch, phase-ordered commits:

• Phase A — feature_frame.py: a leakage-safe future feature-frame (X_future) generator — long-lag (shift ≥ horizon), calendar, and exogenous columns.
• Phase B — RegressionForecaster (wraps HistGradientBoostingRegressor) + a regression training path; POST /scenarios/simulate routes a regression baseline to a genuine re-forecast (method="model_exogenous").
• Phase C — scenario library (tags, cloned_from) + POST /scenarios/compare (rank 2-5 saved plans, merged multi-series chart) + the planner UI multi-scenario comparison view.
• Phase D — two experiment-agent tools: read-only propose_scenario and mutating, HITL-gated save_scenario; provenance/audit columns on scenario_plan.

Required call-outs (per PRP)

• (a) No cross-slice service.py import (DECISIONS LOCKED ci: add GitHub Actions workflows for phase-1 readiness #3). The scenarios slice still imports only load_model_bundle; agent_tools.py is the agent-integration seam — agents/ imports that module, never scenarios/service.py.
• (b) New leakage surface. The future feature frame is a new place leakage could enter. app/features/scenarios/tests/test_future_frame_leakage.py is its load-bearing spec (long-lag only, future-points-only) — never weaken it.
• (c) HistGradientBoostingRegressor over LightGBM. HGBR ships with scikit-learn (already a dependency) — no new dependency, consistent with the single-host vision. LightGBM stays opt-in for the forecasting model zoo.
• (d) Product-vision Litmus. 1) Fits the existing scenarios + forecasting slices (no new slice). 2) PRP-27 / Scenario Simulation / What-If Planning — Full Version #223 describe it. 3) Time-safety preserved — new leakage spec added. 4) Three forward-only Alembic migrations ship. 5) Runs via docker-compose up. 6) Passes ruff + mypy --strict + pyright --strict + pytest.
• (e) Additive. The model_exogenous path is additive — every non-regression baseline still uses the deterministic heuristic multiplier; the method CHECK was widened, not replaced.
• (f) Agent mutation-surface widening. save_scenario lets the experiment agent persist a scenario_plan row — a new mutation surface. Per AGENTS.md § Safety, it is added to agent_require_approval (["create_alias","archive_run","save_scenario"]) so every agent save pauses for explicit HITL approval and records a full provenance/audit trail (source, agent_session_id, approved_by, approved_at, approval_decision). PRP-27 (maintainer-approved) is that approval.

Validation

• ruff check / ruff format --check — clean
• mypy app/ + pyright app/ (--strict) — 0 errors
• pytest -m "not integration" — 1224 passed
• pytest -m integration (scenarios + agents) — 37 passed
• 3 migrations upgrade/downgrade cleanly on a fresh DB
• Frontend tsc --noEmit + lint + test — clean, 97 passed
• Live dogfood: trained a regression baseline on seeded data, confirmed POST /scenarios/simulate returns method="model_exogenous", saved/tagged/listed/compared plans through the running API. (Note: the seeded sales are price-invariant, so the model's price response is legitimately flat — the mechanism is exercised by the synthetic-coefficient integration fixture.)

Closes #223.

[sourcery-ai]

Sorry @w7-mgfcode, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cf33043e-ff96-47e3-ba4a-d4b4bf41417d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/scenario-simulation-full-version

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}