--- paths: - "src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/**" - "src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/**" - "src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/**" - "docs/ScriptedAlarms.md" - "docs/AlarmTracking.md" --- # Scripted alarm ack/shelve and Part 9 condition method behaviour > Moved verbatim from the root `CLAUDE.md` (2026-10-13) so it loads only when working in this area. > Root `CLAUDE.md` § "Subsystem guides" indexes it. Edit it here, not in the root file. ## Scripted Alarm Ack/Shelve Inbound operator acknowledge/shelve for scripted alarms is fully implemented. Two surfaces converge on the `alarm-commands` DPS topic: (1) OPC UA Part 9 condition methods (Acknowledge / Confirm / AddComment / OneShotShelve / TimedShelve / Unshelve) wired in `OtOpcUaNodeManager`, gated on the `AlarmAck` role — conferred by the session's API-key principal's `NodeAcl` grants (or the `anonymous` principal's), carried by `RoleCarryingUserIdentity`; LDAP is AdminUI-only; (2) AdminUI `/alerts` per-row buttons routed through the `AdminOperationsActor` singleton (gated by `DriverOperator` policy). `ScriptedAlarmHostActor` dispatches from the topic to the engine. Client.CLI supports `ack`, `confirm`, `shelve` commands. See `docs/ScriptedAlarms.md` §"Inbound operator ack/shelve" and `docs/AlarmTracking.md`. ⚠️ **One condition event per accepted method call is OURS, not the SDK's (Gitea #587).** The SDK's own report is gated on `AutoReportStateChanges` (left `false`), so before #587 a client Acknowledge emitted **no** condition event — the old "SDK auto-fires its own event (E2)" comments were wrong. `WireMethodTransitionReporting` wraps every method's SDK handler (Ack/Confirm/AddComment/Enable/Disable/OneShotShelve/TimedShelve/Unshelve) and, on Good, reports once via `ReportConditionEvent` — **under `Lock`**, so the engine's/driver's re-projection (routed by a fire-and-forget Tell *before* the SDK applies state) waits and then hits the delta-gate with no delta. Things to keep: the SDK's shelve handlers never apply shelving, so the wrapper does; only a real before/after change is reported (a re-ack is silent and restores the Confirmed/Retain the SDK flips); `MaxTimeShelved` is set to `int.MaxValue` ms at materialise because `Create()` left it 0 and every TimedShelve failed. ⚠️ **Native alarms support Acknowledge and AddComment only** — Confirm, the shelve methods and Enable/Disable return `BadNotSupported` (no upstream path, no pair replication, and `NativeAlarmProjector`'s Confirmed/Unshelved constants own those fields); a native ack re-asserts `ConfirmedState = true` because the SDK's ack unconfirms any confirm-capable condition and ScadaBridge maps that field. Pinned over the wire by `ConditionMethodEventTests` (exactly-once after a sentinel, folder + `i=2253`). **A native ack the driver refuses or fails is not left Acknowledged (#760).** Two layers: (1) a refusal the driver can decide without I/O (`IAlarmAcknowledgePreflight` — Galaxy, no fallback ack account: an anonymous session, or a keyed session whose key `GalaxyAckIdentityDirectory` reports Absent, #765) fails the Part 9 call `BadUserAccessDenied` via `NativeAlarmAckPreflight`, read lock-free from the `NativeAlarmAckPreflightView` snapshot `DriverHostActor` publishes; never do I/O (e.g. a Secrets lookup) in a pre-check — it runs under the SDK `Lock`; that is why the keyed case reads a cached, periodically refreshed key set (`Drivers:Galaxy:AckIdentityCache`), which must answer Unknown (= let it through) whenever it is not certain — no refresh yet, stale, or an identity-secret change signalled through the decorated `ISecretCacheInvalidator` and not yet re-listed. Only an identity written straight into the store by the `secret` CLI (no in-process signal) can be refused until the next refresh, which the refusal itself requests. (2) anything else (a keyed session the cache cannot vouch for, MXAccess non-zero `hresult`, driver still connecting/reconnecting) comes back as `DriverInstanceActor.AlarmAckFailed` — or, for a disabled/unspawned/stubbed driver, is decided in the host itself (#765) — and `DriverHostActor` re-projects the condition unacknowledged — only while the ack is still pending in `NativeAlarmProjector` (any driver transition since then wins). A host that came up **Stale** cannot route any native ack, so it marks the whole `NativeAlarmAckPreflightView` unavailable and every native ack is refused synchronously until `BecomeSteady` (#765). A test that routes an ack and expects it to STAND must start the owning driver (`AckingAlarmDriver` in Runtime.Tests). Behaviours that were wrong or missing and are now fixed — keep them: the SDK's `OnTimedUnshelve` is a **no-op** (the engine's `AutoUnshelve` owns timed-shelve expiry, and `UnshelveTime` reports the real remaining time from `AlarmConditionSnapshot.UnshelveAtUtc`); a **commented** re-ack is stored as an `AddComment` (durable, replicated) and reports one event, an uncommented re-ack stays silent; a **native ack is refused `BadInvalidState` off-Primary** via `NativeAlarmAckPrimaryGate` (fed by `IDriverPrimaryRoleSource`; `DriverHostActor` publishes its Primary verdict at host start and on member changes, so the boot window before the first redundancy snapshot is closed — the same fix covers the MQTT Sparkplug primary-host claim). A native re-ack is still re-sent to the driver (the retry path, by design). **Condition `Severity` is carried verbatim, clamped to 1..1000** — `ToPart9Severity`; the node manager used to re-bucket onto the five `EventSeverity` points (so an MTConnect Fault read 900, scripted Critical 1000 read 900, native Low 200 read 300). ScadaBridge only clamps, so exact values pass through. ⚠️ **Never select a two-state id with `AddSelectClause(type, "X/Id")`** — the string becomes ONE QualifiedName named `X/Id`, which no event carries; the Client.CLI/Client.UI filter did this since `a2883b82` and every alarm read inactive+unacked. Use `new SimpleAttributeOperand(type, [X, Id])` (ScadaBridge already does). **Condition children are instance-scoped (#629).** Every child of a materialised condition carries `{ConditionId}/{browse path}` in the condition's namespace (e.g. `…/temp_hi/ShelvingState/UnshelveTime`), assigned by the `OtOpcUaNodeManager.New` override — the SDK default kept each child on the TYPE's ns=0 id, so a direct Read hit the type (or `BadNodeIdUnknown`), translate failed, and children sat outside the ACL (the slash join now puts them under their condition's scope). ⚠️ The shelve methods resolve by the `AlarmConditionType_ShelvingState_*` ids only because `New` adopts those (a fixed set) as their `MethodDeclarationId`; calls by the `ShelvedStateMachineType_*` id are no longer supported (pinned by a test). Condition teardown must forget the whole `PredefinedNodes` subtree (`ForgetPredefinedSubtree`) or a removed condition's children keep answering.