// <copyright file="IHlcStateStore.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under BUSL-1.1.
// </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);
}