docs(localdb): README + scadaproj index row + design-doc deltas; pack-verified 3 nupkgs @ 0.1.0

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 01:12:19 -04:00
parent b2345c32d4
commit ac6bcde159
5 changed files with 242 additions and 6 deletions
@@ -18,6 +18,7 @@ public static class LocalDbServiceCollectionExtensions
    /// caller. This is where consumers create their tables (via the passed <see cref="ILocalDb"/>) and call
    /// <see cref="ILocalDb.RegisterReplicated"/> to opt them into replication.
    /// </param>
+    /// <remarks>Subsequent calls are no-ops if an <see cref="ILocalDb"/> registration already exists (first registration wins).</remarks>
    public static IServiceCollection AddZbLocalDb(
        this IServiceCollection services,
        IConfiguration configuration,
@@ -44,8 +45,16 @@ public static class LocalDbServiceCollectionExtensions
            catch
            {
                // A throwing callback must not leak the open master connection: MS.DI does not
-                // dispose instances a failed factory never returned.
-                db.Dispose();
+                // dispose instances a failed factory never returned. Guard the cleanup so a Dispose
+                // failure can never replace the consumer's original onReady exception.
+                try
+                {
+                    db.Dispose();
+                }
+                catch
+                {
+                    // Swallow: the onReady exception below is the one the caller must see.
+                }
                throw;
            }
            return db;
@@ -13,6 +13,7 @@ public sealed class HybridLogicalClock
        _last = initialValue;
    }

+    /// <summary>Returns the next monotonically increasing HLC stamp: the current UTC physical time when it advances the clock, otherwise the last value with its logical counter incremented by one.</summary>
    public long Next()
    {
        lock (_lock)
@@ -26,8 +27,12 @@ public sealed class HybridLogicalClock
    /// <summary>Merge a peer's HLC so our next stamp orders after everything we've seen.</summary>
    public void Observe(long remote) { lock (_lock) { if (remote > _last) _last = remote; } }

+    /// <summary>The most recently issued/observed HLC value, without advancing the clock.</summary>
    public long Current { get { lock (_lock) return _last; } }

+    /// <summary>Extracts the physical component (UTC Unix milliseconds) from a packed HLC value.</summary>
    public static long PhysicalMs(long hlc) => hlc >> 16;
+
+    /// <summary>Extracts the 16-bit logical counter from a packed HLC value.</summary>
    public static int Counter(long hlc) => (int)(hlc & 0xFFFF);
 }