docs(probe): close superseded unblock bullet, hedge the summary, evidence gobject_id, ack-caveat in RPC docs

This commit is contained in:
Joseph Doherty
2026-08-18 07:03:20 -04:00
parent 462850afb7
commit bc22792a36
3 changed files with 23 additions and 4 deletions
+13 -4
View File
@@ -258,7 +258,9 @@ MXAccess-side entry point and the wnwrap-side entry point is inert.
requirement that the wnwrap consumer, which passes an operator *name* string and no requirement that the wnwrap consumer, which passes an operator *name* string and no
authenticated identity, cannot meet. If so, ack over wnwrap is not merely untested here authenticated identity, cannot meet. If so, ack over wnwrap is not merely untested here
but unavailable by configuration, and the gateway's `AcknowledgeByName` path needs the but unavailable by configuration, and the gateway's `AcknowledgeByName` path needs the
same treatment on any customer galaxy configured that way. same treatment on any customer galaxy configured that way. (Answered by the Third attempt
below — enforced by the alarm attribute's `MxSecurityOperate` security classification, an
engine-level write-security setting, not a separate `alarmmgr`-side ack policy.)
- If neither lands, the acknowledge leg stays assumed. It is worth restating that this is a - If neither lands, the acknowledge leg stays assumed. It is worth restating that this is a
documentation gap, not a correctness one: a re-minted GUID on acknowledge would produce a documentation gap, not a correctness one: a re-minted GUID on acknowledge would produce a
spurious Clear plus a spurious Raise, which is the same shape the now-observed re-raise spurious Clear plus a spurious Raise, which is the same shape the now-observed re-raise
@@ -284,7 +286,12 @@ notes referenced elsewhere in this repo are **not present on this box** (`Test-P
### The test attribute is classified `MxSecurityOperate` ### The test attribute is classified `MxSecurityOperate`
UDA security classification lives in `dynamic_attribute.security_classification`, keyed by UDA security classification lives in `dynamic_attribute.security_classification`, keyed by
`gobject_id` — for the `$TestMachine` template that is `1055`: `gobject_id`. For the `$TestMachine` template that is `1055`:
```
SELECT gobject_id, tag_name, hierarchical_name FROM gobject WHERE gobject_id=1055;
1055|$TestMachine|$TestMachine
```
``` ```
attribute_name | security_classification | mx_attribute_category attribute_name | security_classification | mx_attribute_category
@@ -374,8 +381,10 @@ statements and both matter:
- The wnwrap ack path is unavailable on this rig as configured, for an identified reason - The wnwrap ack path is unavailable on this rig as configured, for an identified reason
rather than an unknown one. This is a real finding for the gateway: `AcknowledgeByName` rather than an unknown one. This is a real finding for the gateway: `AcknowledgeByName`
will behave the same way — accepted, inert — on any customer galaxy whose alarmed will behave the same way — accepted, inert — on any customer galaxy whose alarmed
attributes carry a non-free-access security classification. It is worth noting in the attributes carry a non-free-access security classification (inferred from the mechanism —
alarm client's documentation that a silent `rc=0` is not proof of acknowledgement. no `AlarmAckByName` overload can carry a credential — not confirmed by relaxing the
classification and re-testing; see "What a human would need to do"). It is worth noting in
the alarm client's documentation that a silent `rc=0` is not proof of acknowledgement.
- Whether wnwrap re-mints the record GUID on `UNACK_ALM → ACK_ALM` is still unobserved, and - Whether wnwrap re-mints the record GUID on `UNACK_ALM → ACK_ALM` is still unobserved, and
after three attempts it stays assumed. As the second attempt already noted, this remains after three attempts it stays assumed. As the second attempt already noted, this remains
a documentation gap rather than a correctness one: a re-minted GUID produces a spurious a documentation gap rather than a correctness one: a re-minted GUID produces a spurious
+2
View File
@@ -92,6 +92,8 @@ 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).
### `StreamAlarms` ### `StreamAlarms`
`StreamAlarms` is a server-streaming, **session-less** RPC that attaches to the gateway's central alarm feed. The handler delegates to `IGatewayAlarmService.StreamAsync`. The stream opens with a `provider_status` and a `snapshot_status` `AlarmFeedMessage` (the current provider mode and snapshot-completeness verdict), then one `AlarmFeedMessage` carrying an `active_alarm` per currently-active alarm (the ConditionRefresh snapshot), then a single `snapshot_complete`, then a `transition` for every subsequent raise / acknowledge / clear — interleaved with a further `provider_status` on each failover/failback and a further `snapshot_status` on each change of the truncation verdict. It is served by the always-on `GatewayAlarmMonitor`, which owns a single gateway-managed worker session and fans out to every attached client — clients no longer open a session of their own. `alarm_filter_prefix`, when set, scopes the stream to a sub-tree. `StreamAlarms` is a server-streaming, **session-less** RPC that attaches to the gateway's central alarm feed. The handler delegates to `IGatewayAlarmService.StreamAsync`. The stream opens with a `provider_status` and a `snapshot_status` `AlarmFeedMessage` (the current provider mode and snapshot-completeness verdict), then one `AlarmFeedMessage` carrying an `active_alarm` per currently-active alarm (the ConditionRefresh snapshot), then a single `snapshot_complete`, then a `transition` for every subsequent raise / acknowledge / clear — interleaved with a further `provider_status` on each failover/failback and a further `snapshot_status` on each change of the truncation verdict. It is served by the always-on `GatewayAlarmMonitor`, which owns a single gateway-managed worker session and fans out to every attached client — clients no longer open a session of their own. `alarm_filter_prefix`, when set, scopes the stream to a sub-tree.
+8
View File
@@ -227,6 +227,14 @@ ack. If the attribute has no writable ack-comment subtag configured, the RPC
returns `FailedPrecondition`. In alarm-manager mode, `AlarmAckByName` is returns `FailedPrecondition`. In alarm-manager mode, `AlarmAckByName` is
used as before. used as before.
**Acceptance is not application:** the ack is forwarded to the provider, and a
successful return means the provider accepted the call, not that the
acknowledgement was applied. On galaxies whose alarmed attributes carry a
non-free-access security classification, `AlarmAckByName` returns `rc=0` and the
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.
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
`OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto fields. The `OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto fields. The