abstractions+driver+client.shared: extend AlarmEventArgs with rich payload (PR E.7)

Fourteenth PR of the alarms-over-gateway epic
(docs/plans/alarms-over-gateway.md). Depends on PR B.2 (GalaxyDriver
implements IAlarmSource, merged) and B.3 (DriverNodeManager prefers
driver-native ack, merged).

Three new optional fields on Core.Abstractions.AlarmEventArgs:

- OperatorComment — populated by the driver-native gateway path on
  Acknowledge transitions. Null on raise / clear, and null on the
  sub-attribute fallback path where the comment collapses into a
  single string write.
- OriginalRaiseTimestampUtc — preserved across Acknowledge so OPC
  UA Part 9 conditions keep the original raise time.
- AlarmCategory — taxonomy bucket from the upstream alarm system.
  Maps to ConditionClassName downstream when a class mapping is
  configured.

GalaxyDriver.OnPumpAlarmTransition populates the new fields from
GalaxyAlarmTransition (PR B.1). Empty strings collapse to null so
consumers can use is-null rather than is-null-or-empty checks.

Client.Shared mirror DTO (Client.Shared/Models/AlarmEventArgs)
gains the same three properties so the Client.UI / Client.CLI
surfaces can reflect the rich payload — the actual UI/CLI
verbose-output and Show-Details rendering ship as a follow-up
PR; this PR locks in the payload contract.

Tests:
- 2 new tests in Driver.Galaxy.Tests pin the populated-vs-null
  behaviour for full-payload Acknowledge and bare-bones Raise
  transitions respectively.
- Solution build clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/AlarmEventArgs.cs

@@ -15,7 +15,10 @@ public sealed class AlarmEventArgs : EventArgs
         bool ackedState,
         DateTime time,
         byte[]? eventId = null,
-        string? conditionNodeId = null)
+        string? conditionNodeId = null,
+        string? operatorComment = null,
+        DateTime? originalRaiseTimestampUtc = null,
+        string? alarmCategory = null)
     {
         SourceName = sourceName;
         ConditionName = conditionName;
@@ -27,6 +30,9 @@ public sealed class AlarmEventArgs : EventArgs
         Time = time;
         EventId = eventId;
         ConditionNodeId = conditionNodeId;
+        OperatorComment = operatorComment;
+        OriginalRaiseTimestampUtc = originalRaiseTimestampUtc;
+        AlarmCategory = alarmCategory;
     }
 
     /// <summary>The name of the source object that raised the alarm.</summary>
@@ -58,4 +64,25 @@ public sealed class AlarmEventArgs : EventArgs
 
     /// <summary>The NodeId of the condition instance (SourceNode), used for acknowledgment.</summary>
     public string? ConditionNodeId { get; }
+
+    /// <summary>
+    ///     PR E.7 — Operator-supplied comment recorded by the upstream alarm system on
+    ///     Acknowledge transitions. Null on raise / clear, or when the upstream path
+    ///     can't surface the comment (sub-attribute fallback path collapses comments
+    ///     into a single string write).
+    /// </summary>
+    public string? OperatorComment { get; }
+
+    /// <summary>
+    ///     PR E.7 — When the alarm originally entered the active state. Preserved
+    ///     across Acknowledge transitions so OPC UA Part 9 conditions keep the
+    ///     original raise time. Null when the upstream path doesn't surface it.
+    /// </summary>
+    public DateTime? OriginalRaiseTimestampUtc { get; }
+
+    /// <summary>
+    ///     PR E.7 — Upstream alarm taxonomy bucket (e.g. <c>Process</c> /
+    ///     <c>Safety</c> / <c>Diagnostics</c>). Null when not surfaced.
+    /// </summary>
+    public string? AlarmCategory { get; }
 }

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAlarmSource.cs

@@ -41,6 +41,30 @@ public sealed record AlarmAcknowledgeRequest(
     string? Comment);
 
 /// <summary>Event payload for <see cref="IAlarmSource.OnAlarmEvent"/>.</summary>
+/// <param name="SubscriptionHandle">Subscription this event belongs to.</param>
+/// <param name="SourceNodeId">Driver-side identifier for the alarm source.</param>
+/// <param name="ConditionId">Stable id correlating raise / ack / clear of the same condition.</param>
+/// <param name="AlarmType">Driver-defined alarm type name (e.g. AnalogLimitAlarm.HiHi).</param>
+/// <param name="Message">Human-readable alarm description.</param>
+/// <param name="Severity">Four-bucket severity ladder.</param>
+/// <param name="SourceTimestampUtc">When this transition occurred.</param>
+/// <param name="OperatorComment">
+///     Operator-supplied comment recorded by the upstream alarm system on Acknowledge
+///     transitions. Null on raise / clear, or when the upstream path can't surface
+///     the comment (the Galaxy sub-attribute fallback path collapses comments into a
+///     single string write — null on that path; the driver-native gateway path
+///     populates this).
+/// </param>
+/// <param name="OriginalRaiseTimestampUtc">
+///     When the alarm originally entered the active state. Preserved across
+///     Acknowledge transitions so OPC UA Part 9 conditions keep the original raise
+///     time in <c>Time</c>. Null when the upstream path doesn't surface it.
+/// </param>
+/// <param name="AlarmCategory">
+///     Upstream alarm taxonomy bucket (e.g. <c>Process</c> / <c>Safety</c> /
+///     <c>Diagnostics</c>). Maps to OPC UA <c>ConditionClassName</c> downstream when
+///     a class mapping is configured. Null when the upstream path doesn't carry it.
+/// </param>
 public sealed record AlarmEventArgs(
     IAlarmSubscriptionHandle SubscriptionHandle,
     string SourceNodeId,
@@ -48,7 +72,10 @@ public sealed record AlarmEventArgs(
     string AlarmType,
     string Message,
     AlarmSeverity Severity,
-    DateTime SourceTimestampUtc);
+    DateTime SourceTimestampUtc,
+    string? OperatorComment = null,
+    DateTime? OriginalRaiseTimestampUtc = null,
+    string? AlarmCategory = null);
 
 /// <summary>Mirrors the <c>NodePermissions</c> alarm-severity enum in <c>docs/v2/acl-design.md</c>.</summary>
 public enum AlarmSeverity { Low, Medium, High, Critical }

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/GalaxyDriver.cs

@@ -837,7 +837,10 @@ public sealed class GalaxyDriver
             AlarmType: transition.AlarmTypeName,
             Message: transition.Description,
             Severity: transition.SeverityBucket,
-            SourceTimestampUtc: transition.TransitionTimestampUtc);
+            SourceTimestampUtc: transition.TransitionTimestampUtc,
+            OperatorComment: string.IsNullOrEmpty(transition.OperatorComment) ? null : transition.OperatorComment,
+            OriginalRaiseTimestampUtc: transition.OriginalRaiseTimestampUtc,
+            AlarmCategory: string.IsNullOrEmpty(transition.Category) ? null : transition.Category);
         try
         {
             OnAlarmEvent?.Invoke(this, args);