fix(localdb): phase-2 live gate — 4 production defects found and fixed

Gate record: docs/plans/2026-07-20-localdb-phase2-live-gate.md. Checks 1, 2, 5, 6 pass. Checks 3 and 4 are NOT satisfied — the defect they were meant to confirm turned out to be the opposite of what the plan assumed. Three defects crash-looped every driver node before check 1 could even run: 1. An empty ServerHistorian:ApiKey kills the host. ServerHistorianOptions- Validator exists to turn exactly that class of failure into a named OptionsValidationException, but its documented fail tier explicitly excluded ApiKey on the reasoning that a keyless client "degrades — the gateway rejects calls". It does not: the client validates its own options at construction, so the process dies during Akka startup and never makes a call. 2. UseTls disagreeing with the endpoint scheme kills the host too, in both directions (both messages confirmed in the shipped client assembly). Moving an endpoint from https to http without clearing UseTls is an ordinary migration slip. 3. Plaintext h2c was UNREACHABLE. HistorianGatewayClientAdapter forwarded the TLS-only options unconditionally, and AllowUntrustedServerCertificate defaults to false, so it always sent RequireCertificateValidation=true — which the client rejects outright when UseTls=false. Every http:// deployment crashed, though the scheme is documented as the supported way to select h2c, and the only workaround was to assert a certificate posture for a connection that has no certificate. The fourth was the blocker, and it is Phase 2's own: 4. The drain gate deferred to a Primary that cannot deliver. Redundancy roles are elected CLUSTER-WIDE; the alarm queue is PAIR-LOCAL. On the rig the elected driver Primary is central-1 — it carries the driver Akka role, replicates nobody's LocalDb and does not even run the alarm historian — so every driver node logged "Historian drain suspended", including the two site-b nodes that have no peer at all. Nothing drained anywhere, where before Phase 2 it drained fine. The cost is not a duplicate; it is the buffer growing to the capacity wall and evicting the audit trail it exists to protect. Fixed in three layers: a separate ShouldDrainAlarmHistory policy (unknown role drains; the two gates now deliberately disagree, and a test pins that); peer- host matching in DriverHostActor so a node stands down only for a Primary holding its rows; and AddAlarmHistorian short-circuiting the gate when replication is unconfigured — testing BOTH Replication:PeerAddress and SyncListenPort, since only the dialing half sets the former while both halves share the queue. Every one of these follows from the asymmetry: a false allow costs a duplicate row, which at-least-once delivery already accepts and payload-hash ids collapse; a false deny loses data silently. A third vacuous test, caught by the same delete-the-guard discipline: the role-view tests stayed green with the guard removed, because AwaitAssert polls until an assertion passes and the assertion was "reads open" — which is the SEEDED value, satisfied at the first poll before the actor processed anything. They now assert the sequence of published values through a recording view; the control then goes red for exactly the cases that matter. Migration evidence: 11 legacy rows across two deliberately overlapping files converged to exactly 9 identical rows on both nodes, proving D-6's payload-hash identity on real nodes rather than in a fixture. Open design fork, recorded in the gate doc rather than decided here: a pair cannot currently identify its own Primary, so both halves drain. Safe in every topology — nothing loses data — but the gate's de-duplication benefit is unrealised until roles are scoped per pair. Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 06:13:01 -04:00
parent 2e4ccf7fe9
commit f9f1b8fcee
14 changed files with 885 additions and 73 deletions
@@ -257,6 +257,13 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
    /// today, the alarm store-and-forward drain. Null on nodes that do not wire one.</summary>
    private readonly IRedundancyRoleView? _redundancyRoleView;

+    /// <summary>
+    ///     Host of this node's LocalDb replication partner — the only node that holds a copy of this
+    ///     node's alarm queue, and therefore the only node it may ever stand down in favour of.
+    ///     <c>null</c> when this node dials nobody (unpaired, or the listening half of a pair).
+    /// </summary>
+    private readonly string? _replicationPeerHost;
+
    /// <summary>Debounces the S5 "snapshot omitted this node" Warning to once per process — a persistent
    /// identity mismatch (03/S5) would otherwise log on every snapshot.</summary>
    private bool _warnedSnapshotMissingLocalNode;
@@ -372,7 +379,8 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
        IDriverCapabilityInvokerFactory? invokerFactory = null,
        Func<int>? driverMemberCountProvider = null,
        IDeploymentArtifactCache? deploymentArtifactCache = null,
-        IRedundancyRoleView? redundancyRoleView = null) =>
+        IRedundancyRoleView? redundancyRoleView = null,
+        string? replicationPeerHost = null) =>
        // WARNING: this forwarding list is POSITIONAL, and Props.Create compiles it into an
        // expression tree. Six IActorRef? parameters and several interface-typed ones mean a
        // mis-ordered argument is usually type-compatible and therefore compiles clean, then binds
@@ -382,7 +390,7 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
            dbFactory, localNode, coordinator, driverFactory, localRoles, dependencyMux, opcUaPublishActor,
            healthPublisher, virtualTagEvaluator, historyWriter, virtualTagHostOverride,
            loggerFactory, scriptRootLogger, scriptedAlarmHostOverride, invokerFactory, driverMemberCountProvider,
-            deploymentArtifactCache, redundancyRoleView));
+            deploymentArtifactCache, redundancyRoleView, replicationPeerHost));

    /// <summary>Initializes a new DriverHostActor with the specified dependencies.</summary>
    /// <param name="dbFactory">Database context factory for configuration database access.</param>
@@ -433,10 +441,12 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
        IDriverCapabilityInvokerFactory? invokerFactory = null,
        Func<int>? driverMemberCountProvider = null,
        IDeploymentArtifactCache? deploymentArtifactCache = null,
-        IRedundancyRoleView? redundancyRoleView = null)
+        IRedundancyRoleView? redundancyRoleView = null,
+        string? replicationPeerHost = null)
    {
        _deploymentArtifactCache = deploymentArtifactCache;
        _redundancyRoleView = redundancyRoleView;
+        _replicationPeerHost = replicationPeerHost;
        _dbFactory = dbFactory;
        _localNode = localNode;
        _coordinatorOverride = coordinator;
@@ -1465,6 +1475,14 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
        }
    }

+    /// <summary>Host part of a <c>host:port</c> node id.</summary>
+    private static string HostOf(NodeId nodeId)
+    {
+        var text = nodeId.ToString();
+        var colon = text.LastIndexOf(':');
+        return colon < 0 ? text : text[..colon];
+    }
+
    /// <summary>The Primary-gate deny reason tag for the denial meter (<c>secondary|detached|role-unknown</c>).</summary>
    private string PrimaryGateDenyReason() => _localRole switch
    {
@@ -1496,11 +1514,23 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
                _localNode, string.Join(",", msg.Nodes.Select(n => n.NodeId)));
        }

-        // Publish on EVERY snapshot, including ones that leave the cached role untouched: the other
-        // half of the decision is the driver member count, which moves with cluster membership and
-        // not with this message. Snapshots are re-published on a heartbeat, so a membership change
-        // is picked up within one heartbeat rather than waiting for a role change that may never come.
-        _redundancyRoleView?.Publish(ShouldServiceAsPrimary());
+        // Publish on EVERY snapshot, including ones that leave the cached role untouched, so a role
+        // that changes without this node being named still reaches the drain within one heartbeat.
+        //
+        // NOTE the different policy: the drain gate keys on the role ALONE and opens when it is
+        // unknown, where the data-plane gate above resolves an unknown role by member count and
+        // denies. Publishing ShouldServiceAsPrimary() here suspended the drain on every node of a
+        // multi-driver cluster that had no redundancy configured — see ShouldDrainAlarmHistory.
+        // Defer ONLY to the node that holds a copy of our rows. The redundancy election is
+        // cluster-wide and the queue is pair-local, so "somebody is Primary" is not a licence to stop
+        // draining — that Primary is usually in another pair entirely, and cannot deliver our events.
+        var peerIsPrimary =
+            _replicationPeerHost is not null
+            && msg.Nodes.Any(n => n.Role == RedundancyRole.Primary
+                                  && HostOf(n.NodeId) == _replicationPeerHost);
+
+        _redundancyRoleView?.Publish(
+            PrimaryGatePolicy.ShouldDrainAlarmHistory(_localRole, queueSharingPeerIsPrimary: peerIsPrimary));
    }

    private void Stale()