# ADR-0114: CSM-Based Configuration Invalidation and Selective Bootstrap

Status: Accepted

## Context

The E27 panel exposes CSM (Configuration State Map) data that reflects changes
to configuration tables and system state. Configuration data (such as object
definitions, names, membership, and capabilities) changes infrequently, while
runtime state (such as armed status, zone open/closed, troubles) changes
frequently.

A full configuration download on every connection or reconnect is:
- expensive in request count
- slow to complete
- unnecessary when configuration has not changed

At the same time, correctness requires that Home Assistant never operate on
stale configuration data.

Given the panel’s limited packet pool, the single in-flight request policy
(ADR-0111), and the phased bootstrap model (ADR-0112), CSM provides a mechanism
to minimize unnecessary configuration downloads while preserving correctness.

## Decision

CSM is used as a configuration invalidation signal to drive selective bootstrap
and refresh behavior.

### 1. Configuration vs Runtime State

The integration distinguishes between two classes of data:

- Configuration data:
  - configured object identifiers (areas, zones, outputs, etc.)
  - names, attributes, and membership
  - capability and table metadata

- Runtime state:
  - armed/disarmed/alarm states
  - zone open/closed/trouble/bypass status
  - output/light on/off state

CSM governs configuration data only. Runtime state is always refreshed or
validated independently.

### 2. CSM Retrieval Timing

CSM is retrieved early during connection or reconnection, after session
establishment and minimal capability discovery.

CSM retrieval occurs:
- during initial bootstrap
- during reconnect
- during explicit refresh or reload operations

### 3. Cached State

The integration persists the following across restarts:
- last-seen CSM values per relevant table or domain
- cached configuration inventory metadata (configured IDs and attributes)

The integration does not persist runtime state as authoritative truth.

### 4. Selective Bootstrap Logic

On connection or reconnect:

1. Retrieve current CSM.
2. Compare current CSM against cached CSM values.
3. For each domain:
   - If CSM unchanged, reuse cached configuration inventory.
   - If CSM changed or unknown, re-run inventory enumeration and attribute
     retrieval for that domain.
4. Always perform a minimal runtime state refresh (or validate via unsolicited
   updates) before declaring readiness.

If CSM is unavailable or retrieval fails, the integration falls back to a full
configuration bootstrap.

### 5. Safety and Fallback Rules

- On first run (no cached CSM), full configuration bootstrap is required.
- Broad or system-level CSM changes invalidate all cached configuration.
- Capability or table definition changes force a full re-evaluation regardless
  of CSM values.
- Partial bootstrap results must not be exposed to Home Assistant entities.

Correctness always takes precedence over optimization.

### 6. Interaction with Unsolicited Messages

Unsolicited messages may update runtime state continuously, but they do not
replace:
- initial runtime state validation
- configuration correctness checks

CSM-driven selective bootstrap complements unsolicited updates; it does not
supersede them.

## Rationale

Using CSM as an invalidation mechanism:
- dramatically reduces unnecessary configuration traffic
- shortens reconnect and startup times
- preserves correctness through explicit fallback paths
- aligns with inventory-driven API design
- respects the panel’s resource constraints

Treating CSM as advisory rather than authoritative ensures robustness in the
presence of partial information or protocol anomalies.

## Consequences

- The E27 library must expose CSM data in a structured, domain-aware form.
- The bootstrap pipeline must be able to plan and execute partial refreshes.
- Cached configuration data becomes a first-class input to bootstrap planning.
- Testing must cover both full and selective bootstrap paths.

## Scope / Non-Goals

- Does not define the exact structure or encoding of CSM data.
- Does not mandate specific persistence storage mechanisms.
- Does not eliminate the need for full refresh in all cases.

## References

- ADR-0012: Stable Inventory-Driven E27 API Surface
- ADR-0109: Home Assistant Integration Adapts to E27 Library Model
- ADR-0111: E27 Request Concurrency and Backpressure
- ADR-0112: E27 Bootstrap and Configuration Download Sequencing
- ADR-0113: E27 Reconnect and Rediscovery Policy
- E27 API Comms Protocol
