docs(scripted-alarms): F14b OPC UA Part 9 SDK research notes (T13)

2026-06-10 18:19:52 -04:00
parent a8640a9331
commit 4217b213b0
1 changed files with 609 additions and 0 deletions
@@ -0,0 +1,609 @@
 # F14b — OPC UA Part 9 Alarm & Condition SDK Notes (T13)
 Reference notes for materialising **real** OPC UA Part 9 Alarm & Condition
 nodes in our `CustomNodeManager2`-based `OtOpcUaNodeManager`, firing events
 on state transitions, and accepting inbound Acknowledge / Confirm / Shelve /
 AddComment method calls. This replaces the current placeholder in
 `OtOpcUaNodeManager.WriteAlarmState`, which only writes a two-element
 `[active, acknowledged]` `BaseDataVariableState` and fires no events.
 Consumed by implementation tasks **T14–T17**.
 ## Provenance (read this first)
 - **DeepWiki MCP: NOT AVAILABLE** in this session. `mcp__deepwiki__*` tools
  were not surfaced by the tool registry (only Gmail/Calendar/Drive/Chrome
  MCP servers were). All findings below come from sources 2 and 3 instead.
 - **Local NuGet cache (authoritative, version-exact).** Every API name,
  ctor, delegate, and method signature below was confirmed by **decompiling
  the exact assembly we reference** — `OPCFoundation.NetStandard.Opc.Ua.*`
  **v1.5.378.106** (pinned in `Directory.Packages.props`), `net10.0` TFM —
  with `ilspycmd`. The Part 9 condition types live in `Opc.Ua.Core.dll`;
  `NodeState` / `ISystemContext` / `IUserIdentity` live in `Opc.Ua.Types.dll`;
  `CustomNodeManager2` lives in `Opc.Ua.Server.dll`.
 - **GitHub reference sample (pattern-level, master branch).** The end-to-end
  node-creation / event-firing / handler-wiring patterns were cross-checked
  against the OPC Foundation reference server at
  `Applications/Quickstarts.Servers/Alarms/` (the `AlarmHolders/*` classes +
  `AlarmNodeManager.cs`). **Caveat:** these samples are on `master`, which is
  slightly ahead of 1.5.378.106 — they use a few newer optional members
  (e.g. `SilenceState`, `OutOfServiceState`, `LatchedState`,
  `PropertyState<T>.With<VariantBuilder>`, `ByteString`). The *core* alarm
  pattern (Create → set state → ReportEvent; OnAcknowledge/OnConfirm
  delegates) is identical in both. Anything sample-only that I could not
  also confirm in the 1.5.378.106 assembly is flagged **[SAMPLE-ONLY]** below.
 ### What's verified vs. uncertain
 | Claim | Status |
 |---|---|
 | Condition/Alarm type names, class hierarchy, ctors | **Verified** in 1.5.378.106 assembly |
 | `SetActiveState` / `SetAcknowledgedState` / `SetConfirmedState` / `SetEnableState` / `SetSeverity` / `SetShelvingState` / `SetSuppressedState` signatures | **Verified** in assembly |
 | `OnAcknowledge` / `OnConfirm` / `OnAddComment` / `OnEnableDisable` / `OnShelve` / `OnTimedUnshelve` delegate field types + signatures | **Verified** in assembly |
 | `NodeState.Create(...)` / `ReportEvent(...)` / `AddNotifier(...)` signatures | **Verified** in assembly |
 | `CustomNodeManager2.AddRootNotifier` / `SubscribeToEvents` / `ConditionRefresh` / `Call` behaviour | **Verified** by decompiling `CustomNodeManager2` |
 | Principal surfacing via `ISessionOperationContext.UserIdentity` (`GetCurrentUserId`) | **Verified** in assembly |
 | End-to-end wiring sequence (folder EventNotifier → AddRootNotifier → alarm.Create → AddChild → ReportEvent) | **Verified** by decompile + cross-checked against reference sample |
 | No packaged base alarm server class — must hand-roll on `CustomNodeManager2` | **Verified** (no `AlarmConditionServer`/`SampleNodeManager` type in the `Opc.Ua.Server` NuGet) |
 | `InitializeAlarmConditionEvent` helper | **DOES NOT EXIST** in this SDK — see Q3 |
 ---
 ## Q1 — Node creation under a `CustomNodeManager2`
 ### Type hierarchy (all in namespace `Opc.Ua`, assembly `Opc.Ua.Core`)
 ```
 BaseObjectState
 └─ BaseEventState                       (EventId, EventType, SourceNode, SourceName, Time, ReceiveTime, Message, Severity)
     └─ ConditionState                   (EnabledState, Retain, ConditionClassId, ConditionName, BranchId, Quality, Comment, AddComment method)
         └─ AcknowledgeableConditionState (AckedState, ConfirmedState, Acknowledge + Confirm methods)
             └─ AlarmConditionState       (ActiveState, SuppressedState, ShelvingState, Shelve/Unshelve methods, ...)
                 ├─ LimitAlarmState        (HighLimit / HighHighLimit / LowLimit / LowLowLimit : PropertyState<double>)
                 │   ├─ ExclusiveLimitAlarmState     (LimitState : ExclusiveLimitStateMachineState; SetLimitState)
                 │   │   ├─ ExclusiveLevelAlarmState
                 │   │   ├─ ExclusiveDeviationAlarmState
                 │   │   └─ ExclusiveRateOfChangeAlarmState
                 │   └─ NonExclusiveLimitAlarmState  (HighState/HighHighState/LowState/LowLowState : TwoStateVariableState; SetLimitState)
                 │       ├─ NonExclusiveLevelAlarmState
                 │       ├─ NonExclusiveDeviationAlarmState
                 │       └─ NonExclusiveRateOfChangeAlarmState
                 ├─ DiscreteAlarmState
                 │   ├─ OffNormalAlarmState
                 │   │   ├─ SystemOffNormalAlarmState
                 │   │   └─ TripAlarmState
                 │   └─ (CertificateExpirationAlarmState, etc.)
                 └─ DiscrepancyAlarmState, InstrumentDiagnosticAlarmState, ...
 ```
 These are all **ModelCompiler-generated** (`[GeneratedCode("Opc.Ua.ModelCompiler")]`).
 Each carries an embedded base64 `InitializationString`: calling `Create(...)`
 builds the **entire mandatory child set** (EnabledState, AckedState,
 ConfirmedState, ActiveState, the Acknowledge/Confirm/AddComment/Enable/Disable
 methods, etc.) automatically. You do **not** hand-build child variables/methods.
 ### Constructors (verified)
 `AlarmConditionState` (and only it, among these) has **two** ctors:
 ```csharp
 public AlarmConditionState(NodeState parent)                              // classic
 public AlarmConditionState(ITelemetryContext telemetry, NodeState parent) // 1.5.378 telemetry-aware
 ```
 `ConditionState`, `AcknowledgeableConditionState`, `LimitAlarmState`,
 `ExclusiveLimitAlarmState`, `NonExclusiveLimitAlarmState`, `OffNormalAlarmState`,
 etc. expose only the **`(NodeState parent)`** ctor in 1.5.378.106.
 > **Recommendation:** prefer the telemetry ctor for `AlarmConditionState`
 > when a telemetry context is reachable (`Server.Telemetry`), matching the
 > reference sample (`new AlarmConditionState(Server.Telemetry, parent)`).
 > The `(NodeState parent)` ctor is fine and is the only option for the
 > non-alarm condition types.
 ### The create-and-parent pattern (verified shape, from `AlarmHolder.InitializeInternal`)
 ```csharp
 // 'parent' is the owning ObjectState/FolderState already in the address space.
 // 'trigger' is the source variable the alarm reports against (optional).
 var alarm = new AlarmConditionState(Server.Telemetry, parent);
 var nodeId      = new NodeId($"{parentId}.{alarmName}", NamespaceIndex);
 var browseName  = new QualifiedName(alarmName, NamespaceIndex);
 var displayName = new LocalizedText(alarmName);
 alarm.SymbolicName    = alarmName;
 alarm.ReferenceTypeId = ReferenceTypeIds.HasComponent;   // how the parent links to it
 // Builds the full mandatory child tree from the embedded type definition.
 alarm.Create(
    SystemContext,   // ISystemContext
    nodeId,          // NodeId   (or null/default to auto-assign)
    browseName,      // QualifiedName
    displayName,     // LocalizedText
    assignNodeIds: true);
 // (optional) point the source variable at the condition
 trigger.AddReference(ReferenceTypeIds.HasCondition, isInverse: false, alarm.NodeId);
 parent.AddChild(alarm);                          // wires the parent→alarm reference
 AddPredefinedNode(SystemContext, alarm);         // registers node + all children with the manager
 ```
 `NodeState.Create` signature (verified):
 ```csharp
 public virtual void Create(ISystemContext context, NodeId nodeId,
                           QualifiedName browseName, LocalizedText displayName,
                           bool assignNodeIds)
 ```
 > **Important:** `AddPredefinedNode(SystemContext, alarm)` registers the alarm
 > **and all the children `Create` minted** into `PredefinedNodes`, so browse /
 > read / method-call routing all work. Our existing `EnsureFolder` /
 > `EnsureVariable` already use `AddPredefinedNode`; the alarm node is the same
 > call. When tearing down, mirror `RebuildAddressSpace`: `parent.RemoveChild`
 > + remove from `PredefinedNodes`.
 ### What makes a node an event-notifier (so clients can subscribe to its events)
 Two things, both required:
 1. The **notifier object** (typically the folder/area the alarms live under,
   or our `_root`) must set
   `EventNotifier = EventNotifiers.SubscribeToEvents` and be registered as a
   **root notifier**:
   ```csharp
   alarmsFolder.EventNotifier = EventNotifiers.SubscribeToEvents;
   AddRootNotifier(alarmsFolder);   // protected, on CustomNodeManager2
   ```
   `AddRootNotifier` (verified) does three things: sets
   `notifier.OnReportEvent = OnReportEvent` (which forwards to
   `Server.ReportEvent`), adds an **inverse `HasNotifier` reference to the
   Server object** (so the Server object becomes the well-known event entry
   point clients subscribe to), and back-fills any existing
   "monitor all events" subscriptions.
 2. The condition node must have a **notifier path up to that root notifier**.
   `alarm.Create(...)` under a parent that is itself a root notifier is the
   simplest path; `ReportEvent` walks **inverse** notifier references upward
   (see Q3). If a condition is several folders deep, each intermediate folder
   needs `EventNotifier = SubscribeToEvents` and an `AddNotifier` /
   `HasNotifier` link, OR just make each alarm folder its own root notifier.
 `NodeState.AddNotifier` (verified):
 ```csharp
 public virtual void AddNotifier(ISystemContext context, NodeId referenceTypeId,
                                bool isInverse, NodeState target)
 // referenceTypeId null ⇒ HasEventSource. Use HasNotifier for object→object notifier chains.
 ```
 > **Simplest robust design for us:** make the single OtOpcUa alarm-root folder
 > a root notifier (`SubscribeToEvents` + `AddRootNotifier`) and `Create` every
 > alarm condition directly (or via plain folders that are themselves root
 > notifiers) under it. Don't over-engineer the notifier hierarchy until a
 > deep-tree requirement appears.
 ---
 ## Q2 — State setters (which take an `ISystemContext`)
 All the `Set*` mutators below are on the condition/alarm types and **take an
 `ISystemContext` first arg** — pass the manager's `SystemContext` (a
 `ServerSystemContext`) or a copy of it. They internally update the relevant
 `TwoStateVariableState` (`.Id.Value`, `.Value` true/false text,
 `TransitionTime`) and flag change masks.
 | Goal | API (verified signature) | Defined on |
 |---|---|---|
 | Active / inactive | `void SetActiveState(ISystemContext context, bool active)` | `AlarmConditionState` |
 | Acked / unacked | `void SetAcknowledgedState(ISystemContext context, bool acknowledged)` | `AcknowledgeableConditionState` |
 | Confirmed / unconfirmed | `void SetConfirmedState(ISystemContext context, bool confirmed)` | `AcknowledgeableConditionState` |
 | Enabled / disabled | `void SetEnableState(ISystemContext context, bool enabled)` | `ConditionState` |
 | Suppressed | `void SetSuppressedState(ISystemContext context, bool suppressed)` | `AlarmConditionState` |
 | Shelving (all 3 transitions) | `void SetShelvingState(ISystemContext context, bool shelved, bool oneShot, double shelvingTime)` | `AlarmConditionState` |
 | Severity | `void SetSeverity(ISystemContext context, EventSeverity severity)` | `ConditionState` |
 | Comment (+ user) | `void SetComment(ISystemContext context, LocalizedText comment, string clientUserId)` | `ConditionState` |
 | Exclusive limit zone | `void SetLimitState(ISystemContext context, LimitAlarmStates limit)` | `ExclusiveLimitAlarmState` |
 | Non-exclusive limit zone | `void SetLimitState(ISystemContext context, LimitAlarmStates limit)` | `NonExclusiveLimitAlarmState` |
 **`SupportsConfirm()`** (verified, on `AcknowledgeableConditionState`) gates
 whether the Confirm sub-state machine is active. The SDK auto-decides this from
 whether `ConfirmedState` was materialised. To enable Confirm you must have a
 `ConfirmedState` child + call `SetConfirmedState` during init.
 ### Properties you set directly (not via a `Set*` helper)
 These are inherited `PropertyState<T>` nodes; assign `.Value` and (for event
 fields) let `ReportEvent` snapshot them:
 | Property | Type (verified) | Notes |
 |---|---|---|
 | `Message` | `PropertyState<LocalizedText>` | event message text |
 | `Severity` | `PropertyState<ushort>` | prefer `SetSeverity` (also stamps `LastSeverity`) |
 | `Time` | `PropertyState<DateTime>` | event source time (UTC); set per event in `ReportEvent` |
 | `ReceiveTime` | `PropertyState<DateTime>` | usually `= Time.Value` |
 | `EventId` | `PropertyState<byte[]>` | **new GUID-bytes per event** (see Q3) |
 | `EventType` | `PropertyState<NodeId>` | set by `Create` from the type; can override |
 | `SourceNode` / `SourceName` | `PropertyState<NodeId>` / `PropertyState<string>` | the originating tag |
 | `Retain` | `PropertyState<bool>` | **drives ConditionRefresh replay** (see Q5) |
 | `ConditionClassId` | `PropertyState<NodeId>` | e.g. `ObjectTypeIds.ProcessConditionClassType` |
 | `ConditionName` | `PropertyState<string>` | human name of the condition |
 | `BranchId` | `PropertyState<NodeId>` | `new NodeId()` (null) for the main branch |
 | `Quality` | `PropertyState<StatusCode>` | usually `StatusCodes.Good` |
 | `EnabledState` | `TwoStateVariableState` | set via `SetEnableState`, not directly |
 `EventSeverity` is the `Opc.Ua.EventSeverity` enum (`Low`/`Medium`/`High`/...);
 `SetSeverity` maps it to the `ushort Severity` value and stamps `LastSeverity`.
 ---
 ## Q3 — Firing an event on a state transition
 ### There is NO `InitializeAlarmConditionEvent` in this SDK
 The method named in the task brief **does not exist** in 1.5.378.106. The real
 firing path is: set the per-event fields, then call `ReportEvent` passing a
 **filter target** that is a snapshot of the node.
 `NodeState.ReportEvent` (verified):
 ```csharp
 public virtual void ReportEvent(ISystemContext context, IFilterTarget e)
 ```
 The reference sample's verbatim pattern (from `ConditionTypeHolder.ReportEvent`):
 ```csharp
 if (alarm.EnabledState.Id.Value)              // only fire if enabled
 {
    alarm.EventId.Value     = Uuid.NewUuid().ToByteString(); // unique per event
    alarm.Time.Value        = DateTime.UtcNow;
    alarm.ReceiveTime.Value = alarm.Time.Value;
    // (Message / Severity / ActiveState / AckedState already set by the Set* calls)
    alarm.ClearChangeMasks(SystemContext, includeChildren: true);
    var snapshot = new InstanceStateSnapshot();
    snapshot.Initialize(SystemContext, alarm);
    alarm.ReportEvent(SystemContext, snapshot);   // IFilterTarget = InstanceStateSnapshot
 }
 ```
 Key points:
 - **`InstanceStateSnapshot`** is the `IFilterTarget` — a frozen copy of the
  condition's fields at fire time, so the event a client receives reflects the
  values *at that instant* even if the live node mutates afterwards. `Initialize`
  reads the node's children into the snapshot.
 - **A fresh `EventId` per event** is mandatory — Acknowledge/Confirm/AddComment
  inbound calls are correlated back to a specific event by this `EventId`
  (`GetEventByEventId` / `GetBranch`). Reusing one breaks ack routing.
 - `ReportEvent` then walks **inverse notifier references upward**: each notifier
  in the chain re-reports, and the root notifier's `OnReportEvent` hands off to
  `Server.ReportEvent`, which queues the event to subscribed monitored items.
 - **Typical transition flow:** `SetActiveState`/`SetAcknowledgedState`/... →
  set `Message`/`Severity` → set `Retain` (active or unacked ⇒ `true`) →
  `ReportEvent`.
 ### Threading / locking
 - **Every node-manager mutation must hold the manager's `Lock`** (we already do
  this in `OtOpcUaNodeManager` — see `WriteValue`/`EnsureFolder`). Creating the
  alarm, the `Set*` calls, and `ReportEvent` must all run **under `lock (Lock)`**.
  `CustomNodeManager2.AddRootNotifier`, `ConditionRefresh`, etc. all take `Lock`
  internally; if you call them while *already* holding `Lock` that's fine (it's
  the same monitor — `Lock` is a plain `object` used with C# `lock`, which is
  re-entrant on the same thread).
 - `ReportEvent` itself does **not** require any extra lock beyond the manager
  `Lock` you already hold for the mutation; the Server's event queue is
  internally synchronised.
 ---
 ## Q4 — Inbound method calls (Acknowledge / Confirm / AddComment / Shelve)
 ### You do NOT route methods by hand
 `alarm.Create(...)` materialises the standard Part 9 methods (`Acknowledge`,
 `Confirm`, `AddComment`, `Enable`, `Disable`, `OneShotShelve`, `TimedShelve`,
 `Unshelve`) as `MethodState` children, and the condition types **wire their own
 `OnCall` handlers in `OnAfterCreate`** (verified):
 ```csharp
 // AcknowledgeableConditionState.OnAfterCreate:
 Acknowledge.OnCall = OnAcknowledgeCalled;
 Confirm.OnCall     = OnConfirmCalled;
 // ConditionState.OnAfterCreate:
 AddComment.OnCall  = OnAddCommentCalled;
 ```
 When a client calls `Acknowledge`, the path is:
 `MasterNodeManager.Call` → `CustomNodeManager2.Call(...)` (verified: routes to
 `MethodState.OnCall`) → `AcknowledgeableConditionState.OnAcknowledgeCalled(...)`.
 The built-in `OnAcknowledgeCalled` (verified body) already does **all of this**
 for you:
 1. `ProcessBeforeAcknowledge` (validates `eventId`, checks `EnabledState`,
   **invokes your `OnAcknowledge` delegate** for veto/permission — see below);
 2. resolves the branch via `GetAcknowledgeableBranch(eventId)`;
 3. `SetAcknowledgedState(context, true)` (+ `SetConfirmedState(false)` if it
   supports confirm);
 4. `SetComment(context, comment, GetCurrentUserId(context))`;
 5. `UpdateRetainState()`;
 6. if events are monitored, `ReportStateChange(...)` **(fires the condition
   event for you)** plus an `AuditConditionAcknowledgeEventState` audit event.
 So for a basic implementation you **don't even need to fire an event after an
 ack** — the SDK does it. You only supply the **veto/permission/business
 delegates**.
 ### Delegate hooks (the wiring point) — verified field types + signatures
 | Hook field | Delegate type | Signature |
 |---|---|---|
 | `AcknowledgeableConditionState.OnAcknowledge` | `ConditionAddCommentEventHandler` | `(ISystemContext context, ConditionState condition, byte[] eventId, LocalizedText comment) → ServiceResult` |
 | `AcknowledgeableConditionState.OnConfirm` | `ConditionAddCommentEventHandler` | same as above |
 | `ConditionState.OnAddComment` | `ConditionAddCommentEventHandler` | same as above |
 | `ConditionState.OnEnableDisable` | `ConditionEnableEventHandler` | `(ISystemContext, ConditionState, bool enabling) → ServiceResult` |
 | `AlarmConditionState.OnShelve` | `AlarmConditionShelveEventHandler` | `(ISystemContext, AlarmConditionState alarm, bool shelving, bool oneShot, double shelvingTime) → ServiceResult` |
 | `AlarmConditionState.OnTimedUnshelve` | `AlarmConditionTimedUnshelveEventHandler` | `(ISystemContext, AlarmConditionState alarm) → ServiceResult` |
 > Note: `OnAcknowledge`, `OnConfirm`, and `OnAddComment` **all use the same
 > delegate type** `ConditionAddCommentEventHandler`
 > `(context, condition, eventId, comment)`, matching the task brief exactly.
 > There is **no** separate `AcknowledgeMethodHandler` / `ConfirmMethodHandler`
 > type — those are not in this SDK.
 Wire them right after `Create` (and after setting initial state):
 ```csharp
 alarm.OnAcknowledge   = OnAcknowledgeHandler;   // ServiceResult OnAcknowledgeHandler(ISystemContext ctx, ConditionState c, byte[] eventId, LocalizedText comment)
 alarm.OnConfirm       = OnConfirmHandler;
 alarm.OnAddComment    = OnAddCommentHandler;
 alarm.OnEnableDisable = OnEnableDisableHandler;
 alarm.OnShelve        = OnShelveHandler;         // only if shelving is supported
 alarm.OnTimedUnshelve = OnTimedUnshelveHandler;
 ```
 Returning a **bad `ServiceResult`** (e.g.
 `StatusCodes.BadUserAccessDenied`, `StatusCodes.BadConditionBranchAlreadyAcked`,
 `StatusCodes.BadEventIdUnknown`) **vetoes** the operation — the SDK aborts the
 state change and returns that status to the client. This is the natural seam for
 our **AlarmAck permission gate** (T17): check the caller's role in
 `OnAcknowledge`, return `BadUserAccessDenied` if they lack `AlarmAck`.
 ### How the calling principal reaches the handler
 The `ISystemContext context` passed into the handler is a `ServerSystemContext`
 (`: SessionSystemContext`) carrying the session's identity. The SDK's own
 `ConditionState.GetCurrentUserId` (verified) reads it as:
 ```csharp
 if (context is ISessionOperationContext { UserIdentity: not null } s)
    return s.UserIdentity.DisplayName;   // IUserIdentity
 ```
 So in our handlers:
 ```csharp
 var identity = (context as ISessionOperationContext)?.UserIdentity; // Opc.Ua.IUserIdentity
 // identity.DisplayName    : string
 // identity.GrantedRoleIds : NodeIdCollection   ← use for the AlarmAck gate
 // identity.TokenType      : UserTokenType
 ```
 `IUserIdentity` (verified) exposes `DisplayName`, `TokenType`, `IssuedTokenType`,
 and **`GrantedRoleIds` (`NodeIdCollection`)** — the latter is what the AlarmAck
 gate should check (or carry our own claims via the identity we set during
 authentication). `ServerSystemContext` is constructed from the `OperationContext`
 / `ISession` (`UserIdentity = session.Identity`), so the principal is whoever
 authenticated the calling session via our `IOpcUaUserAuthenticator` /
 `LdapOpcUaUserAuthenticator`.
 > The reference sample also uses `context.UserId` (a `string`) inside handlers —
 > that resolves on the concrete `SystemContext`/`IOperationContext`. Prefer the
 > `ISessionOperationContext.UserIdentity` cast above: it's what the SDK itself
 > uses and gives the full `IUserIdentity` (roles), not just a display string.
 ### Shelve specifics
 - Client `OneShotShelve` / `TimedShelve` / `Unshelve` methods call into
  `AlarmConditionState.OnOneShotShelve` / `OnTimedShelve` / `OnUnshelve`, which
  invoke your `OnShelve` (with `shelving`/`oneShot`/`shelvingTime` flags) and
  `OnTimedUnshelve` delegates, then call `SetShelvingState`.
 - The `ShelvingState` is a `ShelvedStateMachineState` child; for timed shelve
  the SDK runs an internal timer (`UnshelveTimeUpdateRate`,
  `OnTimerExpired`/`OnUnshelveTimeUpdate`) that auto-unshelves. `UnshelveTime`
  is a calculated property (read handler `OnReadUnshelveTime`).
 - **[SAMPLE-ONLY]** `SilenceState`, `OutOfServiceState`, `LatchedState`,
  `MaxTimeShelved` are created as **optional** children in the master sample.
  In 1.5.378.106 the `ShelvingState`/`SuppressedState`/`OutOfServiceState`/
  `SilenceState`/`LatchedState` properties **exist** on `AlarmConditionState`,
  but you must materialise the optional ones yourself before `Create`
  (e.g. `alarm.ShelvingState = new ShelvedStateMachineState(alarm)` then
  `ShelvingState.Create(...)`). For our first pass we likely only need
  ActiveState + AckedState + (optional) ConfirmedState + ShelvingState.
 ---
 ## Q5 — Gotchas / threading / ConditionRefresh / base server
 ### Dispatcher / threading
 - All node-manager mutations under **`lock (Lock)`** (already our convention).
  Build + `Create` + `Set*` + `ReportEvent` for one transition in a single
  critical section so a client never observes a half-applied state.
 - `CustomNodeManager2.Lock` is a plain `object` used with `lock` — re-entrant
  on the same thread, so calling `AddRootNotifier`/`ConditionRefresh` while
  holding it is safe.
 ### EventId / branches
 - **Fresh `EventId` per `ReportEvent`** (GUID bytes). Inbound
  Acknowledge/Confirm carry the `eventId` of the event being acked; the SDK
  matches it via `GetEventByEventId` / `GetAcknowledgeableBranch` /
  `GetBranch(eventId)`.
 - **Branches** (`CreateBranch(context, branchId)` →
  `ConditionState`) model "a previous unacked occurrence while a new one is
  already active". They are **optional** — only needed if we want the
  ack-the-old-while-new-is-active semantics. **For T14–T17 we can skip
  branching initially** (main branch `BranchId = new NodeId()` / null) and add
  it later; our `Part9StateMachine` doesn't model branches today.
 ### ConditionRefresh (must work, or clients can't recover retained state)
 - When a client (re)subscribes to events and calls the `ConditionRefresh`
  method, `CustomNodeManager2.ConditionRefresh` (verified) iterates the
  monitored items, calls `node.ConditionRefresh(context, events, true)` on each
  root notifier (or the specific source node), collects the retained condition
  events, and queues a refresh batch to that monitored item.
 - For this to replay our active/unacked alarms, **each live condition must have
  `Retain.Value == true`** while it should appear in a refresh (Part 9 rule:
  retain while active OR unacknowledged OR unconfirmed). The built-in
  `UpdateRetainState`/`GetRetainState` handles this if you keep ack/active state
  in sync; if you compute retain yourself, set `alarm.Retain.Value` on every
  transition. **`CustomNodeManager2.ConditionRefresh` is `public virtual` and
  already implemented** — we get refresh "for free" as long as the alarms are
  registered (`AddPredefinedNode`) and reachable from a root notifier with
  correct `Retain`.
 ### Is there a base alarm server to lean on? — **No (in NuGet).**
 - The `OPCFoundation.NetStandard.Opc.Ua.Server` **NuGet package** contains
  **no** `AlarmConditionServer`, `SampleNodeManager`, or alarm-holder helper.
  Confirmed: the only alarm/condition type in `Opc.Ua.Server` is the interface
  `IConditionRefreshAsyncNodeManager`. The `AlarmConditionServer` /
  `Quickstarts.Servers` code lives **only in the GitHub repo's
  `Applications/` tree**, which is *not* packaged.
 - **Therefore we hand-roll on `CustomNodeManager2`** (which we already
  subclass). The base class gives us everything load-bearing:
  - `Call` → routes client method calls to `MethodState.OnCall` (so
    Acknowledge/Confirm/AddComment/Shelve "just work" once `Create` runs);
  - `SubscribeToEvents` / `SubscribeToAllEvents` → flips
    `node.SetAreEventsMonitored` so `EventsMonitored()` gates audit-event
    emission;
  - `AddRootNotifier` / `RemoveRootNotifier` → notifier wiring to the Server
    object;
  - `ConditionRefresh` → retained-event replay;
  - `AddPredefinedNode` → node registration (we use it already).
 - The reference `AlarmHolders/*` classes are a **good pattern reference to
  copy selectively** (Create → set state → ReportEvent; delegate wiring), but
  they're tangled with the sample's controllers/branching/optional-children
  scaffolding we don't need. Lift the *shape*, not the whole hierarchy.
 ---
 ## Mapping to our existing domain model (for T14–T17)
 We already have a **pure** Part 9 state machine and domain records in
 `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/`:
 `Part9StateMachine` (`ApplyAcknowledge`/`ApplyConfirm`/`ApplyOneShotShelve`/
 `ApplyTimedShelve`/`ApplyUnshelve`/`ApplyEnable`/`ApplyDisable`/`ApplyAddComment`/
 `ApplyShelvingCheck`) and the `AlarmConditionState` / `ShelvingState` /
 `AlarmComment` records.
 **The SDK node is a *projection* of that domain state, not a second source of
 truth.** Recommended split:
 - **Inbound (client → us):** keep the SDK delegates *thin*. In
  `OnAcknowledge`/`OnConfirm`/`OnShelve`/etc., (a) run the **AlarmAck permission
  gate** off `ISessionOperationContext.UserIdentity`, returning a bad
  `ServiceResult` to veto if denied; (b) translate to the matching
  `Part9StateMachine.Apply*` call against our domain state; (c) let the
  resulting domain transition drive the authoritative store. You can either let
  the SDK's built-in `OnAcknowledgeCalled` post-processing apply the SDK-side
  state change + event, or set state yourself — but don't double-fire.
 - **Outbound (engine → clients):** when our `ScriptedAlarmEngine` produces a new
  `AlarmConditionState` (active/severity/ack changes), project it onto the SDK
  node: `SetActiveState` / `SetAcknowledgedState` / `SetConfirmedState` /
  `SetSeverity` / set `Message` + `Retain`, then `ReportEvent` — all under
  `lock (Lock)`.
 - This replaces `OtOpcUaNodeManager.WriteAlarmState`'s `[active, ack]` boolean
  pair with a real `AlarmConditionState` node keyed by the same alarm node id.
 ---
 ## Minimal end-to-end sketch (what T14–T16 build toward)
 ```csharp
 // --- one-time, in CreateAddressSpace or first alarm registration (under Lock) ---
 _alarmsFolder.EventNotifier = EventNotifiers.SubscribeToEvents;
 AddRootNotifier(_alarmsFolder);
 // --- register one alarm condition (under Lock) ---
 var alarm = new AlarmConditionState(Server.Telemetry, _alarmsFolder);
 alarm.SymbolicName    = name;
 alarm.ReferenceTypeId = ReferenceTypeIds.HasComponent;
 alarm.Create(SystemContext, new NodeId($"{parentId}.{name}", NamespaceIndex),
             new QualifiedName(name, NamespaceIndex), new LocalizedText(name), true);
 alarm.ConditionName.Value   = name;
 alarm.ConditionClassId.Value = ObjectTypeIds.BaseConditionClassType;   // or a specific class
 alarm.SetEnableState(SystemContext, true);
 alarm.SetActiveState(SystemContext, false);
 alarm.SetAcknowledgedState(SystemContext, true);
 alarm.Retain.Value = false;
 alarm.OnAcknowledge   = OnAck;     // permission gate + domain Apply
 alarm.OnConfirm       = OnConfirm;
 alarm.OnAddComment    = OnAddComment;
 alarm.OnEnableDisable = OnEnableDisable;
 _alarmsFolder.AddChild(alarm);
 AddPredefinedNode(SystemContext, alarm);
 _alarms[alarmNodeId] = alarm;
 // --- on an engine-driven transition (under Lock) ---
 alarm.SetActiveState(SystemContext, active: true);
 alarm.SetAcknowledgedState(SystemContext, acknowledged: false);
 alarm.SetSeverity(SystemContext, EventSeverity.High);
 alarm.Message.Value = new LocalizedText("en", "High temperature");
 alarm.Retain.Value  = true;                          // active|unacked ⇒ retain
 alarm.EventId.Value = Uuid.NewUuid().ToByteString();
 alarm.Time.Value = alarm.ReceiveTime.Value = DateTime.UtcNow;
 alarm.ClearChangeMasks(SystemContext, true);
 var snap = new InstanceStateSnapshot();
 snap.Initialize(SystemContext, alarm);
 alarm.ReportEvent(SystemContext, snap);
 // --- inbound ack handler (called by SDK Call routing; on a server thread) ---
 ServiceResult OnAck(ISystemContext ctx, ConditionState c, byte[] eventId, LocalizedText comment)
 {
    var id = (ctx as ISessionOperationContext)?.UserIdentity;
    if (!HasAlarmAck(id)) return StatusCodes.BadUserAccessDenied;   // T17 gate
    // translate to Part9StateMachine.ApplyAcknowledge(...) against domain state
    return ServiceResult.Good;   // returning Good lets the SDK set acked state + fire the event
 }
 ```
 ---
 ## Open uncertainties to validate during T14–T17
 1. **Telemetry ctor vs classic ctor at runtime.** We verified both ctors exist;
   confirm `Server.Telemetry` (`ITelemetryContext`) is non-null in our host
   before relying on the telemetry ctor — fall back to `new AlarmConditionState(parent)`
   if not. (Not load-bearing; pick whichever the host supports.)
 2. **Optional children before `Create`.** Whether `ShelvingState` /
   `ConfirmedState` are auto-created by `Create` or must be instantiated first
   (the sample instantiates them) — **[SAMPLE-ONLY]** behaviour; verify by
   inspecting the live node after `Create` (browse the children). If Confirm /
   Shelve children are missing, materialise them like the sample before `Create`.
 3. **`InstanceStateSnapshot` vs reporting the node directly.** The sample uses
   an `InstanceStateSnapshot` as the `IFilterTarget`. Confirm whether reporting
   the alarm node itself (which is also an `IFilterTarget`) is acceptable — the
   snapshot is safer (frozen values) and is the documented pattern; default to it.
 4. **Double-event on inbound ack.** The built-in `OnAcknowledgeCalled` already
   fires `ReportStateChange` after a successful ack. Make sure our handler does
   **not** also call `ReportEvent` for the same transition (would double-emit).
   Decide whether to drive SDK state from the handler return (let SDK fire) or
   suppress the SDK's auto-state-change and project from the engine.
 5. **`GrantedRoleIds` vs our own claim model.** Confirm whether our
   `LdapOpcUaUserAuthenticator` populates `IUserIdentity.GrantedRoleIds`, or
   whether the AlarmAck permission lives on a custom identity we set. The gate
   in `OnAcknowledge` must read whichever surface our auth actually fills.
 ---
 *All API names/signatures verified against `OPCFoundation.NetStandard.Opc.Ua.*`
 v1.5.378.106 (`net10.0`) via `ilspycmd` decompilation, cross-checked against the
 OPC Foundation reference server samples at
 `UA-.NETStandard/Applications/Quickstarts.Servers/Alarms/` (master). DeepWiki
 MCP was unavailable; no claim here rests on it.*