docs consolidation and others

src/Scheduler/__Libraries/StellaOps.Scheduler.Queue/Services/IHlcSchedulerDequeueService.cs

@@ -0,0 +1,73 @@
+// -----------------------------------------------------------------------------
+// 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);
+}