HealthInfoManager
=================

Role in the Architecture
------------------------

The ``HealthInfoManager`` aggregates and publishes the ``healthInfo``
attribute for a CSP.LMC device.

It is responsible for:

- Merging local diagnostics with forwarded subsystem diagnostics
- Deduplicating messages per FQDN while preserving order
- Detecting content changes to avoid redundant emissions
- Publishing the aggregated payload through a callback

The manager does not decide *when* health evaluation occurs. It is
driven by the ``CspHealthSupervisor``, which controls evaluation timing
and provides the local diagnostics and forwarded subsystem updates.

Responsibilities
----------------

The manager:

- Maintains the aggregated ``healthInfo`` snapshot
- Stores forwarded subsystem payloads per subsystem source (FQDN)
- Merges subsystem contributions into a single aggregated payload
- Ensures deterministic ordering of the published structure
- Applies change detection before emitting
- Publishes through a callback when content changes

Aggregation Model
-----------------

The aggregated payload is composed of:

- Local diagnostics produced by the owning device (its own FQDN key)
- Forwarded diagnostics from subsystem devices (other FQDN keys)

The owning device FQDN entry is guaranteed to appear first in the
published dictionary (when present), followed by other entries in a
stable ordering.

Subsystem contributions are treated as authoritative per source.
When multiple subsystem sources report messages for the same FQDN:

- Messages are deduplicated
- Insertion order is preserved
- Keys no longer reported by any subsystem are removed

Emission Model
--------------

The ``HealthInfoManager`` emits updates immediately when the aggregated
content changes.

Each call to ``update_health_info(...)`` recomputes the aggregated
structure from:

- The latest local diagnostics
- The latest forwarded subsystem payloads

If the resulting structure differs from the previously published
snapshot, the manager invokes the publication callback.

If the content is identical, no event is emitted.

This guarantees:

- No redundant ``healthInfo`` events
- Deterministic and stable output
- One emission per effective content change

In practice, subsystem ``state``, ``HealthState`` and ``healthInfo``
updates may arrive close in time. These events can trigger consecutive
evaluation cycles and potentially produce different intermediate
diagnostic outputs.

Event bursts are mitigated at the supervision level through debounce
and max-latency control. The manager itself remains purely
content-driven and does not implement any timing or scheduling logic.

All timing control is delegated to the supervisor.


ASCII Overview
--------------

.. code-block:: text

   Subsystem healthInfo events
                |
                v
      +-----------------------+
      | CspHealthSupervisor   |
      | - buffers latest per  |
      |   subsystem source    |
      +-----------+-----------+
                  |
                  | update_health_info(...)
                  v
      +-----------------------+
      | HealthInfoManager     |
      | - merge local+forward |
      | - deduplicate         |
      | - change detection    |
      +-----------+-----------+
                  |
                  v
          publish callback
          ("healthInfo")

Key Behaviours
--------------

- Change detection ensures identical payloads do not produce events.
- Subsystem contributions are authoritative per source and merged across
  all sources.
- Local device diagnostics are independent from forwarded subsystem data.
- The manager is free of timing and scheduling responsibilities.

Public API Overview
-------------------

The following methods are commonly used by the supervisor:

- ``update_health_info(...)``:
  Apply local and/or subsystem updates and update the aggregated snapshot.
  Emits immediately if content changed.

- ``snapshot()``:
  Return a thread-safe copy of the current aggregated ``healthInfo``.

Relationship to the Supervisor
------------------------------

The ``CspHealthSupervisor``:

- Controls evaluation timing (debounce and max-latency)
- Buffers forwarded subsystem ``healthInfo`` updates
- Provides local diagnostics derived from health evaluation

The ``HealthInfoManager``:

- Aggregates local and forwarded diagnostics
- Performs change detection
- Publishes the final ``healthInfo`` attribute

For the supervisor role and timing coordination, refer to:

:doc:`/api/observation/supervisor/health_supervisor`