Harden Surreal migration with retry/coverage fixes and XML docs cleanup

tests/ZB.MOM.WW.CBDDC.Sample.Console.Tests/SurrealStoreContractTests.cs

@@ -11,6 +11,9 @@ namespace ZB.MOM.WW.CBDDC.Sample.Console.Tests;
 
 public class SurrealOplogStoreContractTests
 {
+    /// <summary>
+    ///     Verifies append, range query, merge, drop, and last-hash behavior for the oplog store.
+    /// </summary>
     [Fact]
     public async Task OplogStore_AppendQueryMergeDrop_AndLastHash_Works()
     {
@@ -71,6 +74,9 @@ public class SurrealOplogStoreContractTests
 
 public class SurrealDocumentMetadataStoreContractTests
 {
+    /// <summary>
+    ///     Verifies upsert, deletion marking, incremental reads, and merge precedence for document metadata.
+    /// </summary>
     [Fact]
     public async Task DocumentMetadataStore_UpsertMarkDeletedGetAfterAndMergeNewer_Works()
     {
@@ -108,6 +114,9 @@ public class SurrealDocumentMetadataStoreContractTests
 
 public class SurrealPeerConfigurationStoreContractTests
 {
+    /// <summary>
+    ///     Verifies save, read, remove, and merge behavior for remote peer configuration records.
+    /// </summary>
     [Fact]
     public async Task PeerConfigurationStore_SaveGetRemoveAndMerge_Works()
     {
@@ -163,6 +172,9 @@ public class SurrealPeerConfigurationStoreContractTests
 
 public class SurrealPeerOplogConfirmationStoreContractTests
 {
+    /// <summary>
+    ///     Verifies peer registration, confirmation updates, and peer deactivation semantics.
+    /// </summary>
     [Fact]
     public async Task PeerOplogConfirmationStore_EnsureUpdateAndDeactivate_Works()
     {
@@ -194,6 +206,9 @@ public class SurrealPeerOplogConfirmationStoreContractTests
         afterDeactivate.All(x => x.IsActive == false).ShouldBeTrue();
     }
 
+    /// <summary>
+    ///     Verifies merge semantics prefer newer confirmations and preserve active-state transitions.
+    /// </summary>
     [Fact]
     public async Task PeerOplogConfirmationStore_Merge_UsesNewerAndActiveStateSemantics()
     {
@@ -262,6 +277,9 @@ public class SurrealPeerOplogConfirmationStoreContractTests
 
 public class SurrealSnapshotMetadataStoreContractTests
 {
+    /// <summary>
+    ///     Verifies insert, update, merge, and hash lookup behavior for snapshot metadata records.
+    /// </summary>
     [Fact]
     public async Task SnapshotMetadataStore_InsertUpdateMergeAndHashLookup_Works()
     {
@@ -333,6 +351,9 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
     private readonly string _rootPath;
     private readonly ICBDDCSurrealSchemaInitializer _schemaInitializer;
 
+    /// <summary>
+    ///     Initializes a temporary embedded Surreal environment for contract tests.
+    /// </summary>
     public SurrealTestHarness()
     {
         string suffix = Guid.NewGuid().ToString("N");
@@ -351,6 +372,9 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
         _schemaInitializer = new TestSurrealSchemaInitializer(_client);
     }
 
+    /// <summary>
+    ///     Creates a document metadata store instance bound to the test harness database.
+    /// </summary>
     public SurrealDocumentMetadataStore CreateDocumentMetadataStore()
     {
         return new SurrealDocumentMetadataStore(
@@ -359,6 +383,9 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
             NullLogger<SurrealDocumentMetadataStore>.Instance);
     }
 
+    /// <summary>
+    ///     Creates an oplog store instance bound to the test harness database.
+    /// </summary>
     public SurrealOplogStore CreateOplogStore()
     {
         return new SurrealOplogStore(
@@ -371,6 +398,9 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
             NullLogger<SurrealOplogStore>.Instance);
     }
 
+    /// <summary>
+    ///     Creates a peer configuration store instance bound to the test harness database.
+    /// </summary>
     public SurrealPeerConfigurationStore CreatePeerConfigurationStore()
     {
         return new SurrealPeerConfigurationStore(
@@ -379,6 +409,9 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
             NullLogger<SurrealPeerConfigurationStore>.Instance);
     }
 
+    /// <summary>
+    ///     Creates a peer oplog confirmation store instance bound to the test harness database.
+    /// </summary>
     public SurrealPeerOplogConfirmationStore CreatePeerOplogConfirmationStore()
     {
         return new SurrealPeerOplogConfirmationStore(
@@ -387,6 +420,9 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
             NullLogger<SurrealPeerOplogConfirmationStore>.Instance);
     }
 
+    /// <summary>
+    ///     Creates a snapshot metadata store instance bound to the test harness database.
+    /// </summary>
     public SurrealSnapshotMetadataStore CreateSnapshotMetadataStore()
     {
         return new SurrealSnapshotMetadataStore(
@@ -395,6 +431,7 @@ internal sealed class SurrealTestHarness : IAsyncDisposable
             NullLogger<SurrealSnapshotMetadataStore>.Instance);
     }
 
+    /// <inheritdoc />
     public async ValueTask DisposeAsync()
     {
         await _client.DisposeAsync();
@@ -421,11 +458,16 @@ internal sealed class TestSurrealSchemaInitializer : ICBDDCSurrealSchemaInitiali
     private readonly ICBDDCSurrealEmbeddedClient _client;
     private int _initialized;
 
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="TestSurrealSchemaInitializer" /> class.
+    /// </summary>
+    /// <param name="client">The embedded client to initialize.</param>
     public TestSurrealSchemaInitializer(ICBDDCSurrealEmbeddedClient client)
     {
         _client = client;
     }
 
+    /// <inheritdoc />
     public async Task EnsureInitializedAsync(CancellationToken cancellationToken = default)
     {
         if (Interlocked.Exchange(ref _initialized, 1) == 1) return;