save progress

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

@@ -0,0 +1,77 @@
+// <copyright file="IHlcSchedulerDequeueService.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
+// </copyright>
+
+using StellaOps.HybridLogicalClock;
+
+namespace StellaOps.Scheduler.Queue.Hlc;
+
+/// <summary>
+/// Service for HLC-ordered scheduler job dequeuing.
+/// </summary>
+/// <remarks>
+/// This service provides deterministic, HLC-ordered retrieval of scheduler log entries
+/// for processing. The HLC ordering guarantees causal consistency across distributed nodes.
+/// </remarks>
+public interface IHlcSchedulerDequeueService
+{
+    /// <summary>
+    /// Dequeues scheduler log entries in HLC order.
+    /// </summary>
+    /// <param name="tenantId">Tenant identifier.</param>
+    /// <param name="limit">Maximum number of entries to return.</param>
+    /// <param name="partitionKey">Optional partition key to filter by.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The dequeue result with entries in HLC order.</returns>
+    Task<SchedulerHlcDequeueResult> DequeueAsync(
+        string tenantId,
+        int limit,
+        string? partitionKey = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Dequeues scheduler log entries within an HLC time range.
+    /// </summary>
+    /// <param name="tenantId">Tenant identifier.</param>
+    /// <param name="startHlc">HLC range start (inclusive, null for unbounded).</param>
+    /// <param name="endHlc">HLC range end (inclusive, null for unbounded).</param>
+    /// <param name="limit">Maximum number of entries to return.</param>
+    /// <param name="partitionKey">Optional partition key to filter by.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The dequeue result with entries in HLC order.</returns>
+    Task<SchedulerHlcDequeueResult> DequeueByRangeAsync(
+        string tenantId,
+        HlcTimestamp? startHlc,
+        HlcTimestamp? endHlc,
+        int limit,
+        string? partitionKey = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Dequeues scheduler log entries after a specific HLC timestamp (cursor-based).
+    /// </summary>
+    /// <param name="tenantId">Tenant identifier.</param>
+    /// <param name="afterHlc">HLC timestamp to start after (exclusive).</param>
+    /// <param name="limit">Maximum number of entries to return.</param>
+    /// <param name="partitionKey">Optional partition key to filter by.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The dequeue result with entries in HLC order.</returns>
+    Task<SchedulerHlcDequeueResult> DequeueAfterAsync(
+        string tenantId,
+        HlcTimestamp afterHlc,
+        int limit,
+        string? partitionKey = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets a single scheduler log entry by job ID.
+    /// </summary>
+    /// <param name="tenantId">Tenant identifier.</param>
+    /// <param name="jobId">The job identifier.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The scheduler log entry if found, null otherwise.</returns>
+    Task<Persistence.Postgres.Models.SchedulerLogEntry?> GetByJobIdAsync(
+        string tenantId,
+        Guid jobId,
+        CancellationToken cancellationToken = default);
+}