docs+code: close Theme 1 — 24 design-doc / XML-doc drift findings

Doc/XML-comment drift + small adherence fixes across 17 modules. Highlights:
- Host-017: site CoordinatedShutdown ordering — SiteStreamGrpcServer gains
  CancelAllStreams() (refuse new streams, cancel active), wired into
  Program.cs site branch via ApplicationStopping.
- InboundAPI-021: ParentExecutionId now travels on RouteToGet/SetAttributes
  symmetric with RouteToCallRequest; RouteHelper stamps from _parentExecutionId.
- ClusterInfra-012: ClusterOptionsValidator now requires both seed nodes.
- Comm-018: SiteCommunicationActor.HeartbeatMessage.IsActive derived from
  cluster leader check (was hardcoded true).
- DM-020: reconciliation audit row attributes the current user, not prior deployer.
- SEL-019: EventLogPurgeService early-exits on standby via active-node check.
- Plus comment/XML-doc accuracy fixes across AuditLog, ConfigurationDatabase,
  NotificationOutbox, SiteRuntime, SiteCallAudit; doc refreshes for Component-
  Commons / -ManagementService / -CLI / -ExternalSystemGateway / -HealthMonitoring
  / -Transport / -ConfigurationDatabase; CD-023 index-name doc alignment.

11 new regression tests (RouteHelper x4, SiteStreamGrpcServer x2,
ClusterOptionsValidator x1, SiteCommunicationActor x1, DeploymentService x1,
EventLogPurgeService x3). Build clean (0 warnings); InboundAPI/Communication/
Host suites all green. README regenerated: 112 open (was 136).

tests/ScadaLink.Communication.Tests/Grpc/SiteStreamGrpcServerTests.cs

@@ -138,6 +138,63 @@ public class SiteStreamGrpcServerTests : TestKit
         Assert.Equal(0, server.ActiveStreamCount);
     }
 
+    // --- Host-017 / REQ-HOST-7: site-shutdown ordering ---
+
+    [Fact]
+    public async Task Host017_CancelAllStreams_CancelsActiveStreamsAndRefusesNewOnes()
+    {
+        // REQ-HOST-7 step (1)+(2): on CoordinatedShutdown the gRPC server must
+        // stop accepting new streams AND cancel every active stream so the
+        // client observes a clean Cancelled (not a silent stream that only
+        // times out via keepalive). Program.cs registers
+        // ApplicationStopping → CancelAllStreams(); this test exercises the
+        // server-side guarantee in isolation.
+        var server = CreateServer();
+        server.SetReady(Sys);
+
+        var cts1 = new CancellationTokenSource();
+        var context1 = CreateMockContext(cts1.Token);
+        var writer1 = Substitute.For<IServerStreamWriter<SiteStreamEvent>>();
+
+        var stream1Task = Task.Run(() => server.SubscribeInstance(
+            MakeRequest("corr-shutdown-1"), writer1, context1));
+
+        await WaitForConditionAsync(() => server.ActiveStreamCount == 1);
+
+        // Begin shutdown — flip the flag AND cancel the active stream.
+        server.CancelAllStreams();
+
+        Assert.True(server.IsShuttingDown);
+
+        // Active stream's await foreach observes OCE and falls through finally
+        // → entry is removed from _activeStreams.
+        await stream1Task;
+        Assert.Equal(0, server.ActiveStreamCount);
+
+        // A second SubscribeInstance after shutdown is refused immediately
+        // with Unavailable rather than allowed to register a new stream.
+        var writer2 = Substitute.For<IServerStreamWriter<SiteStreamEvent>>();
+        var context2 = CreateMockContext();
+        var ex = await Assert.ThrowsAsync<RpcException>(
+            () => server.SubscribeInstance(MakeRequest("corr-shutdown-2"), writer2, context2));
+        Assert.Equal(StatusCode.Unavailable, ex.StatusCode);
+        Assert.Contains("shutting", ex.Status.Detail, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public void Host017_CancelAllStreams_IsIdempotent()
+    {
+        // Repeated calls during a double-fire shutdown sequence must not throw.
+        var server = CreateServer();
+        server.SetReady(Sys);
+
+        server.CancelAllStreams();
+        server.CancelAllStreams();
+
+        Assert.True(server.IsShuttingDown);
+        Assert.Equal(0, server.ActiveStreamCount);
+    }
+
     [Fact]
     public async Task SubscribesAndRemovesFromStreamManager()
     {

tests/ScadaLink.Communication.Tests/SiteCommunicationActorTests.cs

@@ -2,6 +2,7 @@ using Akka.Actor;
 using Akka.Cluster.Tools.Client;
 using Akka.TestKit.Xunit2;
 using ScadaLink.Commons.Messages.Deployment;
+using ScadaLink.Commons.Messages.Health;
 using ScadaLink.Commons.Messages.Lifecycle;
 using ScadaLink.Commons.Messages.Integration;
 using ScadaLink.Commons.Messages.Notification;
@@ -282,4 +283,35 @@ public class SiteCommunicationActorTests : TestKit
         Assert.False(ack.Applied);
         Assert.NotNull(ack.ErrorMessage);
     }
+
+    // ── Communication-018: heartbeat IsActive reflects this node's cluster role ──
+
+    [Theory]
+    [InlineData(true)]
+    [InlineData(false)]
+    public void Heartbeat_StampsIsActive_FromInjectedCheck(bool isActive)
+    {
+        // Communication-018: HeartbeatMessage.IsActive must reflect the actual
+        // active/standby role of this node, not a hard-coded `true`. The actor
+        // now takes a Func<bool> override (defaulting to a real Akka.Cluster
+        // leader check in production); tests inject a stub so they do not need
+        // to bring up a full cluster in the TestKit ActorSystem.
+        var dmProbe = CreateTestProbe();
+        var centralClientProbe = CreateTestProbe();
+        var fastHeartbeatOptions = new CommunicationOptions
+        {
+            TransportHeartbeatInterval = TimeSpan.FromMilliseconds(50)
+        };
+
+        var siteActor = Sys.ActorOf(Props.Create(() =>
+            new SiteCommunicationActor("site1", fastHeartbeatOptions, dmProbe.Ref, () => isActive)));
+
+        siteActor.Tell(new RegisterCentralClient(centralClientProbe.Ref));
+
+        var send = centralClientProbe.FishForMessage<ClusterClient.Send>(
+            s => s.Message is HeartbeatMessage, TimeSpan.FromSeconds(3));
+        var heartbeat = Assert.IsType<HeartbeatMessage>(send.Message);
+        Assert.Equal(isActive, heartbeat.IsActive);
+        Assert.Equal("site1", heartbeat.SiteId);
+    }
 }