############################
HealthInfo semantics in CSP
############################

The ``healthInfo`` attribute is a JSON string keyed by device FQDN. Values are
lists of human-readable diagnostic messages.

CSP.LMC device entry
====================

The CSP.LMC device (Subarray or Controller) owns and manages its own
``healthInfo`` entry. This entry is derived from evaluated aggregated
conditions and is:

- created only when ``healthState != OK``;
- fully recomputed at each health evaluation;
- removed when the device returns to ``HealthState.OK``.

Examples
========

Aggregated ``healthState`` is ``OK``:

::

   healthInfo = '{}'

Aggregated ``healthState`` is not ``OK``:

::

   healthInfo = '{
       "low-csp/subarray/01": [
           "The HealthState of low-cbf/subarray/01 is FAILED"
       ]
   }'

Subsystem entries
=================

Subsystem entries (for example CBF, PSS, PST) are produced by the subsystem
devices themselves. CSP forwards subscribed subsystem ``healthInfo`` entries
without interpretation.

For the Controller, ``healthInfo`` from ``csp-subarray`` components is
intentionally not subscribed/forwarded to avoid duplicating the controller
aggregation stream.

Therefore subsystem entries:

- are not required to change synchronously with ``healthState`` or ``State``;
- are updated asynchronously through subscriptions;
- may exist even when aggregated CSP ``healthState`` is ``OK``.

While subsystem ``healthInfo`` usually correlates with state changes, CSP.LMC does
not enforce strict synchronization between them.

::

   {
       "mid-csp/subarray/01": [
           "The State of mid-pst/beam/03 is FAULT"
       ],
       "mid-pst/beam/03": [
           "Hardware initialization failed"
       ]
   }

Aggregation behaviour
=====================

The CSP.LMC device maintains an aggregated view of ``healthInfo`` composed of:

- its own locally evaluated entry;
- forwarded entries received from subscribed subsystem devices.

The CSP.LMC device entry is independent from forwarded subsystem entries
and is never overwritten by them.

Subsystem ``HealthInfo`` change events are buffered by the
supervision loop (latest per subsystem source) and forwarded
to the ``HealthInfoManager`` during the next debounced
evaluation cycle.



The aggregation rules are:

- Multiple subsystem devices may contribute messages for the same FQDN.
- Messages are deduplicated while preserving insertion order.
- Keys no longer reported by any subsystem are removed from the
  aggregated view.
- The CSP.LMC device FQDN entry, if present, always appears first in the
  published JSON structure.
- The ``healthInfo`` attribute is updated only when the aggregated
  content changes.
- At most one ``HealthInfo`` publication is produced per
  debounced supervisor cycle (subject to change detection),
  even when multiple subsystem updates were received.



The aggregation logic does not filter devices by type. Any FQDN present
in subscribed subsystem ``healthInfo`` payloads may appear in the CSP
published structure.

See Also
========

- :doc:`health_aggregation_matrix`