<?php
/**
 * Runs a write the core cannot re-send (ADR-18 §5).
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Extension;

use AgentFirewall\Policy\ActionDescriptor;

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

/**
 * The other half of Api::hold_at_effect(): a write an extension caught at an
 * effect hook - a refund inside WooCommerce's own code - is held with an
 * envelope the extension built, and on approval the core hands that
 * envelope back here to run.
 *
 * replay() runs as the agent's linked WordPress user, after the core's
 * at-most-once claim, expiry check and drift check, so it must check that
 * user's capabilities as the original code path would. It is called at
 * most once per hold. A throw is treated as a run that may have taken
 * effect: the hold is closed as interrupted, never run again.
 *
 * The envelope is stored in the clear until the hold is decided, so it
 * should name what to do - an order, an amount - and never carry a secret
 * such as a gateway token or card data.
 */
interface ReplayProvider {

	/**
	 * Carry out a held write.
	 *
	 * @param ActionDescriptor     $action   The held action, as the ledger stores it.
	 * @param array<string, mixed> $envelope What the extension passed to hold_at_effect().
	 * @return array<string, mixed>|\WP_Error What was done, or why not.
	 */
	public function replay( ActionDescriptor $action, array $envelope ): array|\WP_Error;
}