<?php
/**
 * Announces holds whose AI review never came.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Pending;

use AgentFirewall\Repository\AgentRepository;
use AgentFirewall\Repository\LedgerRepository;
use AgentFirewall\Repository\PendingRepository;
use Closure;
use DateTimeImmutable;

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

/**
 * The safety net under the Pro AI evaluator (AF-21.4, ADR-15 §5).
 *
 * A hold the evaluator was to review first is not announced when it is
 * made. If no review has come fifteen minutes later - the review event was
 * lost, cron is not running, the evaluator was switched off, or the site
 * now runs the free build without the evaluator at all - the hold is
 * marked as no longer waiting and announced to a human, exactly as any
 * hold is. Core rather than premium for that last reason: no hold may
 * wait silently because the code that was to review it is gone.
 */
final class AiReviewTimeout {

	/**
	 * Seconds a hold waits for its AI review before a human is told.
	 */
	public const AFTER = 900;

	/**
	 * Holds looked at per sweep.
	 */
	public const LIMIT = 200;

	/**
	 * The clock.
	 *
	 * @var Closure(): DateTimeImmutable
	 */
	private Closure $now;

	/**
	 * Constructor.
	 *
	 * @param PendingRepository                   $pending Holds.
	 * @param LedgerRepository                    $ledger  Ledger.
	 * @param AgentRepository                     $agents  Agents.
	 * @param (Closure(): DateTimeImmutable)|null $now     Clock.
	 */
	public function __construct(
		private readonly PendingRepository $pending,
		private readonly LedgerRepository $ledger,
		private readonly AgentRepository $agents,
		?Closure $now = null
	) {
		$this->now = $now ?? static fn (): DateTimeImmutable => new DateTimeImmutable( 'now' );
	}

	/**
	 * Ride the hourly expiry sweep, after the backlog check (priority 20).
	 */
	public function register(): void {
		add_action( ExpiryCron::HOOK, array( $this, 'sweep' ), 25 );
	}

	/**
	 * The cron callback.
	 */
	public function sweep(): void {
		$this->run();
	}

	/**
	 * Announce every hold that has waited too long for its AI review.
	 *
	 * @return int How many were announced or marked.
	 */
	public function run(): int {
		$cutoff = ( $this->now )()->getTimestamp() - self::AFTER;
		$count  = 0;

		foreach ( $this->pending->list_awaiting_ai( self::LIMIT ) as $listed ) {
			if ( $listed['held_at']->getTimestamp() > $cutoff ) {
				continue;
			}

			$hold   = $listed['pending'];
			$entry  = $this->ledger->find( $hold->ledger_id );
			$result = $entry->result ?? array();
			if ( null === $entry || true !== ( $result['awaits_ai'] ?? null ) || isset( $result['ai_verdict'] ) ) {
				continue;
			}

			// Marked first, so a review that arrives late finds the hold no
			// longer waiting and leaves it to the human now told about it.
			$this->ledger->update_result(
				$entry->id,
				array_merge(
					$result,
					array(
						'awaits_ai'        => false,
						'review_timed_out' => true,
					)
				)
			);
			++$count;

			$agent = $this->agents->find_by_id( $entry->agent_id );
			if ( null !== $agent ) {
				// Documented in InterceptionPipeline: a human must act.
				do_action(
					'adaf_action_pending',
					$hold->id,
					$agent,
					$entry->action( $hold->stored_input ),
					$entry->id,
					false
				);
			}
		}

		return $count;
	}
}