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/Features/DeltaUlsdLag.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace App\Services\Forecasting\Features;
+
+use App\Services\Forecasting\Contracts\ForecastFeature;
+use App\Services\Forecasting\WeeklyPumpPriceLoader;
+use Carbon\CarbonInterface;
+
+/**
+ * ΔULSD at lag L. Cross-fuel signal — diesel often leads/lags petrol
+ * during oil shocks. Same lag semantics as DeltaUlspLag.
+ */
+final class DeltaUlsdLag implements ForecastFeature
+{
+    public function __construct(
+        private readonly WeeklyPumpPriceLoader $loader,
+        public readonly int $lag,
+    ) {}
+
+    public function name(): string
+    {
+        return 'delta_ulsd_lag_'.$this->lag;
+    }
+
+    public function valueFor(CarbonInterface $targetMonday): ?float
+    {
+        [$newer, $older] = $this->dates($targetMonday);
+        $a = $this->loader->ulsdPence($newer->toDateString());
+        $b = $this->loader->ulsdPence($older->toDateString());
+        if ($a === null || $b === null) {
+            return null;
+        }
+
+        return (float) ($a - $b);
+    }
+
+    public function sourceDates(CarbonInterface $targetMonday): array
+    {
+        return $this->dates($targetMonday);
+    }
+
+    /** @return array{0: CarbonInterface, 1: CarbonInterface} */
+    private function dates(CarbonInterface $targetMonday): array
+    {
+        return [
+            $targetMonday->copy()->subDays(7 * ($this->lag + 1)),
+            $targetMonday->copy()->subDays(7 * ($this->lag + 2)),
+        ];
+    }
+}

app/Services/Forecasting/Features/DeltaUlspLag.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Services\Forecasting\Features;
+
+use App\Services\Forecasting\Contracts\ForecastFeature;
+use App\Services\Forecasting\WeeklyPumpPriceLoader;
+use Carbon\CarbonInterface;
+
+/**
+ * ΔULSP at lag L: the change in petrol price that ended L weeks before
+ * the most recent observation, in pence × 100.
+ *
+ * lag=0 → ULSP[t-7d] − ULSP[t-14d]   (1-week momentum)
+ * lag=1 → ULSP[t-14d] − ULSP[t-21d]  (2-week momentum)
+ * lag=3 → ULSP[t-28d] − ULSP[t-35d]  (4-week momentum)
+ *
+ * Source dates are always strictly before the target Monday — the
+ * earliest is target − 7×(lag+1), the older is target − 7×(lag+2).
+ */
+final class DeltaUlspLag implements ForecastFeature
+{
+    public function __construct(
+        private readonly WeeklyPumpPriceLoader $loader,
+        public readonly int $lag,
+    ) {}
+
+    public function name(): string
+    {
+        return 'delta_ulsp_lag_'.$this->lag;
+    }
+
+    public function valueFor(CarbonInterface $targetMonday): ?float
+    {
+        [$newer, $older] = $this->dates($targetMonday);
+        $a = $this->loader->ulspPence($newer->toDateString());
+        $b = $this->loader->ulspPence($older->toDateString());
+        if ($a === null || $b === null) {
+            return null;
+        }
+
+        return (float) ($a - $b);
+    }
+
+    public function sourceDates(CarbonInterface $targetMonday): array
+    {
+        return $this->dates($targetMonday);
+    }
+
+    /** @return array{0: CarbonInterface, 1: CarbonInterface} */
+    private function dates(CarbonInterface $targetMonday): array
+    {
+        return [
+            $targetMonday->copy()->subDays(7 * ($this->lag + 1)),
+            $targetMonday->copy()->subDays(7 * ($this->lag + 2)),
+        ];
+    }
+}

app/Services/Forecasting/Features/IsPreBankHoliday.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Services\Forecasting\Features;
+
+use App\Services\Forecasting\Contracts\ForecastFeature;
+use App\Services\Forecasting\UkBankHolidays;
+use Carbon\CarbonInterface;
+
+/**
+ * 1.0 if any UK bank holiday falls in the 7-day window starting at the
+ * target Monday; 0.0 otherwise.
+ *
+ * Captures pre-holiday demand spikes (Easter, summer, Christmas
+ * weekend). Pure calendar — no DB read, sourceDates is empty.
+ */
+final class IsPreBankHoliday implements ForecastFeature
+{
+    public function name(): string
+    {
+        return 'is_pre_bank_holiday';
+    }
+
+    public function valueFor(CarbonInterface $targetMonday): ?float
+    {
+        return UkBankHolidays::holidayWithin($targetMonday, 7) ? 1.0 : 0.0;
+    }
+
+    public function sourceDates(CarbonInterface $targetMonday): array
+    {
+        return [];
+    }
+}

app/Services/Forecasting/Features/UlspMinusMa8.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Services\Forecasting\Features;
+
+use App\Services\Forecasting\Contracts\ForecastFeature;
+use App\Services\Forecasting\WeeklyPumpPriceLoader;
+use Carbon\CarbonInterface;
+
+/**
+ * Mean-reversion term: gap between the most recent observable ULSP
+ * (target − 7d) and its 8-week trailing mean (target − 7d through
+ * target − 56d, inclusive).
+ *
+ * Empirically this is the single most useful 1-week-ahead feature for
+ * UK pump prices — pump retailers tend to revert to their recent
+ * trailing mean, especially after sudden moves.
+ */
+final class UlspMinusMa8 implements ForecastFeature
+{
+    private const int WINDOW_WEEKS = 8;
+
+    public function __construct(
+        private readonly WeeklyPumpPriceLoader $loader,
+    ) {}
+
+    public function name(): string
+    {
+        return 'ulsp_minus_ma8';
+    }
+
+    public function valueFor(CarbonInterface $targetMonday): ?float
+    {
+        $values = [];
+        foreach ($this->sourceDates($targetMonday) as $d) {
+            $v = $this->loader->ulspPence($d->toDateString());
+            if ($v === null) {
+                return null;
+            }
+            $values[] = (float) $v;
+        }
+
+        $latest = $values[0];
+        $mean = array_sum($values) / count($values);
+
+        return $latest - $mean;
+    }
+
+    public function sourceDates(CarbonInterface $targetMonday): array
+    {
+        $dates = [];
+        for ($w = 1; $w <= self::WINDOW_WEEKS; $w++) {
+            $dates[] = $targetMonday->copy()->subDays(7 * $w);
+        }
+
+        return $dates;
+    }
+}

app/Services/Forecasting/Features/WeekOfYearTrig.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Services\Forecasting\Features;
+
+use App\Services\Forecasting\Contracts\ForecastFeature;
+use Carbon\CarbonInterface;
+use InvalidArgumentException;
+
+/**
+ * Cyclic week-of-year encoding. Two instances expected, one for sin and
+ * one for cos. Together they let the linear model fit a smooth annual
+ * seasonal cycle without a 52-way one-hot expansion.
+ *
+ * This is a pure calendar feature — no DB read. sourceDates is empty,
+ * so the LeakDetector has nothing to validate against.
+ */
+final class WeekOfYearTrig implements ForecastFeature
+{
+    public function __construct(public readonly string $component)
+    {
+        if (! in_array($component, ['sin', 'cos'], true)) {
+            throw new InvalidArgumentException('component must be "sin" or "cos"');
+        }
+    }
+
+    public function name(): string
+    {
+        return 'week_of_year_'.$this->component;
+    }
+
+    public function valueFor(CarbonInterface $targetMonday): ?float
+    {
+        $week = (int) $targetMonday->format('W'); // ISO week number 1..53
+        $angle = 2.0 * M_PI * $week / 52.0;
+
+        return $this->component === 'sin' ? sin($angle) : cos($angle);
+    }
+
+    public function sourceDates(CarbonInterface $targetMonday): array
+    {
+        return [];
+    }
+}