# ADR-0120: Throttling and Concurrency Responsibilities (Home Assistant vs Library)

Status: Accepted

## Context

The Elk E27 panel has constrained resources and vendor guidance strongly
recommends operating in a “one request / one response at a time” mode to avoid
exhausting the panel’s limited response packet pool. This constraint is already
captured as an architectural requirement (ADR-0111).

Home Assistant also implements its own mechanisms to limit parallel work in an
integration (e.g., coordinated polling patterns, per-platform parallel update
limits, and DataUpdateCoordinator usage).

If throttling responsibility is not explicitly defined, the system may:
- rely on Home Assistant limits that do not fully protect the panel
- implement redundant or conflicting throttling in multiple layers
- accidentally reintroduce parallel request patterns during future refactors

The integration must remain correct and panel-safe even if Home Assistant calls
entity updates or services concurrently.

## Decision

Throttling and concurrency control are split by responsibility:

1. Library (elke27_lib) is the primary enforcement point for panel safety.
   - The library must enforce strict single in-flight request semantics per
     panel session.
   - The library must serialize requests from all callers (entities, services,
     bootstrap pipelines) through a single queue.
   - This enforcement is mandatory and independent of Home Assistant behavior.

2. Home Assistant is a secondary safety net focused on system-level behavior.
   - Home Assistant should avoid generating unnecessary concurrent calls by
     using a hub/coordinator model.
   - Where Home Assistant platform parallelism controls exist, they should be
     configured conservatively to reduce concurrent update pressure.
   - Home Assistant throttling must not be relied on to satisfy the panel’s
     single in-flight constraint.

3. Push-first state updates are preferred for E27.
   - Unsolicited panel messages and library events drive state changes.
   - Home Assistant entities should not poll the panel for routine updates.
   - If periodic refresh/health checks are used, they must be low-rate and
     routed through the same library request queue.

## Rationale

The panel constraint is absolute and must be enforced closest to the protocol
implementation, where all traffic is visible. Home Assistant’s throttling
controls can reduce load and improve overall stability, but they do not provide
a complete guarantee against concurrent requests originating from different
paths.

By treating Home Assistant throttling as secondary and the library queue as
primary, we ensure:
- panel safety under all call patterns
- predictable, testable behavior
- minimal duplication of throttling logic

## Consequences

- The library request queue becomes the single choke point for all outbound
  traffic.
- Home Assistant entity implementations remain thin and avoid I/O.
- Polling-based update models are minimized or eliminated in favor of event-
  driven updates.
- Future contributors must not introduce direct device I/O from entities or
  bypass the library queue.

## Scope / Non-Goals

- Does not define specific polling intervals for optional health checks.
- Does not define Home Assistant platform PARALLEL_UPDATES values.
- Does not change the single in-flight policy already defined in ADR-0111.

## References

- ADR-0111: E27 Request Concurrency and Backpressure (Single In-Flight Policy)
- ADR-0112: E27 Bootstrap and Configuration Download Sequencing
- Home Assistant developer guidance on fetching data and coordination patterns
