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/Forecasting/WeeklyPumpPriceLoader.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace App\Services\Forecasting;
+
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Loads `weekly_pump_prices` once into an in-memory map keyed by date.
+ *
+ * Used by features and the ridge model — avoids one SELECT per
+ * (week × feature) lookup. Lazy: nothing loads until first query.
+ */
+final class WeeklyPumpPriceLoader
+{
+    /** @var array<string, object{date: string, ulsp_pence: int, ulsd_pence: int}>|null */
+    private ?array $byDate = null;
+
+    public function ulspPence(string $date): ?int
+    {
+        $row = $this->byDate()[$date] ?? null;
+
+        return $row === null ? null : (int) $row->ulsp_pence;
+    }
+
+    public function ulsdPence(string $date): ?int
+    {
+        $row = $this->byDate()[$date] ?? null;
+
+        return $row === null ? null : (int) $row->ulsd_pence;
+    }
+
+    /** @return array<int, string> Sorted ascending. */
+    public function allDates(): array
+    {
+        return array_keys($this->byDate());
+    }
+
+    /** @return array<string, object{date: string, ulsp_pence: int, ulsd_pence: int}> */
+    private function byDate(): array
+    {
+        if ($this->byDate !== null) {
+            return $this->byDate;
+        }
+
+        $rows = DB::table('weekly_pump_prices')
+            ->orderBy('date')
+            ->get(['date', 'ulsp_pence', 'ulsd_pence']);
+
+        $map = [];
+        foreach ($rows as $r) {
+            $map[(string) $r->date] = $r;
+        }
+
+        $this->byDate = $map;
+
+        return $map;
+    }
+}