<?php

namespace App\Services\Forecasting\Contracts;

use App\Services\Forecasting\FeatureSpec;
use App\Services\Forecasting\WeeklyPrediction;
use Carbon\CarbonInterface;

/**
 * Contract every weekly forecaster must satisfy. The harness consumes
 * this interface — naive baselines, ridge regression, and any future
 * model all implement it.
 */
interface WeeklyForecastModel
{
    public function featureSpec(): FeatureSpec;

    /**
     * Train on the supplied weeks. Implementations may store coefficients
     * internally for the subsequent predict() calls.
     *
     * @param  array<int, CarbonInterface>  $trainingMondays
     */
    public function train(array $trainingMondays): void;

    /**
     * Predict ΔULSP for the week starting $targetMonday. Returned value
     * is in pence × 100 (integer-ish, but typed float for fractional
     * predictions).
     */
    public function predict(CarbonInterface $targetMonday): WeeklyPrediction;

    /**
     * Coefficients in a JSON-serialisable form, or null for non-parametric
     * models like the naive baseline.
     *
     * @return array<string, mixed>|null
     */
    public function coefficients(): ?array;
}