# ADR-0119: Zone Definition Filtering and Entity Creation Rules

Status: Draft

## Context

The E27 panel reports zone configuration and attributes, including a
`definition` field that describes the semantic purpose of the zone.

Some zones may be present in the configuration tables but have a definition of
`UNDEFINED`. These zones do not represent meaningful physical sensors or logical
inputs and should not be exposed as entities in Home Assistant.

Other zones report concrete definitions (e.g., burglary perimeter, interior
motion, fire, etc.) and include flags that describe capabilities such as
bypassability, chime support, and reporting behavior.

Exposing undefined or placeholder zones in Home Assistant would:
- clutter the entity registry
- confuse users
- provide no actionable value

## Decision

Zone entity creation in Home Assistant is gated by the zone definition.

1. Zones with `definition == "UNDEFINED"` do not produce any Home Assistant
   entities.
   - No binary_sensor, sensor, or diagnostic entity is created.
   - These zones are ignored entirely at the HA entity layer.

2. Zones with a concrete, non-UNDEFINED definition are eligible for entity
   creation.

3. The zone `definition` determines the primary Home Assistant platform and
   semantic type (e.g., burglary contact → binary_sensor).

4. Zone flags are treated as capability hints and attributes, not as entity
   existence criteria.

5. Changes in zone definition detected via CSM or configuration refresh may
   result in entity creation or removal to reflect the new definition.

## Rationale

Filtering by definition:
- aligns HA entities with meaningful physical or logical sensors
- avoids presenting unused or placeholder zones
- keeps the HA entity model clean and predictable

Separating definition (what the zone is) from flags (how it behaves) provides a
clear mapping model that can evolve as additional definitions are encountered.

## Consequences

- The HA integration must apply definition filtering before entity creation.
- Entity registries may change dynamically if a zone transitions between
  UNDEFINED and a concrete definition.
- Users will not see or interact with UNDEFINED zones in Home Assistant.

## Scope / Non-Goals

- Does not define the full mapping table of zone definitions to HA device
  classes (to be expanded later).
- Does not require the library to suppress UNDEFINED zones; filtering occurs
  at the HA layer.
- Does not interpret or enforce zone flags beyond exposing them as attributes.

## References

- E27 zone attribute reports (definition and flags)
- ADR-0012: Stable Inventory-Driven E27 API Surface
- ADR-0114: CSM-Based Configuration Invalidation and Selective Bootstrap
- Home Assistant entity creation best practices
