<?php
/**
 * Recording session repository contract.
 *
 * @package ScheduledChanges
 */

namespace ScheduledChanges\Repository;

use ScheduledChanges\Domain\Recording\RecordingCleanupStatus;
use ScheduledChanges\Domain\Recording\RecordingSession;
use ScheduledChanges\Domain\Recording\RecordingSessionStatus;
use ScheduledChanges\Domain\Shared\Uuid;

/**
 * Storage port retained for provider workspaces and deterministic test doubles.
 * Persists Record Changes source/shadow workspaces. Finders return `null` for
 * not-found; write and storage failures throw `RepositoryException`.
 */
interface RecordingSessionRepository {
	public function create( RecordingSession $session ): int;

	public function findByUuid( Uuid $uuid ): ?RecordingSession;

	public function findActiveBySourceIdentity( string $provider_id, string $source_type, string $source_reference ): ?RecordingSession;

	/**
	 * Lookup for numeric native WordPress source IDs.
	 */
	public function findActiveBySourceId( int $source_id ): ?RecordingSession;

	/**
	 * Finds expired active sessions that still need cleanup.
	 *
	 * @param int $limit Maximum sessions to return.
	 * @return RecordingSession[]
	 */
	public function stale( int $limit ): array;

	/**
	 * Persists the latest capture and structured diff.
	 *
	 * @param Uuid                $uuid Recording UUID.
	 * @param array<string,mixed> $current_snapshot Latest workspace snapshot.
	 * @param array<string,mixed> $diff Structured diff.
	 */
	public function updateCapture( Uuid $uuid, array $current_snapshot, array $diff ): void;

	/**
	 * Persists selected changes for finalization.
	 *
	 * @param Uuid                $uuid Recording UUID.
	 * @param array<string,mixed> $selected_changes Selected change payload.
	 */
	public function updateSelectedChanges( Uuid $uuid, array $selected_changes ): void;

	public function updateStatus(
		Uuid $uuid,
		string $status,
		string $cleanup_status
	): void;

	public function deleteByUuid( Uuid $uuid ): bool;

	public function activeCount(): int;

	public function staleCount(): int;

	public function orphanedWorkspaceCount(): int;
}
