feat(scripted-alarms): richer AlarmConditionState bridge to the OPC UA node (T15)

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/AlarmConditionSnapshot.cs

@@ -0,0 +1,45 @@
+namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+/// <summary>
+///     Commons-level projection of an alarm's full OPC UA Part 9 condition state, carried from the
+///     Runtime engine to the SDK sink. Commons cannot reference <c>Core.ScriptedAlarms</c> (its
+///     domain enums live there), so this DTO is deliberately primitive: every field is a
+///     <see cref="bool"/>, the Commons-local <see cref="AlarmShelvingKind"/> enum, a
+///     <see cref="ushort"/> severity, or a <see cref="string"/>. The Runtime host maps its Core
+///     <c>AlarmConditionState</c> + <c>AlarmSeverity</c> down to this shape; the SDK
+///     <c>OtOpcUaNodeManager</c> projects it back up onto a real <c>AlarmConditionState</c> node.
+/// </summary>
+/// <param name="Active">Whether the alarm condition is currently active (ActiveState).</param>
+/// <param name="Acknowledged">Whether the active transition has been acknowledged (AckedState).</param>
+/// <param name="Confirmed">Whether the clear transition has been confirmed (ConfirmedState).</param>
+/// <param name="Enabled">Whether the alarm is enabled (EnabledState); a disabled alarm reports no events.</param>
+/// <param name="Shelving">The shelving mode (ShelvingState): unshelved, one-shot, or timed.</param>
+/// <param name="Severity">OPC UA severity on the 1..1000 scale (the SDK <c>SetSeverity</c> input).</param>
+/// <param name="Message">The human-readable condition message (LocalizedText payload).</param>
+public sealed record AlarmConditionSnapshot(
+    bool Active,
+    bool Acknowledged,
+    bool Confirmed,
+    bool Enabled,
+    AlarmShelvingKind Shelving,
+    ushort Severity,
+    string Message);
+
+/// <summary>
+///     Commons-local mirror of the Core <c>ShelvingKind</c> enum so this assembly carries no
+///     dependency on <c>Core.ScriptedAlarms</c>. <see cref="Unshelved"/> = no suppression,
+///     <see cref="OneShot"/> = suppress the next active transition, <see cref="Timed"/> = suppress
+///     until a configured expiry. The Runtime host maps the Core enum onto these members; the SDK
+///     sink maps them onto the Part 9 <c>SetShelvingState(shelved, oneShot, shelvingTime)</c> flags.
+/// </summary>
+public enum AlarmShelvingKind
+{
+    /// <summary>No shelving — the alarm behaves normally.</summary>
+    Unshelved,
+
+    /// <summary>One-shot shelve — suppresses the next active transition, then expires.</summary>
+    OneShot,
+
+    /// <summary>Timed shelve — suppresses until a configured expiry timestamp passes.</summary>
+    Timed,
+}

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/DeferredAddressSpaceSink.cs

@@ -30,13 +30,12 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink
     public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc)
         => _inner.WriteValue(nodeId, value, quality, sourceTimestampUtc);
 
-    /// <summary>Writes an alarm state through the inner sink.</summary>
+    /// <summary>Writes a full alarm-condition state through the inner sink.</summary>
     /// <param name="alarmNodeId">The node ID of the alarm condition.</param>
-    /// <param name="active">Whether the alarm is active.</param>
-    /// <param name="acknowledged">Whether the alarm has been acknowledged.</param>
+    /// <param name="state">The full condition state to project onto the node.</param>
     /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
-    public void WriteAlarmState(string alarmNodeId, bool active, bool acknowledged, DateTime sourceTimestampUtc)
-        => _inner.WriteAlarmState(alarmNodeId, active, acknowledged, sourceTimestampUtc);
+    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc)
+        => _inner.WriteAlarmCondition(alarmNodeId, state, sourceTimestampUtc);
 
     /// <summary>Materialises a real Part 9 alarm-condition node through the inner sink.</summary>
     /// <param name="alarmNodeId">The alarm node ID (== ScriptedAlarmId).</param>

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/IOpcUaAddressSpaceSink.cs

@@ -15,20 +15,21 @@ public interface IOpcUaAddressSpaceSink
     /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
     void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc);
 
-    /// <summary>Write an alarm-condition's active/acknowledged state. When a real Part 9 condition
-    /// node has been materialised for <paramref name="alarmNodeId"/> via
-    /// <see cref="MaterialiseAlarmCondition"/>, this projects onto its ActiveState/AckedState/Retain;
-    /// otherwise it falls back to the legacy two-element placeholder variable.</summary>
+    /// <summary>Write an alarm-condition's full Part 9 state. When a real condition node has been
+    /// materialised for <paramref name="alarmNodeId"/> via <see cref="MaterialiseAlarmCondition"/>,
+    /// this projects the whole <see cref="AlarmConditionSnapshot"/>
+    /// (Enabled/Active/Acked/Confirmed/Shelving/Severity/Message) onto it and recomputes Retain;
+    /// otherwise it falls back to the legacy two-element <c>[Active, Acknowledged]</c> placeholder
+    /// variable. No OPC UA event is fired — that is T16's responsibility.</summary>
     /// <param name="alarmNodeId">The OPC UA node ID of the alarm (== ScriptedAlarmId for materialised conditions).</param>
-    /// <param name="active">Whether the alarm is active.</param>
-    /// <param name="acknowledged">Whether the alarm has been acknowledged.</param>
+    /// <param name="state">The full condition state to project onto the node.</param>
     /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
-    void WriteAlarmState(string alarmNodeId, bool active, bool acknowledged, DateTime sourceTimestampUtc);
+    void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc);
 
     /// <summary>
     ///     Materialise a real OPC UA Part 9 alarm-condition node under its equipment folder so clients
     ///     can browse it as a proper condition (with basic Active/Ack state). The node id equals the
-    ///     alarm node id (the ScriptedAlarmId) so subsequent <see cref="WriteAlarmState"/> calls update
+    ///     alarm node id (the ScriptedAlarmId) so subsequent <see cref="WriteAlarmCondition"/> calls update
     ///     it. Used by <c>Phase7Applier.MaterialiseScriptedAlarms</c>. Idempotent.
     /// </summary>
     /// <param name="alarmNodeId">The alarm node ID (== ScriptedAlarmId); becomes the condition's NodeId.</param>
@@ -84,7 +85,7 @@ public sealed class NullOpcUaAddressSpaceSink : IOpcUaAddressSpaceSink
     public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc) { }
 
     /// <inheritdoc />
-    public void WriteAlarmState(string alarmNodeId, bool active, bool acknowledged, DateTime sourceTimestampUtc) { }
+    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc) { }
 
     /// <inheritdoc />
     public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity) { }