feat(commons): IAlarmSubscribableConnection seam + DCL native alarm messages

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Protocol/IAlarmSubscribableConnection.cs

@@ -0,0 +1,28 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Protocol;
+
+/// <summary>Callback invoked when a native alarm transition (incl. snapshot replay) arrives.</summary>
+/// <param name="transition">The protocol-neutral transition emitted by the adapter.</param>
+public delegate void AlarmTransitionCallback(NativeAlarmTransition transition);
+
+/// <summary>
+/// Optional capability for an <see cref="IDataConnection"/> implementation that
+/// can mirror a source's native alarms (OPC UA Alarms &amp; Conditions, MxAccess
+/// Gateway StreamAlarms). Mirrors the <see cref="IBrowsableDataConnection"/>
+/// capability-interface pattern; consumed by the DataConnectionActor only.
+/// </summary>
+public interface IAlarmSubscribableConnection
+{
+    /// <summary>
+    /// Subscribes to native alarm transitions for the conditions under
+    /// <paramref name="sourceReference"/>. The adapter replays a snapshot of
+    /// currently-active conditions (Snapshot…SnapshotComplete) on every
+    /// (re)subscribe. Returns a subscription id for <see cref="UnsubscribeAlarmsAsync"/>.
+    /// </summary>
+    Task<string> SubscribeAlarmsAsync(string sourceReference, string? conditionFilter,
+        AlarmTransitionCallback callback, CancellationToken cancellationToken = default);
+
+    /// <summary>Cancels an active alarm subscription by its id.</summary>
+    Task UnsubscribeAlarmsAsync(string subscriptionId, CancellationToken cancellationToken = default);
+}

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/DataConnection/NativeAlarmMessages.cs

@@ -0,0 +1,13 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.DataConnection;
+
+/// <summary>DCL → instance: a native alarm transition routed by source reference.</summary>
+public record NativeAlarmTransitionUpdate(string ConnectionName, NativeAlarmTransition Transition);
+
+/// <summary>
+/// DCL → instance: the alarm feed for a source became unavailable (connection
+/// lost). Consumers mark their mirrored alarms uncertain rather than clearing
+/// them; the reconnect snapshot reconciles state.
+/// </summary>
+public record NativeAlarmSourceUnavailable(string ConnectionName, string SourceReference, DateTimeOffset Timestamp);

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/DataConnection/SubscribeAlarmsRequest.cs

@@ -0,0 +1,30 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.DataConnection;
+
+/// <summary>
+/// Sent by a NativeAlarmActor (via the DCL manager) to subscribe an instance to
+/// native alarms for a source binding. The DataConnectionActor opens one alarm
+/// feed per connection and routes transitions by source-object reference.
+/// </summary>
+public record SubscribeAlarmsRequest(
+    string CorrelationId,
+    string InstanceUniqueName,
+    string ConnectionName,
+    string SourceReference,
+    string? ConditionFilter,
+    DateTimeOffset Timestamp);
+
+/// <summary>Reply to a <see cref="SubscribeAlarmsRequest"/>.</summary>
+public record SubscribeAlarmsResponse(
+    string CorrelationId,
+    string InstanceUniqueName,
+    bool Success,
+    string? ErrorMessage,
+    DateTimeOffset Timestamp);
+
+/// <summary>Cancels a native alarm subscription for an instance + source.</summary>
+public record UnsubscribeAlarmsRequest(
+    string CorrelationId,
+    string InstanceUniqueName,
+    string ConnectionName,
+    string SourceReference,
+    DateTimeOffset Timestamp);

tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Messages/NativeAlarmMessagesTests.cs

@@ -0,0 +1,27 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.DataConnection;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Tests.Messages;
+
+public class NativeAlarmMessagesTests
+{
+    [Fact]
+    public void SubscribeAlarmsRequest_CarriesSourceAndFilter()
+    {
+        var r = new SubscribeAlarmsRequest("c1", "inst", "PlantOpcUa", "ns=2;s=Tank01", null, DateTimeOffset.UnixEpoch);
+        Assert.Equal("ns=2;s=Tank01", r.SourceReference);
+        Assert.Null(r.ConditionFilter);
+    }
+
+    [Fact]
+    public void NativeAlarmTransitionUpdate_WrapsTransition()
+    {
+        var t = new NativeAlarmTransition("Tank01.Hi", "Tank01", "x", AlarmTransitionKind.Raise,
+            new AlarmConditionState(true, false, null, AlarmShelveState.Unshelved, false, 500),
+            "", "", "", "", "", null, DateTimeOffset.UnixEpoch, "", "");
+        var u = new NativeAlarmTransitionUpdate("PlantOpcUa", t);
+        Assert.Equal("PlantOpcUa", u.ConnectionName);
+        Assert.Equal("Tank01", u.Transition.SourceObjectReference);
+    }
+}