# DDR-0040: Zone Domain Refresh Re-fetches Definition Metadata

Status: Accepted  
Date: 2026-01-13  
Related ADRs: ADR-0123, ADR-0114, ADR-0112, ADR-0111, DDR-0037

## Context

Selective configuration refresh is driven by CSM invalidation (ADR-0123). When HA
(or the library) decides “zone configuration changed,” it calls the library’s
zone refresh primitive (`refresh_domain_config("zone")`).

HA entity mapping depends on zone definition metadata (DDR-0039). If a zone
refresh does not re-fetch definitions/attribs, an explicit refresh can update
inventory membership but leave definition metadata stale, undermining the core
benefit of CSM-driven selective refresh.

## Decision

Define the minimum semantics of zone configuration refresh as:

`refresh_domain_config("zone")` MUST re-fetch zone definition metadata required
for HA entity mapping, not just membership lists.

Minimum required call sequence for zone refresh:
1. `zone.get_table_info` (table sizing/paging + table_csm visibility)
2. `zone.get_configured` (configured inventory enumeration)
3. `zone.get_attribs` (definition metadata needed by HA)

Optional additional calls may be included if required for completeness:
- `zone.get_defs`
- `zone.get_def_flags`

All refresh calls must route through the library single in-flight queue and
respect DDR-0037 completion gating and timeouts.

## Rationale

- Ensures that a “zone config refresh” actually refreshes the data HA uses to
  create/filter/map entities (names, kinds, UNDEFINED rules).
- Prevents HA from requiring ad-hoc additional calls or reading internal state.
- Matches the intent of CSM invalidation: configuration drift is corrected by a
  single high-level refresh primitive.

## Consequences

- `_refresh_zone_config()` (or equivalent) must enqueue `get_attribs` as part of
  the zone refresh pipeline.
- Snapshot update triggers must fire after attribs/defs/flags updates so HA sees
  the refreshed definitions without polling.
- Tests should cover: invoking zone refresh updates `PanelSnapshot.zone_definitions`.
