<?php
/**
 * What an extension supplies for its own entity types (ADR-18 §5).
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Extension;

use AgentFirewall\Policy\ActionDescriptor;
use DateTimeImmutable;

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

/**
 * Drift, snapshot, undo and reversibility for one entity type the core
 * does not know - an order, a refund, a product.
 *
 * The core calls these before its own post-based paths. Any method may
 * throw; the core treats a throw as the safe answer for that question:
 * drift, no snapshot, a failed restore, not reversible.
 *
 * Every method receives the action as the ledger stores it
 * (ActionDescriptor::as_stored()): source, category, target, ability,
 * input and facts, but no route, replay envelope or destructive
 * declaration. That is all approval and undo can rebuild, so a provider
 * reads the same action when it is held as when it is approved or undone.
 */
interface EntityProvider {

	/**
	 * When the target was last modified, or null when it has no such time.
	 * Read when an action is held and again when it is approved; a
	 * difference is drift. Compared to the second, so an edit within the
	 * same second needs drift_fingerprint() to be seen.
	 *
	 * @param ActionDescriptor $action The action.
	 */
	public function modified_at( ActionDescriptor $action ): ?DateTimeImmutable;

	/**
	 * A string that changes whenever the fields the action depends on do -
	 * an order's status and totals, say - or null for none. Compared like
	 * modified_at(), for changes that do not move a timestamp. The core
	 * stores only its SHA-256.
	 *
	 * @param ActionDescriptor $action The action.
	 */
	public function drift_fingerprint( ActionDescriptor $action ): ?string;

	/**
	 * The target's before-state, captured just before the action runs, or
	 * null when there is nothing to capture. It must be JSON-encodable;
	 * restore() receives it back.
	 *
	 * @param ActionDescriptor $action The action.
	 * @return array<string, mixed>|null
	 */
	public function snapshot( ActionDescriptor $action ): ?array;

	/**
	 * Undo the action from its snapshot. Called only for an action
	 * reversibility() calls reversible.
	 *
	 * @param ActionDescriptor     $action The action being undone.
	 * @param array<string, mixed> $before What snapshot() captured.
	 * @return array<string, mixed>|\WP_Error What was restored, or why not.
	 */
	public function restore( ActionDescriptor $action, array $before ): array|\WP_Error;

	/**
	 * Whether the action can be taken back, and what it does beyond its
	 * target. Undo, and the AI evaluator's approvals, require reversible.
	 * Reversible with no snapshot is offered as undoable and then refused,
	 * so a provider that cannot snapshot an action should not call it
	 * reversible.
	 *
	 * @param ActionDescriptor $action The action.
	 */
	public function reversibility( ActionDescriptor $action ): Reversibility;
}