fix(alarms): surface a refused native alarm ack synchronously, revert one that fails later (lmxopcua#760)

The native-ack path is fire-and-forget after the Part 9 Acknowledge returns, so
a Galaxy ack refused for lack of a credential (#749), or rejected by MXAccess,
left the client with Good and the condition showing Acknowledged while Galaxy
was never acked. Both options from the issue, layered:

1. Synchronous refusal for what the driver can decide without I/O. New optional
   IAlarmAcknowledgePreflight (Core.Abstractions); GalaxyDriver refuses an
   anonymous session when the driver has no AlarmAck fallback account.
   DriverHostActor publishes a condition NodeId -> owning-driver snapshot into
   NativeAlarmAckPreflightView (lock-free, volatile); the node manager's new
   NativeAlarmAckPreflight seam, consulted after the authz and Primary gates,
   returns BadUserAccessDenied with the reason - nothing routed, applied or
   reported. A keyed session is not pre-checked (its identity lives in the
   Secrets store, which must not be read under the SDK lock).

2. Revert for everything else. RouteAlarmAck carries the condition NodeId;
   DriverInstanceActor replies AlarmAckFailed on a refusal, a backend failure,
   a driver without an alarm source, or an ack dropped while connecting /
   reconnecting. DriverHostActor re-projects the condition unacknowledged via
   NativeAlarmProjector.TryRevertAcknowledge, but only while the local ack is
   still pending - any driver transition projected since then wins. A disabled
   or unspawned driver is not reverted (unchanged).

GatewayGalaxyAlarmAcknowledger now throws DriverOperationRefusedException on a
non-zero native hresult (wrong password, no ack permission) instead of only
warning, so that case reverts too; as a refusal it neither retries nor trips
the breaker.

Tests (each fails with its fix mutated out): projector revert/supersede,
DriverHostActor refused + failed ack -> unacked AlarmStateUpdate (successful
ack control), preflight view snapshot, node-manager preflight unit test,
over-the-wire ConditionMethodEventTests (BadUserAccessDenied, no route, no
event; positive control), Galaxy preflight + hresult refusal.
Docs: Galaxy.md, AlarmTracking.md, ScriptedAlarms.md, .claude/rules/alarms.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 13:12:17 -05:00
parent 0217d36cf4
commit 8e8d4cdf13
21 changed files with 737 additions and 61 deletions
@@ -530,6 +530,62 @@ public class NativeAlarmProjectorTests
snap.Active.ShouldBeTrue();
}
/// <summary>
/// lmxopcua#760 — an acknowledge the driver refused reverts the condition: the snapshot keeps the active
/// state, message, severity and source quality and is unacknowledged, and the next driver Clear projects
/// from the reverted (unacked) prior rather than the optimistic ack.
/// </summary>
[Fact]
public void TryRevertAcknowledge_reverts_a_pending_local_ack()
{
var sut = new NativeAlarmProjector();
sut.Project("n1", Evt(AlarmTransitionKind.Raise, AlarmSeverity.Critical, "boom"));
sut.MarkAcknowledged("n1");
sut.TryRevertAcknowledge("n1", out var reverted).ShouldBeTrue();
reverted.ShouldNotBeNull();
reverted.Active.ShouldBeTrue();
reverted.Acknowledged.ShouldBeFalse();
reverted.Severity.ShouldBe((ushort)900);
reverted.Message.ShouldBe("boom");
reverted.StatusCode.ShouldBe(OpcUaStatus.Good);
sut.Project("n1", Evt(AlarmTransitionKind.Clear)).Acknowledged.ShouldBeFalse(
"the reverted ack must not come back on the next Clear");
}
/// <summary>lmxopcua#760 — a revert happens at most once per local ack, and never without one.</summary>
[Fact]
public void TryRevertAcknowledge_without_a_pending_ack_does_nothing()
{
var sut = new NativeAlarmProjector();
sut.TryRevertAcknowledge("untracked", out var none).ShouldBeFalse();
none.ShouldBeNull();
sut.Project("n1", Evt(AlarmTransitionKind.Raise));
sut.TryRevertAcknowledge("n1", out _).ShouldBeFalse("nothing was acknowledged locally");
sut.MarkAcknowledged("n1");
sut.TryRevertAcknowledge("n1", out _).ShouldBeTrue();
sut.TryRevertAcknowledge("n1", out _).ShouldBeFalse("a second failure report must not revert twice");
}
/// <summary>
/// lmxopcua#760 — once a driver transition for the condition has been projected after the local ack, that
/// transition is authoritative: a late failure report does not rewrite it.
/// </summary>
[Fact]
public void A_driver_transition_after_the_ack_supersedes_a_late_failure()
{
var sut = new NativeAlarmProjector();
sut.Project("n1", Evt(AlarmTransitionKind.Raise));
sut.MarkAcknowledged("n1");
sut.Project("n1", Evt(AlarmTransitionKind.Acknowledge)).Acknowledged.ShouldBeTrue();
sut.TryRevertAcknowledge("n1", out var snapshot).ShouldBeFalse();
snapshot.ShouldBeNull();
}
private static AlarmEventArgs Evt(
AlarmTransitionKind kind,
AlarmSeverity sev = AlarmSeverity.High,