<?php
/**
 * Launch repository contract.
 *
 * @package ScheduledChanges
 */

namespace ScheduledChanges\Repository;

use ScheduledChanges\Domain\Launch\Launch;
use ScheduledChanges\Domain\Shared\UtcTimestamp;
use ScheduledChanges\Domain\Shared\Uuid;

/**
 * Storage port retained for wpdb and deterministic test implementations.
 * Persists launch aggregates. Finders return `null` for not-found; write and
 * integrity failures throw `RepositoryException`.
 */
interface LaunchRepository {
	/**
	 * Inserts a launch and returns its internal ID.
	 *
	 * @param Launch $launch Launch to create.
	 */
	public function create( Launch $launch ): int;

	/**
	 * Finds a launch by public UUID.
	 *
	 * @param Uuid $uuid Public launch UUID.
	 */
	public function findByUuid( Uuid $uuid ): ?Launch;

	/**
	 * Finds a launch by internal ID.
	 *
	 * @param int $id Internal launch ID.
	 */
	public function findById( int $id ): ?Launch;

	/**
	 * Marks a launch scheduled against one immutable version.
	 *
	 * @param int          $id Launch ID.
	 * @param int          $version_id Immutable version ID.
	 * @param UtcTimestamp $start_at Scheduled execution time.
	 */
	public function markScheduled( int $id, int $version_id, UtcTimestamp $start_at ): void;

	/**
	 * Points a draft launch at its current immutable version.
	 *
	 * @param int $id Launch ID.
	 * @param int $version_id Immutable version ID.
	 */
	public function setCurrentVersion( int $id, int $version_id ): void;

	/**
	 * Updates execution lifecycle state.
	 *
	 * @param int               $id Launch ID.
	 * @param string            $status New lifecycle state.
	 * @param UtcTimestamp|null $completed_at Completion time for terminal states.
	 */
	public function updateStatus( int $id, string $status, ?UtcTimestamp $completed_at = null ): void;

	/**
	 * Deletes a launch by UUID.
	 *
	 * Used by fixtures and explicit data-management workflows only.
	 *
	 * @param Uuid $uuid Public launch UUID.
	 */
	public function deleteByUuid( Uuid $uuid ): bool;
}
