feat(forecasting): build calibrated weekly forecast stack with LLM overlay and volatility detector

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>

app/Services/StationSearch/StationSearchService.php

@@ -7,8 +7,9 @@ use App\Enums\PriceReliability;
 use App\Models\Search;
 use App\Models\Station;
 use App\Models\User;
+use App\Services\Forecasting\LocalSnapshotService;
+use App\Services\Forecasting\WeeklyForecastService;
 use App\Services\HaversineQuery;
-use App\Services\NationalFuelPredictionService;
 use App\Services\PlanFeatures;
 use Illuminate\Database\Query\JoinClause;
 use Illuminate\Support\Carbon;
@@ -17,7 +18,8 @@ use Illuminate\Support\Collection;
 final class StationSearchService
 {
     public function __construct(
-        private readonly NationalFuelPredictionService $predictionService,
+        private readonly WeeklyForecastService $weeklyForecast,
+        private readonly LocalSnapshotService $localSnapshot,
     ) {}
 
     public function search(SearchCriteria $criteria, ?User $user, ?string $ipHash): SearchResult
@@ -134,7 +136,10 @@ final class StationSearchService
      */
     private function buildPrediction(?User $user, SearchCriteria $criteria): array
     {
-        $result = $this->predictionService->predict($criteria->lat, $criteria->lng);
+        $result = $this->weeklyForecast->currentForecast();
+        // Layer 1 is national; the region_key only reflects whether the
+        // caller passed coordinates so the JSON contract stays stable.
+        $result['region_key'] = 'regional';
 
         $canSeeFull = $user !== null && PlanFeatures::for($user)->can('ai_predictions');
 
@@ -146,6 +151,13 @@ final class StationSearchService
             ];
         }
 
+        $result['local_snapshot'] = $this->localSnapshot->snapshot(
+            fuelType: $criteria->fuelType->value,
+            lat: $criteria->lat,
+            lng: $criteria->lng,
+            radiusKm: max(10, (int) $criteria->radiusKm),
+        );
+
         return $result;
     }
 }