docs consolidation and others

src/__Libraries/StellaOps.HybridLogicalClock/HlcClockSkewException.cs

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