docs(alarms): OPC UA Enable/Disable wired + native-ack→AVEVA with principal + HistoryUpdate permission bit

docs/AlarmTracking.md

@@ -79,6 +79,42 @@ the dedup.
 
 ## Acknowledge routing — Galaxy / driver alarms
 
+### Native alarm acknowledge → AVEVA
+
+When an OPC UA client Acknowledges a **native** (driver-fed, e.g. Galaxy)
+`AlarmConditionState` node, the node manager's `OnAcknowledge` handler
+branches on native-ness and routes through a dedicated path — separate
+from the scripted `AlarmCommandRouter`:
+
+1. **`OtOpcUaNodeManager.HandleNativeAlarmAck`** — gates on the caller's
+   `AlarmAck` role (fails closed: no role → `BadUserAccessDenied`), then
+   dispatches a `NativeAlarmAck(ConditionNodeId, Comment, OperatorUser)`
+   to the `NativeAlarmAckRouter` seam (fire-and-forget, non-blocking under
+   the node-manager Lock). `OperatorUser` carries the authenticated
+   session principal's display name.
+2. **`DriverHostActor.HandleRouteNativeAlarmAck`** — receives a
+   `RouteNativeAlarmAck` message (the host maps `NativeAlarmAck` at the
+   wiring boundary to keep Runtime Akka-free of the OPC UA layer). Applied
+   **Primary-gate first**: a Secondary or Detached node drops the message
+   silently. On Primary, resolves the condition NodeId from the
+   `_driverRefByAlarmNodeId` inverse map (NodeId → `(DriverInstanceId,
+   FullName)`) and Tells the owning `DriverInstanceActor` a
+   `RouteAlarmAck(FullName, Comment, OperatorUser)`.
+3. **Galaxy driver** — `DriverInstanceActor` calls the driver's
+   `IAlarmSource.AcknowledgeAsync` with an `AlarmAcknowledgeRequest`
+   carrying the authored `FullName` as the `ConditionId` and the
+   authenticated `OperatorUser`. The driver forwards this to the Galaxy
+   gateway → AVEVA via `GatewayGalaxyAlarmAcknowledger`.
+   **Fire-and-forget** — a failed upstream ack is not surfaced back to the
+   OPC UA client (mirrors the Galaxy write-outcome limitation; the local
+   `AlarmConditionState` SDK update already committed at step 1).
+
+Only the **Acknowledge** is routed to the driver. `Confirm` / `AddComment`
+/ `Shelve` operations on a native condition stay on the scripted
+`AlarmCommandRouter` path (Phase 3 scope is Acknowledge → AVEVA only).
+
+### Legacy sub-attribute path
+
 `DriverNodeManager` picks the acknowledger when registering each
 condition (PR B.3 logic):