# ADR-0112: E27 Bootstrap and Configuration Download Sequencing

Status: Accepted

## Context

After an E27 connection is made, the client must retrieve sufficient
information from the panel to:
- identify the panel
- determine supported capabilities
- discover configured objects (areas, zones, outputs, etc.)
- safely create Home Assistant entities

However, E27 operation is preceded by:
- discovery (to locate candidate panels and select one by identity)
- linking (to establish long-lived trust keys) when link keys are not already
  persisted

The E27 API is inventory-driven and paged for many domains. Combined with the
panel’s limited packet pool and the single in-flight request policy
(ADR-0111), configuration download must be carefully sequenced.

Uncoordinated or parallel configuration requests risk:
- exhausting the panel’s packet pool
- receiving incomplete or inconsistent inventory
- creating partial or incorrect entity models in Home Assistant

## Decision

E27 onboarding, session establishment, bootstrap, and configuration download
follow a strict, deterministic, sequential pipeline.

The overall process is divided into ordered phases. Each phase must complete
successfully before the next phase begins.

### Phase -2: Discovery (Pre-Connection)
- Discover panels on the local network using the E27 discovery protocol.
- Present discovered candidates to the user by panel name, but bind selection
  definitively by MAC address.
- Discovery is repeated as needed to reacquire the panel if its IP address
  changes.

### Phase -1: Linking (Pre-Session Trust Establishment)
- If persisted link keys (link encryption and link HMAC keys) are not present
  for the selected panel identity, perform the E27 linking procedure.
- Linking establishes long-lived trust keys and must complete before any
  session establishment can proceed.
- If link keys are present, linking is skipped.

### Phase 0: Session Establishment
- Establish TCP connection.
- Complete link/session handshake.
- Achieve baseline session state (session keys active).
- No framed or session-encrypted API traffic is sent before this phase
  completes.

### Phase 1: Panel Identity and Capability Discovery
- Retrieve panel identity and version information.
- Retrieve table/capability information required to determine:
  - supported domains
  - maximum counts
  - feature availability
- This phase establishes whether the integration can proceed.

### Phase 2: Inventory Enumeration (Configured Objects)
- Enumerate configured object identifiers for each supported domain
  (e.g., areas, zones, outputs, lights, thermostats).
- Paged APIs are drained sequentially until complete.
- Only configured IDs are collected; no per-object attributes are fetched yet.

### Phase 3: Attribute and State Population
- For each domain, fetch attributes and current state for configured IDs.
- Requests are issued sequentially and grouped by domain where practical.
- State snapshots are populated incrementally but are not exposed to Home
  Assistant entities until the phase completes.

### Phase 4: Bootstrap Completion Signal
- Emit a single semantic “bootstrap complete” or “ready” signal.
- Only after this signal may Home Assistant create entities and expose services.

## Additional Rules

- All phases must respect the single in-flight request policy.
- Failures in any phase abort the process and surface a clear error to the
  integration.
- Partial bootstrap results must not be exposed to Home Assistant entities.
- Subsequent configuration refreshes (e.g., via CSM or explicit reload) must
  reuse the same phased sequencing model.

## Rationale

A phased model:
- ensures a consistent and complete view of panel configuration
- avoids partial or transient entity creation
- aligns with inventory-driven API semantics
- respects panel resource constraints
- simplifies reasoning, testing, and error handling

By making sequencing architectural, future contributors are prevented from
introducing parallel fetch patterns that destabilize the panel.

## Consequences

- The E27 library must implement onboarding/bootstrap as an explicit pipeline.
- Home Assistant must gate entity setup on the bootstrap completion signal.
- Configuration refresh logic must follow the same sequencing rules as initial
  bootstrap.
- Discovery and IP-change reacquisition are part of the supported lifecycle,
  not exceptional behavior.

## Scope / Non-Goals

- Does not define exact API call lists for each phase.
- Does not define retry/backoff strategies.
- Does not define user-facing progress indicators.

## References

- ADR-0003: Linking and Session Are Distinct Lifetimes
- ADR-0004: Link Keys Are Persisted Externally
- ADR-0008: Discovery UX and Panel Identity
- ADR-0012: Stable Inventory-Driven E27 API Surface
- ADR-0109: Home Assistant Integration Adapts to E27 Library Model
- ADR-0111: E27 Request Concurrency and Backpressure (Single In-Flight Policy)
- E27 API Comms Protocol
