<?php
/**
 * Emergency kill switch.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Policy;

defined( 'ABSPATH' ) || exit;

/**
 * Option-backed emergency switch ("kill switch"). While engaged, the
 * interception pipeline denies every agent action — reads included —
 * before scope or policy evaluation runs, with its own denial reason.
 *
 * A hard deny rather than hold-for-approval on purpose: mid-incident, a
 * runaway agent must not flood the approval queue, and denials still land
 * in the ledger so nothing escapes the audit trail. The switch only gates
 * agent-token traffic; the plugin's own admin routes are exempt from agent
 * gating, so a human can always reach the dashboard to release it.
 */
final class Lockdown {

	/**
	 * Option storing the switch as '1'/'0'.
	 */
	public const OPTION = 'adaf_lockdown';

	/**
	 * Whether the switch is engaged. Anything but an exact '1' is
	 * disengaged, so a corrupted value cannot wedge the site into either
	 * state ambiguously.
	 */
	public function engaged(): bool {
		return $this->site_engaged() || $this->network_engaged();
	}

	/**
	 * Whether this site's own switch is engaged.
	 */
	public function site_engaged(): bool {
		$value = get_option( self::OPTION, '0' );

		return is_scalar( $value ) && '1' === (string) $value;
	}

	/**
	 * Whether the network administrator engaged the switch for every site
	 * of a multisite network (ADR-16 §3). A site administrator cannot
	 * release it: release() clears only this site's own switch.
	 */
	public function network_engaged(): bool {
		/**
		 * Filters whether a network-wide lockdown is engaged.
		 *
		 * Nothing answers it in the free build or on a single site; the
		 * Agency network layer answers true while its switch is engaged.
		 *
		 * @param bool $engaged Whether the network lockdown is engaged. Default false.
		 */
		return true === apply_filters( 'adaf_network_lockdown', false );
	}

	/**
	 * Engage the switch: deny all agent actions until released.
	 */
	public function engage(): void {
		update_option( self::OPTION, '1' );
	}

	/**
	 * Release this site's switch. Normal evaluation resumes unless the
	 * network's switch is engaged too.
	 */
	public function release(): void {
		update_option( self::OPTION, '0' );
	}
}