save progress

src/__Libraries/StellaOps.HybridLogicalClock/IHlcStateStore.cs

@@ -0,0 +1,44 @@
+// <copyright file="IHlcStateStore.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
+// </copyright>
+
+namespace StellaOps.HybridLogicalClock;
+
+/// <summary>
+/// Persistent storage for HLC state (survives restarts).
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implementations should provide atomic update semantics to prevent
+/// state corruption during concurrent operations. The store is used to:
+/// </para>
+/// <list type="bullet">
+/// <item><description>Persist HLC state after each tick (fire-and-forget)</description></item>
+/// <item><description>Recover state on node restart</description></item>
+/// <item><description>Ensure clock monotonicity across restarts</description></item>
+/// </list>
+/// </remarks>
+public interface IHlcStateStore
+{
+    /// <summary>
+    /// Load last persisted HLC state for node.
+    /// </summary>
+    /// <param name="nodeId">The node identifier to load state for.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The last persisted timestamp, or null if no state exists.</returns>
+    Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Persist HLC state (called after each tick).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This operation should be atomic and idempotent. Implementations may use
+    /// fire-and-forget semantics with error logging for performance.
+    /// </para>
+    /// </remarks>
+    /// <param name="timestamp">The timestamp state to persist.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task representing the async operation.</returns>
+    Task SaveAsync(HlcTimestamp timestamp, CancellationToken ct = default);
+}