<?php
/**
 * Launch mutation scheduler contract.
 *
 * @package ScheduledChanges
 */

namespace ScheduledChanges\Scheduler;

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

/**
 * Queues and cancels lifecycle mutations through one scheduler contract.
 */
interface LaunchMutationScheduler {
	/**
	 * Schedules an immutable launch version.
	 */
	public function schedule(
		int $version_id,
		UtcTimestamp $scheduled_at,
		string $trigger = TriggerSource::SCHEDULED
	): int;

	/**
	 * Queues an immutable launch version for immediate execution.
	 */
	public function runNow( int $version_id, ?UtcTimestamp $occurrence_at = null ): int;

	/**
	 * Queues a retry for a terminal source run.
	 *
	 * @return array{source_run_id:int,launch_version_id:int,action_scheduler_id:int,attempt_number:int,occurrence_at_utc:string}
	 */
	public function manualRetry( int $source_run_id, int $actor_id, ?int $expected_launch_id = null ): array;

	/**
	 * Cancels a scheduled immutable launch version.
	 */
	public function cancel( int $version_id, int $actor_id ): int;
}
