docs consolidation and others

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

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