<?php
/**
 * Where the ledger's chain fails verification, and why (AF-24.6).
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Ledger;

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

/**
 * The first entry that fails verification, and what is wrong with it.
 *
 * Rows written since AF-24.5 name the row they follow, outside the hash, so
 * the link catches nothing the hash does not: anyone able to rewrite the
 * hashes can rewrite the links. What it adds is the difference between an
 * entry that was changed and entries removed or inserted around it, which
 * tells an administrator where to look.
 */
final class ChainBreak {

	/**
	 * The entry follows one that is no longer in the ledger.
	 */
	public const REMOVED = 'removed';

	/**
	 * Another entry now sits between this one and the one it follows.
	 */
	public const INSERTED = 'inserted';

	/**
	 * The entry no longer matches its hash.
	 */
	public const CHANGED = 'changed';

	/**
	 * The entry has no hash at all.
	 */
	public const UNHASHED = 'unhashed';

	/**
	 * Constructor.
	 *
	 * @param int      $entry_id First entry that fails verification.
	 * @param string   $reason   One of the constants above.
	 * @param int|null $follows  The entry it names as its predecessor, when it
	 *                           names one and the link was checked.
	 * @param int|null $after    The entry actually before it, for REMOVED and
	 *                           INSERTED.
	 */
	public function __construct(
		public readonly int $entry_id,
		public readonly string $reason,
		public readonly ?int $follows = null,
		public readonly ?int $after = null
	) {
	}

	/**
	 * One sentence saying what happened, for the alert, the webhook and the
	 * command line.
	 */
	public function describe(): string {
		switch ( $this->reason ) {
			case self::REMOVED:
				return sprintf(
					/* translators: 1: ledger entry id, 2: id of the entry it was recorded after. */
					__( 'Entries were removed before entry #%1$d: it was recorded right after entry #%2$d, which is no longer in the ledger.', 'agentic-daisy-ai-agent-firewall' ),
					$this->entry_id,
					(int) $this->follows
				);
			case self::INSERTED:
				return sprintf(
					/* translators: 1: ledger entry id, 2: id of the entry it was recorded after, 3: id of the entry now between them. */
					__( 'An entry was inserted before entry #%1$d, or its link was changed: it was recorded right after entry #%2$d, but entry #%3$d now sits between them.', 'agentic-daisy-ai-agent-firewall' ),
					$this->entry_id,
					(int) $this->follows,
					(int) $this->after
				);
			case self::UNHASHED:
				return sprintf(
					/* translators: %d: ledger entry id. */
					__( 'Entry #%d has no chain hash: it was written or changed outside the plugin.', 'agentic-daisy-ai-agent-firewall' ),
					$this->entry_id
				);
		}

		return null === $this->follows
			? sprintf(
				/* translators: %d: ledger entry id. */
				__( 'Entry #%d no longer matches its hash: it or the entry before it was changed, or entries before it were removed.', 'agentic-daisy-ai-agent-firewall' ),
				$this->entry_id
			)
			: sprintf(
				/* translators: %d: ledger entry id. */
				__( 'Entry #%d no longer matches its hash: it or the entry before it was changed after it was recorded.', 'agentic-daisy-ai-agent-firewall' ),
				$this->entry_id
			);
	}
}