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>
The DispatchUserNotificationJob has been logging sent=true for every
allowed channel without actually sending anything — a TODO marker covered
by the existing test suite, which only asserted log rows. The downstream
"missed today" widget read those rows and reported falsely. This commit
makes the telemetry truthful by wiring the real send.
- App\Notifications\FuelPriceAlert — Notification class with via() that
returns the per-tier-filtered channel list passed in by the dispatcher.
Implements toMail / toOneSignal / toVonageWhatsApp / toVonageSms.
ShouldQueue on the 'notifications' queue.
- App\Notifications\Channels\OneSignalChannel — raw HTTP to OneSignal
REST API, gated on services.onesignal.{app_id,api_key} + user
push_token. Logs every call to api_logs via ApiLogger.
- App\Notifications\Channels\VonageWhatsAppChannel — raw HTTP to Vonage
Messages API, gated on whatsapp_verified_at + whatsapp_number.
- App\Notifications\Channels\VonageSmsChannel — raw HTTP to Vonage SMS
API, gated on whatsapp_number.
- DispatchUserNotificationJob now calls $user->notify(new
FuelPriceAlert(...)) before logging.
- New tests: assert the notification IS dispatched with the right
channels, and that nothing is dispatched when no channels are allowed.
Channels gracefully no-op when their credentials are unset (logging at
info level), so existing tests without a Notification::fake() still
pass — the channels just early-return on missing config.
No new composer dependencies — Vonage SDK avoided in favour of raw HTTP
through the existing ApiLogger pattern.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds `VerifyApiKey` middleware protecting all API routes with `X-Api-Key` header validation. Wraps `/api/stations`, `/api/stats/searches`, and `/api/prediction` in throttled middleware group (60 req/min). Updates StationSearchTest to use `RefreshDatabase`, adds `meta` assertion checks, and validates `fuel_type` in HTTP request assertions. Removes auth routes from API docs and replaces with API key authentication instructions. Adds `api_secret_key` config option.
- New method uses web_search_20260209 server-side tool so Claude fetches
48h of oil/geopolitical news autonomously before predicting direction
- Prompt uses raw prices only — no pre-computed EWMA indicators
- pause_turn loop handles server-side search continuation (up to 5 iters)
- generatePrediction() now tries context method first, falls back to
generateLlmPrediction(), then EWMA
- Default model updated to claude-sonnet-4-6
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
