<?php
/**
 * What Api::hold_at_effect() decided (ADR-18 §5).
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Extension;

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

/**
 * The answer an extension acts on at its effect hook: veto the write, or let
 * it proceed.
 */
final class EffectOutcome {

	/**
	 * Decisions under which the write runs now.
	 */
	private const PROCEEDS = array( 'ALLOW', 'LOG_ONLY' );

	/**
	 * Constructor.
	 *
	 * @param string|null $decision   The decision, or null when the firewall
	 *                                did not evaluate the write - no agent,
	 *                                or a request already evaluated.
	 * @param string|null $reason     Why: a denial reason, or why it was not
	 *                                evaluated.
	 * @param int|null    $ledger_id  The ledger row, when one was written.
	 * @param int|null    $pending_id The hold, when the write was held.
	 */
	public function __construct(
		public readonly ?string $decision,
		public readonly ?string $reason = null,
		public readonly ?int $ledger_id = null,
		public readonly ?int $pending_id = null
	) {
	}

	/**
	 * Whether the extension must stop the write: it was denied, or held to
	 * run on approval.
	 */
	public function vetoes(): bool {
		return null !== $this->decision && ! in_array( $this->decision, self::PROCEEDS, true );
	}

	/**
	 * Whether the write was held for approval, to be replayed by the
	 * extension's replay provider.
	 */
	public function held(): bool {
		return null !== $this->pending_id;
	}
}