docs(probe): align RPC-doc hedging with the findings doc; attribute rig-state inventory

This commit is contained in:
Joseph Doherty
2026-08-18 07:23:33 -04:00
parent 5417222f44
commit 1605f542cc
3 changed files with 6 additions and 4 deletions
+2 -1
View File
@@ -414,7 +414,8 @@ classification hypothesis above, which the read-only probe could only infer.
The third attempt changed nothing. `TestMachine_001.TestAlarm001` and its `.Acked` subtag The third attempt changed nothing. `TestMachine_001.TestAlarm001` and its `.Acked` subtag
both read `false` at the end of the session, matching the state the second attempt left. both read `false` at the end of the session, matching the state the second attempt left.
The three `TestMachine_00{1,2,3}.TestAlarm001` UDAs are back to `false` and their The second attempt's inventory, unchanged since: the three
`TestMachine_00{1,2,3}.TestAlarm001` UDAs are back to `false` and their
`.InAlarm` subtags read `false`, but each leaves a `UNACK_RTN` record in the wnwrap `.InAlarm` subtags read `false`, but each leaves a `UNACK_RTN` record in the wnwrap
snapshot, since nothing can acknowledge them away. `SnapshotActiveAlarms` counts only snapshot, since nothing can acknowledge them away. `SnapshotActiveAlarms` counts only
`UNACK_ALM` and `ACK_ALM` as active, so these are inert for the gateway; they will clear on `UNACK_ALM` and `ACK_ALM` as active, so these are inert for the gateway; they will clear on
+1 -1
View File
@@ -92,7 +92,7 @@ An accepted gRPC command payload can still be too large for the worker pipe: the
`AcknowledgeAlarm` is a unary, **session-less** RPC that acknowledges a single alarm. The handler validates `alarm_full_reference` inline (it does not run through `MxAccessGrpcRequestValidator`) and delegates to `IGatewayAlarmService.AcknowledgeAsync`. The always-on `GatewayAlarmMonitor` routes the ack over its own gateway-managed worker session — clients no longer open a session to acknowledge an alarm. A reference that parses as a canonical GUID forwards to `AcknowledgeAlarmCommand`; a `Provider!Group.Tag` reference forwards to `AcknowledgeAlarmByNameCommand`. `AcknowledgeAlarm` is a unary, **session-less** RPC that acknowledges a single alarm. The handler validates `alarm_full_reference` inline (it does not run through `MxAccessGrpcRequestValidator`) and delegates to `IGatewayAlarmService.AcknowledgeAsync`. The always-on `GatewayAlarmMonitor` routes the ack over its own gateway-managed worker session — clients no longer open a session to acknowledge an alarm. A reference that parses as a canonical GUID forwards to `AcknowledgeAlarmCommand`; a `Provider!Group.Tag` reference forwards to `AcknowledgeAlarmByNameCommand`.
An `OK` response means the alarm provider accepted the acknowledgement, not that it applied it: the gateway forwards the ack and reports what the provider returned, in keeping with the parity rule. On galaxies whose alarmed attributes carry a non-free-access security classification the by-name ack is accepted and inert — the underlying `AlarmAckByName` conveys an operator name rather than an authenticated identity — so a client that needs to confirm an acknowledgement should watch for the resulting transition on `StreamAlarms` instead of treating `OK` as proof. See [Alarm Probe Findings](./AlarmProbeFindings.md). An `OK` response means the alarm provider accepted the acknowledgement, not that it applied it: the gateway forwards the ack and reports what the provider returned, in keeping with the parity rule. On galaxies whose alarmed attributes carry a non-free-access security classification the by-name ack is accepted and inert — the underlying `AlarmAckByName` conveys an operator name rather than an authenticated identity, observed on the probe rig with the mechanism inferred rather than confirmed — so a client that needs to confirm an acknowledgement should watch for the resulting transition on `StreamAlarms` instead of treating `OK` as proof. See [Alarm Probe Findings](./AlarmProbeFindings.md).
### `StreamAlarms` ### `StreamAlarms`
+3 -2
View File
@@ -232,8 +232,9 @@ successful return means the provider accepted the call, not that the
acknowledgement was applied. On galaxies whose alarmed attributes carry a acknowledgement was applied. On galaxies whose alarmed attributes carry a
non-free-access security classification, `AlarmAckByName` returns `rc=0` and the non-free-access security classification, `AlarmAckByName` returns `rc=0` and the
alarm stays `UNACK_ALM` — it carries an operator name, not an authenticated alarm stays `UNACK_ALM` — it carries an operator name, not an authenticated
identity. Confirm an ack by the resulting transition, never by the return code. identity. (Observed on the probe rig; the mechanism is inferred.) Confirm an ack
See `docs/AlarmProbeFindings.md`. by the resulting transition, never by the return code. See
`docs/AlarmProbeFindings.md`.
**Degraded state visibility:** every subtag-mode transition carries **Degraded state visibility:** every subtag-mode transition carries
`degraded = true` and `source_provider = ALARM_PROVIDER_MODE_SUBTAG` on the `degraded = true` and `source_provider = ALARM_PROVIDER_MODE_SUBTAG` on the