# DDR-0039: PanelSnapshot Includes Definition Metadata for HA Entity Mapping

Status: Accepted  
Date: 2026-01-13  
Related ADRs: ADR-0121, ADR-0122, ADR-0119

## Context

Home Assistant entities must read exclusively from `coordinator.data` and must
not consult the library client’s internal mutable state. However, several HA
platforms (notably zones) require definition metadata (name, type/kind, flags)
for filtering (e.g., UNDEFINED), device_class/icon selection, and display.

Earlier snapshot models exposed status but did not expose sufficient definition
metadata, causing HA code to fall back to `hub.client.state` and risking drift
between coordinator data and internal client state.

## Decision

Extend the library’s HA-facing snapshot surface to include stable, immutable
definition metadata required for entity mapping and display:

- Add typed dataclasses (minimum set required by HA):
  - `ZoneDefinition`
  - `OutputDefinition` (and others as needed)
- Extend `PanelSnapshot` to include:
  - `zone_definitions: Mapping[int, ZoneDefinition]`
  - `output_definitions: Mapping[int, OutputDefinition]`

Definition maps are keyed by the panel’s native numeric identifiers:
- zones are keyed by `zone_id` (1-based) to match HA entity numbering.

Snapshot maps are exposed as immutable views (e.g., MappingProxyType) and are
rebuilt as fresh dataclasses on each snapshot update.

## Rationale

- Enables the ADR-0121 requirement: entities read only from coordinator.data.
- Prevents subtle inconsistencies from reading mutable client state directly.
- Centralizes entity mapping inputs in one stable snapshot tree, improving test
  determinism and reducing coupling.
- Aligns with ADR-0122 stability goals by making mapping inputs explicit and
  versionable.

## Consequences

- The client snapshot build pipeline must derive definition maps from library
  state and include them in initial and updated snapshots.
- Snapshot update triggers must include definition-changing events (e.g., zone
  attrib/def/flag updates) so HA sees metadata changes promptly.
- HA platforms must be updated to use `snapshot.zone_definitions[...]` rather
  than any hub/client internal state.
- Library tests must validate:
  - definitions are present in snapshots
  - definitions update after definition/attrib handlers run
  - public API exports include the new types
