<?php

namespace App\Services\Forecasting\Contracts;

use Carbon\CarbonInterface;

/**
 * A single feature in a weekly forecast model.
 *
 * Implementations must be deterministic for a given target Monday and
 * must declare every source date they read so the LeakDetector can
 * verify no source date is on or after the target Monday.
 */
interface ForecastFeature
{
    public function name(): string;

    /**
     * Feature value at $targetMonday, or null when an upstream data
     * row is missing. Caller is expected to drop the entire feature
     * vector when any single feature is null.
     */
    public function valueFor(CarbonInterface $targetMonday): ?float;

    /**
     * Every date this feature reads from any data source for a given
     * target Monday. The LeakDetector requires every returned date to
     * be strictly before $targetMonday.
     *
     * @return array<int, CarbonInterface>
     */
    public function sourceDates(CarbonInterface $targetMonday): array;
}