<?php
/**
 * Shadow-automation ledger recorder.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Ledger;

use AgentFirewall\Policy\ActionDescriptor;
use DateTimeImmutable;

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

/**
 * Records application-password writes to the ledger (BUG-1, MCP09).
 *
 * Such writes carry no agent identity and cannot be governed by policy; in
 * default (non-strict) mode they proceed, and the readme promises they are
 * "flagged". This listener is that flag: each one becomes an 'untracked'
 * ledger row - agent id 0 as the no-agent sentinel (the column is NOT NULL),
 * the acting WP user, and the route-derived action shape - appended through
 * LedgerWriter so it joins the hash chain and `wp agent-firewall verify`
 * still passes. The guard fires only for write methods, and ledger
 * retention applies to these rows like any other.
 */
final class ShadowAutomationRecorder {

	/**
	 * Ledger status for writes that bypassed agent identity.
	 */
	public const STATUS = 'untracked';

	/**
	 * Constructor.
	 *
	 * @param LedgerWriter $writer Chained ledger writer.
	 */
	public function __construct( private readonly LedgerWriter $writer ) {
	}

	/**
	 * Subscribe to the shadow-automation event.
	 */
	public function register(): void {
		add_action( 'adaf_shadow_automation', array( $this, 'record' ), 10, 4 );
	}

	/**
	 * Append the write to the ledger.
	 *
	 * Method and params default conservatively for any caller still firing
	 * the action's original two-argument form.
	 *
	 * @param string               $route      REST route.
	 * @param int                  $wp_user_id Authenticated user.
	 * @param string               $method     HTTP method.
	 * @param array<string, mixed> $params     Request parameters.
	 */
	public function record( string $route, int $wp_user_id, string $method = 'POST', array $params = array() ): void {
		$action = ActionDescriptor::from_rest( $method, $route, $params );

		try {
			$this->writer->append(
				array(
					'ts'           => new DateTimeImmutable( 'now' ),
					'agent_id'     => 0,
					'wp_user_id'   => $wp_user_id,
					'source'       => $action->source,
					'action_cat'   => $action->action_cat,
					'entity_type'  => $action->entity_type,
					'entity_id'    => $action->entity_id,
					'ability_name' => null,
					'status'       => self::STATUS,
					'input'        => $action->input,
					'result'       => null,
					'policy_id'    => null,
					'rule_index'   => null,
				)
			);
		} catch ( LedgerUnavailable $busy ) {
			// What this row records has already happened, so failing the
			// request would not undo it. The row is skipped, as it was before
			// ADR-17 whenever an insert failed.
			return;
		}
	}
}