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

declare(strict_types=1);

namespace AgentFirewall\Policy;

defined( 'ABSPATH' ) || exit;

/**
 * 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 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';

	/**
	 * 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.
	 */
	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
	) {
	}

	/**
	 * 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 {
		return self::REASON_RATE_LIMITED === $this->reason;
	}
}