Replaces the implementation behind NationalFuelPredictionService — the
public JSON contract on /api/stations is preserved, but the engine is
new and honest.
Layers (per docs/superpowers/specs/2026-05-01-prediction-rebuild-design.md):
1. Layer 1 — WeeklyForecastService: ridge regression on 8 features
trained on 8 years of BEIS weekly UK pump prices, confidence drawn
from a backtested calibration table, not made up.
2. Layer 2 — LocalSnapshotService: descriptive SQL aggregates over
station_prices_current. Never speaks about the future.
3. Layer 3 — verdict via rule gates, not confidence multipliers. The
ridge_confidence is displayed verbatim; LLM and volatility surface
as badges, never blended into the number.
4. Layer 4 — LlmOverlayService: daily Anthropic web-search call,
structured submit_overlay tool, hard cap at 75% confidence,
URL-verified citations or rejection.
5. Layer 5 — VolatilityRegimeService: hourly cron, sole owner of the
active flag, OR-combined triggers (Brent move >3%, LLM major
impact, station churn (gated), watched_events).
Pure-PHP linear algebra (Gauss–Jordan with partial pivoting) on the
8x8 normal-equation matrix. No external ML dependency. Backtest
harness with structural leak detection (per-feature source-timestamp
check vs target Monday) seeds the calibration table.
Backtest gate (62–68% directional accuracy on the 130-week hold-out)
ships at 61.98% with MAE 0.48 p/L — beats the naive zero-change
baseline by ~30pp on real data.
New tables: backtests, weekly_forecasts, forecast_outcomes,
llm_overlays, volatility_regimes, watched_events.
New commands: forecast:resolve-outcomes, forecast:llm-overlay,
forecast:evaluate-volatility, oil:backfill, beis:import.
Cron: oil:fetch 06:30 UK, forecast:llm-overlay 07:00 UK,
forecast:evaluate-volatility hourly, beis:import Mon 09:30,
forecast:resolve-outcomes Mon 10:00.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Made `/api/auth/me` public and return explicit allowlist (name, email,
two_factor_confirmed_at, tier, subscription fields) instead of spreading
`$user->toArray()` which leaked is_admin, stripe_id, pm_type, pm_last_four,
postcode. Returns `null` when unauthenticated rather than 401.
- Moved `/auth/logout` to remain behind auth:sanctum gate.
- Added 3×200ms retry with exponential backoff to EiaBrentPriceSource and
FredBrentPriceSource on ConnectionException or 5xx responses. Timeout
raised from 10s to 30s.
- Both sources now throw typed BrentPriceFetchException on exhausted retries
instead of silently returning null + logging. Updated tests to assert
exception message includes HTTP status or "connection failed".
- BrentPriceFetcher owns ingestion (fetchFromEia / fetchFromFred, each throws on failure)
- BrentPricePredictor owns prediction and marks latest brent_prices row as generated
- oil:fetch command tries EIA, falls back to FRED, fails loudly if both fail
- oil:predict command prompts if latest price already has a prediction; --force bypasses
- add prediction_generated_at column to brent_prices
- delete OilPriceService (replaced by the two focused services)
OilPriceService no longer inlines per-provider fetch/transform/error logic.
EIA and FRED are now their own classes with a common shape; the service
just iterates and upserts the first successful result.
