# ADR-0123: Library-Owned CSM Diffing and Selective Configuration Refresh

Status: Accepted

## Context

The E27 API provides Configuration State Map (CSM) values intended to allow
clients to determine whether cached configuration data matches the panel’s
current configuration. These CSM values are exposed at two levels:

- Domain-level CSMs (returned during authentication)
- Table-level `table_csm` values (returned by per-domain `get_table_info` calls)

Home Assistant uses a DataUpdateCoordinator to orchestrate updates and fan out
state to entities, but it should not be required to interpret raw protocol
payloads, API handler naming, or paging semantics.

If Home Assistant is required to compute CSM diffs directly from raw payloads,
it becomes tightly coupled to protocol details and more fragile in the face of
API evolution.

## Decision

The E27 library (elke27_lib) is responsible for computing CSM diffs and declaring
which configuration domains require refresh.

1. The library captures and normalizes all CSM signals:
   - domain-level CSMs
   - table-level `table_csm` values

2. The library maintains the last-seen CSM snapshot and computes diffs when new
   CSM data is observed.

3. The library emits semantic events that describe configuration changes at the
   domain level (and optionally table level), such as:
   - “zone configuration invalidated”
   - “output configuration unchanged”
   - “area configuration refreshed”

4. Home Assistant does not parse raw CSM fields or compute CSM diffs.
   - HA reacts only to library-emitted semantic events or to an updated CSM
     snapshot provided by the library.

5. The library provides explicit refresh primitives per domain (e.g., refresh
   zone configuration), which encapsulate:
   - correct API call sequences
   - paging rules
   - single in-flight request enforcement

6. The Home Assistant DataUpdateCoordinator:
   - subscribes to library events
   - triggers domain refresh operations via the hub when notified
   - republishes updated snapshots to entities

## Rationale

Placing CSM diffing and refresh logic in the library:
- keeps Home Assistant thin and idiomatic
- prevents duplication of protocol knowledge across layers
- reduces the risk of incorrect or partial refresh decisions
- allows protocol evolution without forcing HA changes

This aligns with the broader architectural principle that the library owns all
protocol semantics and correctness constraints, while Home Assistant owns user
experience and orchestration.

## Consequences

- The library must expose a stable CSM snapshot model and diffing logic.
- The library event model expands to include CSM-related semantic events.
- Home Assistant coordinator logic becomes simpler and more robust.
- Selective refresh behavior is testable at the library level.

## Scope / Non-Goals

- Does not mandate which specific CSM signal (domain vs table) is primary; the
  library may choose the most efficient source.
- Does not define polling frequency or triggers for CSM refresh.
- Does not require Home Assistant to persist CSM snapshots (though it may).

## References

- ADR-0114: CSM-Based Configuration Invalidation and Selective Bootstrap
- ADR-0120: Throttling and Concurrency Responsibilities (HA vs Library)
- ADR-0121: Hub + DataUpdateCoordinator Separation
- E27 API Dealer Documentation (CSM and table_csm semantics)
