55 lines
1.9 KiB
C#
55 lines
1.9 KiB
C#
// -----------------------------------------------------------------------------
|
|
// IHybridLogicalClock.cs
|
|
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
|
// Task: HLC-003 - Define HLC interface
|
|
// -----------------------------------------------------------------------------
|
|
|
|
namespace StellaOps.HybridLogicalClock;
|
|
|
|
/// <summary>
|
|
/// Hybrid Logical Clock for monotonic timestamp generation across distributed nodes.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// HLC combines physical (wall-clock) time with logical counters to provide:
|
|
/// - Monotonic timestamps even under clock skew
|
|
/// - Causal ordering guarantees across distributed nodes
|
|
/// - Deterministic tie-breaking for concurrent events
|
|
/// </remarks>
|
|
public interface IHybridLogicalClock
|
|
{
|
|
/// <summary>
|
|
/// Generate next timestamp for local event.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This should be called for every event that needs ordering:
|
|
/// - Job enqueue
|
|
/// - State transitions
|
|
/// - Audit log entries
|
|
/// </remarks>
|
|
/// <returns>New monotonically increasing HLC timestamp</returns>
|
|
HlcTimestamp Tick();
|
|
|
|
/// <summary>
|
|
/// Update clock on receiving remote timestamp, return merged result.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Called when receiving a message from another node to ensure
|
|
/// causal ordering is maintained across the distributed system.
|
|
/// </remarks>
|
|
/// <param name="remote">Timestamp from remote node</param>
|
|
/// <returns>New timestamp that is greater than both local clock and remote timestamp</returns>
|
|
/// <exception cref="HlcClockSkewException">If clock skew exceeds configured threshold</exception>
|
|
HlcTimestamp Receive(HlcTimestamp remote);
|
|
|
|
/// <summary>
|
|
/// Current clock state (for persistence/recovery).
|
|
/// </summary>
|
|
HlcTimestamp Current { get; }
|
|
|
|
/// <summary>
|
|
/// Node identifier for this clock instance.
|
|
/// </summary>
|
|
string NodeId { get; }
|
|
}
|
|
|