docs(opcua,#386): document HEALED as internal-only + ShelvingState precision (bburda review)

Three documentation gaps surfaced by bburda's review on PR #387:

(1) **HEALED design-doc fiction.** ``alarm_state_machine.hpp`` advertised
``SovdAlarmStatus::Healed`` as a first-class lifecycle state and the
design table listed it as rule 5a outcome, but ``ReportHealed`` is a
no-op in ``OpcuaPlugin::on_event_alarm`` so the state never surfaces in
``/faults`` (status stays ``CONFIRMED`` until ``Cleared`` fires).
Header docstring on ``SovdAlarmStatus`` and ``AlarmAction`` now spells
out which values are externally visible vs internal-only, and the
design doc has a new ``.. note::`` block explaining why ``EVENT_PASSED``
on every latch would defeat Part 9's mandatory ack/confirm contract via
fault_manager's debounce engine. Future ``STATUS_LATCHED`` extension on
``ros2_medkit_msgs/msg/Fault`` is called out as the path to make this
visible externally; until then, a known UX gap is documented.

(2) **ShelvingState rule 3 precision.** Doc said
``ShelvingState != Unshelved`` -> Suppressed. Code (poller :382-389)
only treats the specific NodeIds ``i=2930`` (TimedShelved) and
``i=2932`` (OneShotShelved) as suppressing - a null/unset/unknown
``Id`` is interpreted as Unshelved (the deliberate code path with a
"some servers leave the optional field uninitialized" comment). Doc
table now lists the explicit NodeId set + the null/unset behaviour.

(3) **Plugin docs not in published aggregator.** The 162 lines of
``design/index.rst`` and the CHANGELOG entry added in this PR did not
render on https://selfpatch.github.io/ros2_medkit/ because:

- ``docs/changelog.rst`` aggregator did not ``.. include::`` the
  opcua-plugin CHANGELOG.
- ``docs/design/index.rst`` toctree was missing
  ``ros2_medkit_opcua/index``.

Fix:

- Append the opcua CHANGELOG include to ``docs/changelog.rst`` (matches
  the precedent of every other in-tree package).
- Add ``docs/design/ros2_medkit_opcua/index.rst`` as a thin stub that
  ``.. include::``-s the in-package design doc (cleaner than the existing
  duplicated-file pattern under
  ``docs/design/ros2_medkit_graph_provider/index.rst`` - duplicated files
  drift; an include directive cannot).
- Add ``ros2_medkit_opcua/index`` to the design toctree (alphabetically
  between ``ros2_medkit_msgs`` and ``ros2_medkit_param_beacon``).

No code change; the state machine still has 4 internal lifecycle states
and the bridge still keeps HEALED entries at ``status=CONFIRMED``. Local
verify: 27/27 test_alarm_state_machine.

Author: mfaferek93

docs/changelog.rst

@@ -31,3 +31,5 @@ This page aggregates changelogs from all ros2_medkit packages.
 .. include:: ../src/ros2_medkit_discovery_plugins/ros2_medkit_topic_beacon/CHANGELOG.rst
 
 .. include:: ../src/ros2_medkit_plugins/ros2_medkit_graph_provider/CHANGELOG.rst
+
+.. include:: ../src/ros2_medkit_plugins/ros2_medkit_opcua/CHANGELOG.rst

docs/design/index.rst

@@ -16,6 +16,7 @@ This section contains design documentation for the ros2_medkit project packages.
    ros2_medkit_integration_tests/index
    ros2_medkit_linux_introspection/index
    ros2_medkit_msgs/index
+   ros2_medkit_opcua/index
    ros2_medkit_param_beacon/index
    ros2_medkit_serialization/index
    ros2_medkit_sovd_service_interface/index

docs/design/ros2_medkit_opcua/index.rst

@@ -0,0 +1,6 @@
+.. Aggregator stub - actual content lives in
+.. ``src/ros2_medkit_plugins/ros2_medkit_opcua/design/index.rst`` and is
+.. pulled in here so the published docs match what package maintainers
+.. edit alongside the code (bburda review on PR #387).
+
+.. include:: ../../../src/ros2_medkit_plugins/ros2_medkit_opcua/design/index.rst

src/ros2_medkit_plugins/ros2_medkit_opcua/design/index.rst

@@ -236,12 +236,17 @@ Decision order, first match wins:
 +-----+--------------------------------------+---------------------------------------+
 | 2   | ``EnabledState == false``            | clear if was active, else no-op       |
 +-----+--------------------------------------+---------------------------------------+
-| 3   | ``ShelvingState != Unshelved``       | clear if was active, else no-op       |
+| 3   | ``ShelvingState/CurrentState/Id``    | clear if was active, else no-op.      |
+|     | in {``TimedShelved`` (i=2930),       | A null/unset/unknown ``Id`` is        |
+|     | ``OneShotShelved`` (i=2932)}         | treated as ``Unshelved`` (some        |
+|     |                                      | servers leave the optional field      |
+|     |                                      | uninitialized).                       |
 +-----+--------------------------------------+---------------------------------------+
 | 4   | ``ActiveState == true``              | ``CONFIRMED`` (idempotent)            |
 +-----+--------------------------------------+---------------------------------------+
-| 5a  | ``ActiveState == false`` and         | ``HEALED`` (latched, awaiting ack)    |
-|     | not (``Acked`` and ``Confirmed``)    |                                       |
+| 5a  | ``ActiveState == false`` and         | internal ``HEALED`` state; ``/faults``|
+|     | not (``Acked`` and ``Confirmed``)    | still shows ``CONFIRMED`` (see note   |
+|     |                                      | below)                                |
 +-----+--------------------------------------+---------------------------------------+
 | 5b  | ``ActiveState == false``,            | ``CLEARED``                           |
 |     | ``Acked == true``,                   |                                       |
@@ -254,6 +259,26 @@ lifecycle is driven entirely by Active / Acked / Confirmed. The SOVD
 ``PREFAILED`` state has no native equivalent and is reserved for the
 threshold-polling pre-trigger path.
 
+.. note::
+
+   **HEALED is internal-only.** Rule 5a transitions the bridge's internal
+   ``SovdAlarmStatus`` to ``Healed`` and emits the ``ReportHealed`` action,
+   but ``OpcuaPlugin::on_event_alarm`` deliberately treats that action as a
+   no-op. The reason: ``ros2_medkit_msgs/srv/ReportFault`` has only
+   ``EVENT_FAILED`` / ``EVENT_PASSED`` verbs, and routing ``EVENT_PASSED``
+   on every latch would feed the fault_manager debounce engine - which has
+   its own statistical ``HEALED`` semantics (``healing_threshold`` cycles
+   of PASSED events) and may auto-clear the fault, defeating Part 9's
+   mandatory ack/confirm contract. Until ``ros2_medkit_msgs/msg/Fault``
+   gains a ``STATUS_LATCHED`` (or equivalent) value, ``/faults`` keeps
+   ``status=CONFIRMED`` for a latched alarm; the next ``Cleared`` (rule 5b)
+   removes the entry.
+
+   This is a known UX gap: an operator looking at ``/faults`` cannot
+   distinguish "alarm physically active" from "alarm physically cleared,
+   awaiting confirm". The ack/confirm SOVD operations work end-to-end; the
+   visibility limitation is tracked as a follow-up.
+
 Severity mapping
 ----------------
 

src/ros2_medkit_plugins/ros2_medkit_opcua/include/ros2_medkit_opcua/alarm_state_machine.hpp

@@ -19,7 +19,23 @@
 
 namespace ros2_medkit_gateway {
 
-/// SOVD fault statuses surfaced by the OPC-UA AlarmCondition bridge.
+/// Internal lifecycle states the AlarmCondition bridge tracks per condition.
+///
+/// **Public-facing vs internal**: not every value here surfaces in the SOVD
+/// ``/faults`` payload (bburda review on PR #387):
+/// - ``Suppressed``: condition exists but is administratively masked
+///   (``EnabledState=false`` or shelved); no entry in ``/faults``.
+/// - ``Confirmed``: visible as ``status=CONFIRMED`` in ``/faults``.
+/// - ``Cleared``: removed from ``/faults`` via ``clear_fault``.
+/// - ``Healed``: **internal-only**. Means "ActiveState=false but operator
+///   workflow incomplete (ack and/or confirm pending)". This is NOT exposed
+///   as a separate ``/faults`` status - the bridge keeps the entry at
+///   ``CONFIRMED`` until ``Cleared`` fires (see ``ReportHealed`` below).
+///   ``ros2_medkit_msgs/srv/ReportFault`` has no HEALED verb today; routing
+///   ``EVENT_PASSED`` here would let ``fault_manager``'s debounce engine
+///   auto-clear the fault, defeating Part 9's mandatory ack/confirm
+///   contract. A future ``STATUS_LATCHED`` extension to the message would
+///   make this state externally visible; until then it stays internal.
 ///
 /// PREFAILED is reserved for the threshold-polling pre-trigger path and is
 /// never produced by ``AlarmStateMachine::compute`` from native event input -
@@ -28,11 +44,13 @@ enum class SovdAlarmStatus { Suppressed, Confirmed, Healed, Cleared };
 
 /// Action the poller should take after running the state machine on one event.
 ///
-/// ``ReportConfirmed`` / ``ReportHealed`` correspond to ``send_report_fault``
-/// (FAILED event_type for Confirmed; PASSED-but-still-tracked for Healed).
-/// ``ClearFault`` issues ``clear_fault`` against fault_manager. ``NoOp`` means
-/// the event was redundant (same as last_known_status) and we suppress
-/// downstream noise.
+/// ``ReportConfirmed`` triggers ``send_report_fault`` (FAILED event_type).
+/// ``ClearFault`` issues ``clear_fault`` against fault_manager.
+/// ``ReportHealed`` is currently a no-op in ``OpcuaPlugin::on_event_alarm`` -
+/// see ``SovdAlarmStatus::Healed`` above for the rationale and the future
+/// ``STATUS_LATCHED`` extension that would make this surface externally.
+/// ``NoOp`` means the event was redundant (same as last_known_status) and we
+/// suppress downstream noise.
 enum class AlarmAction { NoOp, ReportConfirmed, ReportHealed, ClearFault };
 
 /// Inputs from a single AlarmConditionType event payload.