feat(alarms): condition Quality tracks source connectivity (#477)

Part 9 ConditionType.Quality was never assigned; default(StatusCode)==Good so every native + scripted condition reported Good unconditionally — a comms-lost device still showed a healthy, inactive, Good condition (a wrong-VALUE bug, distinct from the null-value #473/#475). Clients (and HMIs bucketing on IsGood) could not tell "genuinely inactive" from "lost contact". Layer 1 — make Quality a real, plumbed field: - AlarmConditionSnapshot gains OpcUaQuality Quality (default Good). - MaterialiseAlarmCondition sets it (native BadWaitingForInitialData, scripted Good). - WriteAlarmCondition projects snapshot.Quality; the delta-gate gains a Quality member so a quality-bucket change fires a Part 9 event. Layer 2 — drive native quality from driver connectivity (a comms-lost driver emits no alarm transitions, and an alarm-bearing raw tag has no value variable, so quality can't come from either existing channel): - DriverInstanceActor Tells parent ConnectivityChanged on Connected/Reconnecting. - DriverHostActor fans it to every native condition the driver owns as OpcUaPublishActor.AlarmQualityUpdate (Good on connect, Bad on disconnect). - New dedicated IOpcUaAddressSpaceSink.WriteAlarmQuality sets ONLY Quality and fires only on a bucket change — never touches Active/Acked/Retain (an active alarm that loses comms stays active). Not a full-snapshot re-projection, so it can't clobber severity/message and works for a never-fired condition. Forwarded through DeferredAddressSpaceSink (F10b trap; auto-verified by the reflection forwarding guard). Ungated by redundancy role; no /alerts row. Scripted conditions stay Good; worst-of-input quality deferred to #478 (Layer 3). Tests: node-level (materialise/project/no-clobber/unknown-node no-op), NativeAlarmProjector, DriverInstanceActor connectivity emission, DriverHostActor fan-out, OpcUaPublishActor routing, and the wire-level guard (Condition_event_Quality_tracks_source_connectivity_on_the_wire) — RED-verified against a simulated pre-fix always-Good server. Existing DriverInstanceActor parent probes ignore the new ConnectivityChanged. Docs: docs/AlarmTracking.md §"Condition source-data Quality (#477)"; design doc docs/plans/2026-07-17-alarm-condition-quality-477-design.md.
2026-07-17 15:10:04 -04:00
parent f6a3c31b60
commit db751d12a5
30 changed files with 752 additions and 7 deletions
@@ -497,6 +497,16 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
                condition.SetSeverity(SystemContext, MapSeverity(state.Severity));
                condition.Message.Value = new LocalizedText(state.Message);

+                // #477 — project the source-data quality. A Good→Bad bucket change is a genuine condition
+                // change (it's in the delta-gate above), so it fires a Part 9 event carrying the new Quality;
+                // it never touches Active/Acked/Retain (annotation only). Quality is an optional Part 9 child —
+                // null-guard it like Confirmed/Shelving in case a leaner SDK child set omits it.
+                if (condition.Quality is not null)
+                {
+                    condition.Quality.Value = StatusFromQuality(state.Quality);
+                    if (condition.Quality.SourceTimestamp is not null) condition.Quality.SourceTimestamp.Value = sourceTimestampUtc;
+                }
+
                // Part 9: retain the condition while it is active OR unacknowledged so a client's
                // ConditionRefresh replays it. The event firing below also depends on this Retain being
                // correct (a non-retained inactive+acked condition still fires its transition event, but
@@ -535,6 +545,50 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
        }
    }

+    /// <summary>
+    ///     #477 Layer 2 — apply a source-data quality annotation to a materialised condition, OUT OF BAND
+    ///     from any alarm transition. Used by the driver-connectivity path (comms lost → Bad, restored →
+    ///     Good) so a native condition whose device is unreachable stops reporting the accidentally-Good
+    ///     default. This sets ONLY <see cref="ConditionState.Quality"/> — it never touches
+    ///     Active / Acked / Severity / Retain (a comms-lost active alarm must stay active). A change in the
+    ///     quality bucket is a genuine Part 9 condition change, so it fires one condition event carrying the
+    ///     new Quality; an unchanged bucket suppresses (no spurious event). Unknown / unmaterialised node ⇒
+    ///     safe no-op (a mid-rebuild race must not fault a connectivity update), mirroring the other writes.
+    /// </summary>
+    /// <param name="alarmNodeId">The condition node id (RawPath for a native alarm).</param>
+    /// <param name="quality">The source-data quality to annotate.</param>
+    /// <param name="sourceTimestampUtc">Timestamp of the connectivity transition in UTC.</param>
+    /// <param name="realm">The condition's address-space realm.</param>
+    public void WriteAlarmQuality(string alarmNodeId, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(alarmNodeId);
+        EnsureAddressSpaceCreated();
+
+        var key = MapKey(realm, alarmNodeId);
+        lock (Lock)
+        {
+            // Only materialised conditions carry a Quality child; a bare value variable or a missing node is
+            // a no-op (the connectivity fan-out visits every condition the driver owns, some of which a
+            // concurrent rebuild may have just cleared).
+            if (!_alarmConditions.TryGetValue(key, out var condition) || condition.Quality is null)
+                return;
+
+            var newCode = StatusFromQuality(quality);
+            var changed = condition.Quality.Value.Code != newCode.Code;
+
+            condition.Quality.Value = newCode;
+            if (condition.Quality.SourceTimestamp is not null) condition.Quality.SourceTimestamp.Value = sourceTimestampUtc;
+
+            // Fire ONLY on a real bucket change so a steady-state connectivity re-assert doesn't spam events.
+            if (changed)
+            {
+                condition.Time.Value = sourceTimestampUtc;
+                condition.ReceiveTime.Value = sourceTimestampUtc;
+                ReportConditionEvent(condition, sourceTimestampUtc);
+            }
+        }
+    }
+
    /// <summary>
    ///     Fire a real OPC UA Part 9 condition event for one engine-driven state transition on a
    ///     materialised <see cref="AlarmConditionState"/>. The caller MUST already hold <c>Lock</c> and
@@ -650,7 +704,11 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
        bool Enabled,
        AlarmShelvingKind Shelving,
        ushort MappedSeverity,
-        string Message);
+        string Message,
+        // #477 — the source-data quality bucket. Included so a quality-only transition (e.g. a device
+        // going comms-lost: Good→Bad with no state change) is a genuine delta and fires a Part 9 event.
+        // StatusCode has value equality, so the record struct's == still holds.
+        StatusCode Quality);

    /// <summary>Decide whether a <see cref="WriteAlarmCondition"/> projection is a genuine state change
    /// (and so should fire a Part 9 condition event) by comparing the node's pre-projection state to the
@@ -676,7 +734,10 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
        Enabled: condition.EnabledState?.Id?.Value ?? true,
        Shelving: ReadShelvingKind(condition),
        MappedSeverity: condition.Severity?.Value ?? (ushort)0,
-        Message: condition.Message?.Value?.Text ?? string.Empty);
+        Message: condition.Message?.Value?.Text ?? string.Empty,
+        // Optional Part 9 child; a node without it reads as Good (matching the accidentally-Good default
+        // and ToConditionDelta's fold), so a snapshot Quality can't create a phantom delta against it.
+        Quality: condition.Quality?.Value ?? StatusCodes.Good);

    /// <summary>Build the gate-relevant slice from the incoming snapshot, normalising the two fields that
    /// the node stores in a derived form: Severity is run through <see cref="MapSeverity"/> so it matches
@@ -694,7 +755,10 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
        // node's read-back default (Unshelved).
        Shelving: condition.ShelvingState is not null ? state.Shelving : AlarmShelvingKind.Unshelved,
        MappedSeverity: (ushort)MapSeverity(state.Severity),
-        Message: state.Message ?? string.Empty);
+        Message: state.Message ?? string.Empty,
+        // If the node has no Quality child, WriteAlarmCondition's projection is a no-op there; fold to the
+        // node's read-back default (Good) so a snapshot Quality can't register a spurious delta.
+        Quality: condition.Quality is not null ? StatusFromQuality(state.Quality) : StatusCodes.Good);

    /// <summary>Map the live shelving state machine's CurrentState back to our 3-way
    /// <see cref="AlarmShelvingKind"/> by matching its well-known Part 9 state object id. Any node without
@@ -827,6 +891,20 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
            if (alarm.ConditionClassId is not null) alarm.ConditionClassId.Value = ObjectTypeIds.BaseConditionClassType;
            if (alarm.ConditionClassName is not null) alarm.ConditionClassName.Value = new LocalizedText("BaseConditionClass");

+            // #477 — ConditionType.Quality (the quality of the condition's source data). Create() leaves it
+            // UNSET, and default(StatusCode) == StatusCodes.Good (0x0), so an unassigned Quality reports Good
+            // unconditionally — a wrong VALUE (not a null), which hides a comms-lost source. A NATIVE condition
+            // has no data yet at materialise (its driver hasn't confirmed connectivity), so it starts
+            // BadWaitingForInitialData — the same "no driver data yet" convention value variables use — and is
+            // driven Good by the driver-connectivity path (DriverHostActor → ProjectQuality) once Connected. A
+            // SCRIPTED condition is script-computed and always live in v1, so it starts Good. Quality is a pure
+            // annotation: it NEVER alters Active/Acked/Retain (a comms-lost active alarm must stay active).
+            if (alarm.Quality is not null)
+            {
+                alarm.Quality.Value = isNative ? StatusCodes.BadWaitingForInitialData : StatusCodes.Good;
+                if (alarm.Quality.SourceTimestamp is not null) alarm.Quality.SourceTimestamp.Value = DateTime.UtcNow;
+            }
+
            // Initial state via the SDK setters (T14: basic state only, NO event firing).
            alarm.SetEnableState(SystemContext, true);
            alarm.SetActiveState(SystemContext, false);
@@ -28,6 +28,9 @@ public sealed class SdkAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgicalAddre
    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc, AddressSpaceRealm realm)
        => _nodeManager.WriteAlarmCondition(alarmNodeId, state, sourceTimestampUtc, realm);

+    public void WriteAlarmQuality(string alarmNodeId, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm)
+        => _nodeManager.WriteAlarmQuality(alarmNodeId, quality, sourceTimestampUtc, realm);
+
    /// <inheritdoc />
    public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, AddressSpaceRealm realm, bool isNative = false)
        => _nodeManager.MaterialiseAlarmCondition(alarmNodeId, equipmentNodeId, displayName, alarmType, severity, realm, isNative);