feat(alarms): thread an additive AckTime through the native-alarm mirror

MES alarm-status API §6.4 (docs/plans/2026-06-30-mes-alarm-status-api.md, Phase 1 task 1). MES needs a real AckDT for a triggered alarm, and the mirror carried acked-vs-unacked but never WHEN. AckTime now rides the whole path: DCL transition -> AlarmStateChanged -> gRPC AlarmStateUpdate -> site SQLite. Stamping rule, identical on both protocols: non-null ONLY while the condition is active AND acknowledged. That single predicate yields all three required behaviours -- null while unacked, cleared on re-raise (a re-raise arrives unacknowledged), and no phantom ack on a return-to-normal. The last one is load-bearing for MxGateway, which maps INACTIVE to Acknowledged = true; without the active check every clear would claim an ack the system never observed. Provenance is honest, never fabricated: - OPC UA A&C supplies a TRUE ack instant, so we now select it: AcknowledgeableConditionType/AckedState/TransitionTime at SelectClause index 18, APPENDED so the positional reads at 0-17 keep their meaning. Servers that omit the field fall back to the event's own Time. - MxAccess Gateway supplies none, so the ack transition's own timestamp is used -- accurate to when the system SAW the ack. An ACTIVE_ACKED re-subscribe snapshot restores one from LastTransitionTimestamp rather than dropping it. The decision lives in pure mappers (Opc/Mx AlarmMapper.DeriveAckTime), so it is unit-tested with no live server or gateway. Additive-only throughout: init-only property on AlarmStateChanged, trailing optional positional on NativeAlarmTransition (all 14-arg call sites untouched), proto field 24 (never reusing a number) regenerated via docker/regen-proto.sh sitestream with the csproj diff verified empty. Persistence rides native_alarm_state's existing metadata_json blob rather than a new column -- deliberately. That table is RegisterReplicated in SiteLocalDbSetup and LocalDb builds its CDC triggers from the column list at registration time, so an additive JSON property changes no schema, no triggers and no replication contract; metadata_json is exactly the extension point UA4 introduced for this. Rows written before the field deserialize it as null. Tests: 4 OPC UA + 6 MxGateway mapper cases, 3 NativeAlarmActor (emit, failover rehydrate, pre-AckTime row), 1 proto round-trip incl. the null case, 4 Commons additive/back-compat. The OPC UA SelectClause count lock-in moves 18 -> 19 with an index-18 assertion -- intended, the clause is appended, which is precisely what that guard exists to make visible.
2026-08-01 13:12:04 -04:00
parent 6dc5d94cb9
commit 01bcca992c
19 changed files with 775 additions and 113 deletions
@@ -159,6 +159,69 @@ public class StreamRelayActorTests : TestKit
        Assert.False(roundTripped.IsConfiguredPlaceholder);
    }

+    [Fact]
+    public void RelaysAlarmStateChanged_AckTime_SurvivesFullRoundTrip()
+    {
+        // MES alarm-status API §6.4: AlarmStateUpdate field 24. An acknowledged mirrored
+        // condition must reach central with its ack instant intact, and an unacknowledged
+        // one must arrive as null — an absent proto Timestamp, not the epoch.
+        var channel = Channel.CreateUnbounded<SiteStreamEvent>();
+        var actor = Sys.ActorOf(Props.Create(() =>
+            new StreamRelayActor("corr-acktime", channel.Writer)));
+
+        var ackedAt = new DateTimeOffset(2026, 8, 1, 12, 0, 0, TimeSpan.Zero);
+        var acked = new AlarmStateChanged(
+            "Site1.Motor01", "Motor1.MotorAlarms.Hi", AlarmState.Active, 900,
+            new DateTimeOffset(2026, 8, 1, 12, 5, 0, TimeSpan.Zero))
+        {
+            Kind = AlarmKind.NativeOpcUa,
+            SourceReference = "Motor1.MotorAlarms.Hi",
+            NativeSourceCanonicalName = "Motor1.MotorAlarms",
+            AckTime = ackedAt,
+            Condition = new AlarmConditionState(
+                Active: true, Acknowledged: true, Confirmed: null,
+                Shelve: AlarmShelveState.Unshelved, Suppressed: false, Severity: 900)
+        };
+
+        actor.Tell(acked);
+        var ackedProto = ReadProtoEvent(channel);
+        Assert.Equal(Timestamp.FromDateTimeOffset(ackedAt), ackedProto.AlarmChanged.AckTime);
+        Assert.Equal(
+            ackedAt,
+            Assert.IsType<AlarmStateChanged>(
+                SiteStreamGrpcClient.ConvertToDomainEvent(ackedProto)).AckTime);
+
+        actor.Tell(acked with
+        {
+            AckTime = null,
+            Condition = new AlarmConditionState(
+                Active: true, Acknowledged: false, Confirmed: null,
+                Shelve: AlarmShelveState.Unshelved, Suppressed: false, Severity: 900)
+        });
+        var unackedProto = ReadProtoEvent(channel);
+        Assert.Null(unackedProto.AlarmChanged.AckTime);
+        Assert.Null(
+            Assert.IsType<AlarmStateChanged>(
+                SiteStreamGrpcClient.ConvertToDomainEvent(unackedProto)).AckTime);
+    }
+
+    /// <summary>
+    /// Reads the next relayed proto event, retrying once after a short pause because the
+    /// relay actor writes to the channel asynchronously (mirrors the existing round-trip
+    /// tests' read pattern).
+    /// </summary>
+    private static SiteStreamEvent ReadProtoEvent(Channel<SiteStreamEvent> channel)
+    {
+        if (!channel.Reader.TryRead(out var protoEvent))
+        {
+            Thread.Sleep(500);
+            Assert.True(channel.Reader.TryRead(out protoEvent), "Expected a proto event on the channel");
+        }
+
+        Assert.NotNull(protoEvent);
+        return protoEvent!;
+    }
+
    [Fact]
    public void DropsAlarmStateChanged_WhenIsConfiguredPlaceholder()
    {