// -----------------------------------------------------------------------------
// IHlcSchedulerDequeueService.cs
// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
// Task: SQC-010 - Implement HlcSchedulerDequeueService
// -----------------------------------------------------------------------------

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

namespace StellaOps.Scheduler.Queue.Services;

/// <summary>
/// Service for HLC-ordered job dequeue with chain verification.
/// </summary>
public interface IHlcSchedulerDequeueService
{
    /// <summary>
    /// Dequeue jobs in HLC order (ascending) for a tenant/partition.
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="partitionKey">Optional partition key (null for all partitions).</param>
    /// <param name="limit">Maximum jobs to return.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Jobs ordered by HLC timestamp (ascending).</returns>
    Task<IReadOnlyList<SchedulerDequeueResult>> DequeueAsync(
        string tenantId,
        string? partitionKey,
        int limit,
        CancellationToken ct = default);

    /// <summary>
    /// Dequeue jobs within an HLC timestamp range.
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="startT">Start HLC (inclusive, null for no lower bound).</param>
    /// <param name="endT">End HLC (inclusive, null for no upper bound).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Jobs ordered by HLC timestamp within the range.</returns>
    Task<IReadOnlyList<SchedulerDequeueResult>> DequeueByRangeAsync(
        string tenantId,
        HlcTimestamp? startT,
        HlcTimestamp? endT,
        CancellationToken ct = default);

    /// <summary>
    /// Get a specific job by its ID.
    /// </summary>
    /// <param name="jobId">Job identifier.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The job if found, null otherwise.</returns>
    Task<SchedulerDequeueResult?> GetByJobIdAsync(
        Guid jobId,
        CancellationToken ct = default);

    /// <summary>
    /// Get a job by its chain link.
    /// </summary>
    /// <param name="link">Chain link hash.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The job if found, null otherwise.</returns>
    Task<SchedulerDequeueResult?> GetByLinkAsync(
        byte[] link,
        CancellationToken ct = default);

    /// <summary>
    /// Count jobs within an HLC range.
    /// </summary>
    Task<int> CountByRangeAsync(
        string tenantId,
        HlcTimestamp? startT,
        HlcTimestamp? endT,
        CancellationToken ct = default);
}