<?php
/**
 * Action Scheduler gateway.
 *
 * @package ScheduledChanges
 */

namespace ScheduledChanges\Scheduler;

use ScheduledChanges\Domain\Run\TriggerSource;
use ScheduledChanges\Domain\Shared\UtcTimestamp;

/**
 * Narrow adapter port used to enqueue and inspect actions. It intentionally
 * supports alternate queue implementations and deterministic memory fixtures.
 */
interface ActionSchedulerGateway {
	public function available(): bool;

	/**
	 * @throws \InvalidArgumentException When the scheduled action payload is invalid.
	 * @throws \RuntimeException When Action Scheduler cannot create the action.
	 */
	public function schedule(
		int $version_id,
		UtcTimestamp $scheduled_at,
		string $trigger,
		int $attempt_number,
		bool $unique = true,
		?UtcTimestamp $occurrence_at = null,
		int $execution_actor_id = 0
	): int;

	/**
	 * @throws \InvalidArgumentException When the immediate action payload is invalid.
	 * @throws \RuntimeException When Action Scheduler cannot create the action.
	 */
	public function enqueueNow(
		int $version_id,
		UtcTimestamp $occurrence_at,
		string $trigger,
		int $attempt_number,
		bool $unique = true,
		int $execution_actor_id = 0
	): int;

	/**
	 * @throws \RuntimeException When Action Scheduler cannot inspect or cancel actions.
	 */
	public function cancelVersion( int $version_id, ?int $except_action_id = null ): int;

	/**
	 * Cancels one exact Action Scheduler action created by the caller.
	 */
	public function cancelAction( int $action_id ): bool;

	/**
	 * Returns pending/running launch callback identities for repair diagnostics.
	 *
	 * @return array<int,array{action_scheduler_id:int,version_id:int,occurrence_at_utc:string,attempt_number:int,trigger_source:string,status:string}>
	 * @throws \RuntimeException When Action Scheduler cannot inspect actions.
	 */
	public function scheduledLaunchActions(): array;

	/**
	 * @return array{pending:int,running:int,failed:int,complete:int,overdue:int}
	 * @throws \RuntimeException When queue counts cannot be inspected.
	 */
	public function counts(): array;
}
