// -----------------------------------------------------------------------------
// IBatchSnapshotService.cs
// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
// Task: SQC-013 - Implement BatchSnapshotService
// -----------------------------------------------------------------------------

using StellaOps.HybridLogicalClock;
using StellaOps.Scheduler.Queue.Models;

namespace StellaOps.Scheduler.Queue.Services;

/// <summary>
/// Service for creating and managing batch snapshots of the scheduler log.
/// Snapshots provide audit anchors for verifying chain integrity.
/// </summary>
public interface IBatchSnapshotService
{
    /// <summary>
    /// Creates a batch snapshot for a given HLC range.
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="startT">Start HLC timestamp (inclusive).</param>
    /// <param name="endT">End HLC timestamp (inclusive).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The created snapshot.</returns>
    /// <exception cref="InvalidOperationException">If no jobs exist in the specified range.</exception>
    Task<BatchSnapshotResult> CreateSnapshotAsync(
        string tenantId,
        HlcTimestamp startT,
        HlcTimestamp endT,
        CancellationToken ct = default);

    /// <summary>
    /// Gets a batch snapshot by ID.
    /// </summary>
    Task<BatchSnapshotResult?> GetByIdAsync(Guid batchId, CancellationToken ct = default);

    /// <summary>
    /// Gets recent batch snapshots for a tenant.
    /// </summary>
    Task<IReadOnlyList<BatchSnapshotResult>> GetRecentAsync(
        string tenantId,
        int limit = 10,
        CancellationToken ct = default);

    /// <summary>
    /// Gets the latest batch snapshot for a tenant.
    /// </summary>
    Task<BatchSnapshotResult?> GetLatestAsync(
        string tenantId,
        CancellationToken ct = default);

    /// <summary>
    /// Finds snapshots that contain a specific HLC timestamp.
    /// </summary>
    Task<IReadOnlyList<BatchSnapshotResult>> FindContainingAsync(
        string tenantId,
        HlcTimestamp timestamp,
        CancellationToken ct = default);
}