# ADR-0109: Home Assistant Integration Adapts to E27 Library Model

Status: Accepted

## Context

The existing Home Assistant Elk M1 integration is built around a
library model that exposes protocol elements directly to the
integration layer.

The E27 protocol and library are fundamentally different:
- event-driven
- stateful
- session-oriented
- inventory-driven
- reliant on unsolicited messages

Attempting to force the E27 library to emulate the M1 “element”
model would distort the E27 architecture and introduce unnecessary
complexity.

## Decision

The Home Assistant integration will adapt to the E27 library model,
not the reverse.

Specifically:
- The E27 library is the source of truth for protocol, session,
  state, and events.
- The Home Assistant integration consumes only semantic state
  snapshots and semantic events emitted by the library.
- No raw protocol messages, framing details, or JSON payloads are
  exposed to Home Assistant code.

Home Assistant maintains a single runtime “hub” object per config
entry that:
- owns the library client instance
- subscribes to library events
- maintains a canonical in-memory state snapshot
- provides command/request methods for entities

Entities are thin:
- they read state from the hub
- they call hub methods for commands
- they do not interact with the library directly

## Rationale

This approach:
- preserves the integrity of the E27 protocol architecture
- aligns with Home Assistant best practices (coordinator/hub model)
- cleanly supports unsolicited updates
- minimizes Home Assistant code complexity
- makes later reconciliation into the existing `elkm1` integration
  largely mechanical

## Consequences

- M1-style “elements” abstractions are not used for E27
- The E27 library must expose a clear, stable public API
- Home Assistant must implement a hub/state pattern
- Debugging and testing boundaries are cleaner and more deterministic

## Scope / Non-Goals

- Does not mandate specific class names or file layout
- Does not alter E27 protocol semantics
- Does not preclude future refactoring to share code with M1

## References

- ADR-0001: E27 as a First-Class Protocol Backend
- ADR-0006: Semantic Translation Lives Inside Each Backend
- ADR-0012: Stable Inventory-Driven E27 API Surface
- ADR-0108: Temporary Separate Home Assistant Integration Domain for E27 Development
