// -----------------------------------------------------------------------------
// HlcClockSkewException.cs
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
// Task: HLC-003 - Clock skew exception
// -----------------------------------------------------------------------------

namespace StellaOps.HybridLogicalClock;

/// <summary>
/// Exception thrown when clock skew between nodes exceeds the configured threshold.
/// </summary>
/// <remarks>
/// Clock skew indicates that two nodes have significantly different wall-clock times,
/// which could indicate NTP misconfiguration or network partitioning issues.
/// </remarks>
public sealed class HlcClockSkewException : Exception
{
    /// <summary>
    /// The actual skew detected between clocks.
    /// </summary>
    public TimeSpan ActualSkew { get; }

    /// <summary>
    /// The maximum skew threshold that was configured.
    /// </summary>
    public TimeSpan MaxAllowedSkew { get; }

    /// <summary>
    /// Creates a new clock skew exception.
    /// </summary>
    /// <param name="actualSkew">The actual skew detected</param>
    /// <param name="maxAllowedSkew">The configured maximum skew</param>
    public HlcClockSkewException(TimeSpan actualSkew, TimeSpan maxAllowedSkew)
        : base($"Clock skew of {actualSkew.TotalSeconds:F1}s exceeds maximum allowed skew of {maxAllowedSkew.TotalSeconds:F1}s")
    {
        ActualSkew = actualSkew;
        MaxAllowedSkew = maxAllowedSkew;
    }

    /// <summary>
    /// Creates a new clock skew exception with inner exception.
    /// </summary>
    public HlcClockSkewException(TimeSpan actualSkew, TimeSpan maxAllowedSkew, Exception innerException)
        : base($"Clock skew of {actualSkew.TotalSeconds:F1}s exceeds maximum allowed skew of {maxAllowedSkew.TotalSeconds:F1}s", innerException)
    {
        ActualSkew = actualSkew;
        MaxAllowedSkew = maxAllowedSkew;
    }
}