<?php
/**
 * Budget meter.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Policy;

use AgentFirewall\Repository\LedgerRepository;
use DateTimeImmutable;

defined( 'ABSPATH' ) || exit; // @codeCoverageIgnore

/**
 * Measures a rule's budget: the sum of a fact over an agent's rows in a
 * sliding window, plus this action's value, against a maximum (ADR-18 §6).
 *
 * Backed by the ledger, as the rate limiter is, and counting the same rows:
 * allowed, pending, bypassed and interrupted. A hold therefore spends budget
 * while it waits, and a rejected or expired one, which becomes denied, gives
 * it back. The evaluator runs inside the ADR-17 append, so concurrent
 * requests see each other's rows and cannot overspend.
 */
final class BudgetMeter {

	/**
	 * Longest budget window, a year and a day in seconds. Longer windows
	 * would make every measurement read a site's whole history, and a large
	 * enough one wraps the date arithmetic into the future.
	 */
	public const MAX_WINDOW = 366 * 86400;

	/**
	 * Most rows one measurement reads. A window holding more is not
	 * measured, and an unmeasured budget fires its rule: a partial sum
	 * would undercount.
	 */
	public const MAX_ROWS = 5000;

	/**
	 * Constructor.
	 *
	 * @param LedgerRepository $ledger Ledger repository.
	 */
	public function __construct( private readonly LedgerRepository $ledger ) {
	}

	/**
	 * This action's value of a budget's fact, or null when it cannot be
	 * known: absent, from no active extension, not a number or money fact,
	 * not of its declared type, or negative.
	 *
	 * @param ActionDescriptor                    $action  The action.
	 * @param string                              $fact    The budget's fact.
	 * @param array<string, array<string, mixed>> $catalog Facts active extensions declare.
	 */
	public static function value_of( ActionDescriptor $action, string $fact, array $catalog ): int|float|null {
		$type  = $catalog[ $fact ]['type'] ?? null;
		$value = $action->facts[ $fact ] ?? null;

		$typed = 'money' === $type ? is_int( $value )
			: 'number' === $type && ( is_int( $value ) || ( is_float( $value ) && is_finite( $value ) ) );

		// A budget sums costs. A negative one would make room for others,
		// so it is not a value the budget can use.
		return $typed && $value >= 0 ? $value : null;
	}

	/**
	 * Whether this action takes the agent over the budget, and if so how
	 * long until enough of the window's spending ages out for it to fit;
	 * null when the window cannot be read in full.
	 *
	 * The hint is null when the action alone exceeds the budget: no wait
	 * lets it through. Otherwise it is never less than one second. Negative
	 * stored values spend nothing.
	 *
	 * @param int                                              $agent_id Acting agent.
	 * @param array{fact: string, max: int|float, window: int} $budget   The rule's budget.
	 * @param int|float                                        $value    This action's value.
	 * @param DateTimeImmutable                                $now      Reference time.
	 * @return array{over: bool, retry_after: int|null}|null
	 */
	public function measure( int $agent_id, array $budget, int|float $value, DateTimeImmutable $now ): ?array {
		$rows = $this->ledger->fact_values_since( $agent_id, $budget['fact'], $now->modify( sprintf( '-%d seconds', $budget['window'] ) ), self::MAX_ROWS );
		if ( null === $rows ) {
			return null;
		}
		$spent = array_sum( array_map( static fn ( array $row ): int|float => max( 0, $row[1] ), $rows ) );

		if ( $spent + $value <= $budget['max'] ) {
			return array(
				'over'        => false,
				'retry_after' => null,
			);
		}

		$retry_after = null;
		if ( $value <= $budget['max'] && array() !== $rows ) {
			// Rows leave the window oldest first, a row still counting
			// through its last second; the first whose leaving makes room is
			// when a retry fits. Once every row has left it surely fits,
			// whatever rounding the running total picked up.
			$last = $rows[ count( $rows ) - 1 ][0];
			foreach ( $rows as list( $at, $amount ) ) {
				$spent -= max( 0, $amount );
				if ( $spent + $value <= $budget['max'] ) {
					$last = $at;
					break;
				}
			}
			$retry_after = max( 1, $last + $budget['window'] + 1 - $now->getTimestamp() );
		}

		return array(
			'over'        => true,
			'retry_after' => $retry_after,
		);
	}
}