Entity Mapping Stabilization Checklist (Design/Coding)

Goal: Ensure entity creation and behavior are stable across reconnects, refreshes,
and library refactors.

A. Identity and Unique ID Rules
- Define device identity: MAC primary, serial secondary.
- Implement unique_id scheme: <mac>:<domain>:<numeric_id>.
- Verify unique_id does not depend on:
  - host/IP
  - session_id
  - discovery order
  - paging order

B. Inventory Eligibility Rules
- Create entities only for IDs returned by configured inventory enumeration.
- Apply domain-specific filters before entity creation:
  - Zones: skip if definition == "UNDEFINED" (ADR-0119).
- Decide handling of Disabled objects:
  - create but default-disabled in entity registry, OR
  - omit entirely (document choice).

C. Domain Mapping Tables
- Create initial mapping table for Zones:
  - definition -> platform (binary_sensor vs sensor)
  - definition -> device_class (door/window/motion/smoke/etc.)
  - default enabled/disabled
- Create mapping table for Areas:
  - area state -> alarm_control_panel state mapping
  - supported features flags
- Define outputs vs lights policy:
  - avoid mapping the same endpoint to both a switch and a light
- Define thermostat mapping policy for climate

D. Naming Policy
- Prefer panel-provided names.
- Provide deterministic fallback name if missing.
- Ensure renames update name only, not unique_id.

E. Snapshot Contract (coordinator.data)
- Define a stable HA-facing snapshot structure:
  - panel_info (stable fields)
  - areas_by_id, zones_by_id, outputs_by_id, etc.
- Ensure entities read only from coordinator.data, not from hub/library objects.

F. Configuration Change Behavior (CSM / refresh)
- On new configured object: create entity.
- On removed object: remove entity.
- On zone becomes UNDEFINED: remove entity.
- On name/attrib change: update entity properties without changing unique_id.

G. Verification / Regression Control
- Capture a representative inventory fixture (golden data).
- Produce expected entity list:
  (unique_id, platform, device_class, enabled_default).
- Re-run after changes; any churn requires explicit review and decision.

Done when:
- Entities remain stable across restart/reconnect.
- CSM refresh does not create duplicates or break unique_ids.
- No “UNDEFINED” zones appear as entities.
