<?php
/**
 * Policy evaluation result.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Policy;

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

/**
 * A decision plus why it was reached. The reason distinguishes denials an
 * agent should stop retrying (policy, scope) from ones that clear on their
 * own (rate limiting), which is the difference between a useful error and a
 * retry loop.
 */
final class Evaluation {

	/**
	 * Denial because a rule said so.
	 */
	public const REASON_POLICY = 'policy';

	/**
	 * Denial because the agent exceeded a rate limit.
	 */
	public const REASON_RATE_LIMITED = 'rate_limited';

	/**
	 * Denial because the action would take the agent over a budget: the sum
	 * of a fact over a window (ADR-18 §6). Older spending ages out of the
	 * window, so waiting clears it - unless the action alone is larger than
	 * the whole budget, which retry_after (null) says.
	 */
	public const REASON_BUDGET = 'budget_exceeded';

	/**
	 * Denial because the action falls outside the token's scopes.
	 */
	public const REASON_OUT_OF_SCOPE = 'out_of_scope';

	/**
	 * Denial because an administrator engaged the kill switch.
	 */
	public const REASON_LOCKDOWN = 'lockdown';

	/**
	 * Denial because the agent addressed the firewall's own control plane,
	 * which is the human surface and closed to agents entirely (AF-12.14).
	 */
	public const REASON_CONTROL_PLANE = 'control_plane';

	/**
	 * Denial because the action would need approval but was caught at an
	 * effect hook, where the write is already in flight and cannot be held
	 * and re-executed later (AF-13.3).
	 */
	public const REASON_APPROVAL_UNAVAILABLE = 'approval_unavailable';

	/**
	 * Denial because the ledger could not record the action: every attempt
	 * lost to a concurrent write (ADR-17). Nothing unrecorded may run, and
	 * the contention passes in moments.
	 */
	public const REASON_LEDGER_BUSY = 'ledger_busy';

	/**
	 * Denial because an administrator-run agent addressed the firewall's own
	 * plugin or options (AF-25.15, ADR-18 §9).
	 */
	public const REASON_FIREWALL_PROTECTED = 'firewall_protected';

	/**
	 * The denial reasons worth waking someone for: an agent reaching
	 * somewhere it was never provisioned for. A denial by a policy the site
	 * owner wrote is the firewall working as designed, and an agent in a loop
	 * generates those faster than anyone can read them. Rate-limit denials
	 * have their own alert. Shared by the webhook and the digest.
	 */
	public const NOTABLE_REASONS = array(
		self::REASON_OUT_OF_SCOPE,
		self::REASON_LOCKDOWN,
		self::REASON_CONTROL_PLANE,
		self::REASON_FIREWALL_PROTECTED,
	);

	/**
	 * Constructor.
	 *
	 * Provenance answers "which rule decided this", which a bare decision
	 * cannot. Both are null when no rule matched and the built-in defaults
	 * applied.
	 *
	 * @param Decision    $decision   Policy decision.
	 * @param string|null $reason     Denial reason, null when not denied.
	 * @param int|null    $policy_id  Policy that decided, null for a default.
	 * @param int|null    $rule_index Position of the deciding rule in that policy.
	 * @param int|null    $retry_after Seconds until a retry could succeed.
	 * @param bool        $ai_triage   Whether the deciding rule said
	 *                                 EVALUATE_AI. The decision is still
	 *                                 REQUIRE_APPROVAL - the core never
	 *                                 stops degrading it - but the Pro
	 *                                 evaluator may review the hold
	 *                                 (ADR-15 §1).
	 * @param bool        $network     Whether a network rule decided, on a
	 *                                 multisite network (ADR-16 §2). The
	 *                                 policy id is then null and the rule
	 *                                 index is the network rule's.
	 * @param array<string, mixed>|null $limit_rule The rule whose rate limit
	 *                                 denied, for the anomaly alert the
	 *                                 caller raises once the denial is
	 *                                 recorded (ADR-17).
	 * @param bool        $unresolved  Whether the deciding rule fired on a
	 *                                 condition that could not be
	 *                                 evaluated (ADR-18 §4).
	 * @param bool        $over_budget Whether the deciding rule fired
	 *                                 because the action would exceed its
	 *                                 budget (ADR-18 §6).
	 * @param string|null $extension   The extension whose default rule
	 *                                 decided (AF-25.10). The policy id is
	 *                                 then null and the rule index is the
	 *                                 rule's among that extension's defaults.
	 * @param bool        $admin_guard Whether the guard on administrator-run
	 *                                 agents raised the decision (AF-25.15).
	 */
	public function __construct(
		public readonly Decision $decision,
		public readonly ?string $reason = null,
		public readonly ?int $policy_id = null,
		public readonly ?int $rule_index = null,
		public readonly ?int $retry_after = null,
		public readonly bool $ai_triage = false,
		public readonly bool $network = false,
		public readonly ?array $limit_rule = null,
		public readonly bool $unresolved = false,
		public readonly bool $over_budget = false,
		public readonly ?string $extension = null,
		public readonly bool $admin_guard = false
	) {
	}

	/**
	 * Whether a stored rule decided, rather than the built-in defaults.
	 */
	public function matched_a_rule(): bool {
		return null !== $this->policy_id;
	}

	/**
	 * Whether waiting and retrying could succeed.
	 */
	public function is_retryable(): bool {
		if ( self::REASON_BUDGET === $this->reason ) {
			return null !== $this->retry_after;
		}

		return self::REASON_RATE_LIMITED === $this->reason || self::REASON_LEDGER_BUSY === $this->reason;
	}
}