# ADR-0113: E27 Reconnect and Rediscovery Policy (MAC-Preserving Fast Path)

Status: Accepted

## Context

E27 communication relies on a persistent TCP connection. Network interruptions,
panel restarts, IP address changes, or transient LAN issues may cause the TCP
connection to drop at any time.

Because E27 panel identity is defined by MAC address (not IP), reconnect logic
must restore connectivity to the same physical panel without risking accidental
connection to a different device.

Reconnect behavior must also respect:
- long-lived link keys vs per-session keys
- the single in-flight request policy
- deterministic bootstrap/config sequencing

This behavior must be automatic and not require user intervention for normal
network changes.

## Decision

When the TCP connection to an E27 panel is lost, the client follows a strict,
identity-preserving reconnect sequence.

### Step 1: Enter Disconnected State
- Immediately mark the session as disconnected.
- Cancel or fail the in-flight request.
- Pause the outbound request queue.
- Emit a semantic “connection_lost” or equivalent event so higher layers
  mark entities unavailable.

### Step 2: Fast Reconnect Using Last Known Host Hint
- Attempt to reconnect to the last known host/port hint.
- This attempt should be quick and bounded (no long blocking retries).
- If successful, proceed directly to session establishment.

### Step 3: Rediscovery by Identity (Fallback)
- If the fast reconnect fails, initiate E27 discovery.
- Match discovered panels strictly by MAC address.
- If a matching panel is found:
  - update the in-memory host/port hint
  - optionally persist the new hint via a reconfigure flow
- If no matching panel is found, retry discovery with backoff.

Hard rule:
- The client must never connect to a panel whose MAC does not match the stored
  identity.

### Step 4: Session Re-Establishment (No Re-Link)
- Establish a new TCP connection.
- Reuse persisted link keys to establish a new session.
- Do not perform linking unless the panel explicitly rejects the stored link
  keys.

### Step 5: Bootstrap and State Revalidation
- Restart the bootstrap/configuration sequencing pipeline.
- At minimum, ensure:
  - session is valid
  - baseline state is current
- Full inventory/config refresh may be optimized or skipped only if proven
  unchanged (e.g., via versioning), but correctness is prioritized over speed.

### Step 6: Resume Operation
- Resume the request queue.
- Emit a semantic “ready” or “reconnected” signal.
- Entities transition back to available.

## Error Escalation Rules

- Re-linking is performed only if:
  - the panel indicates link keys are invalid or missing, or
  - repeated protocol/crypto failures strongly suggest incorrect keys.
- In such cases, emit a clear “link_required” or “invalid_link_keys” condition
  so Home Assistant can prompt the user via a repair or reauth flow.

## Rationale

This policy:
- preserves strict device identity
- minimizes downtime for common IP changes
- avoids unnecessary re-linking
- aligns with the panel’s security and session model
- provides predictable, testable reconnect behavior

Separating fast reconnect from rediscovery ensures optimal performance on stable
networks while remaining robust to topology changes.

## Consequences

- The E27 library must own reconnect and rediscovery logic.
- Home Assistant must treat reconnect as a normal lifecycle event.
- Host/port is treated as a mutable hint, never as identity.
- Users are not prompted unless trust must be re-established.

## Scope / Non-Goals

- Does not define exact retry intervals or backoff timing.
- Does not define UI presentation details.
- Does not guarantee zero state refresh on reconnect.

## References

- ADR-0003: Linking and Session Are Distinct Lifetimes
- ADR-0008: Discovery UX and Panel Identity
- ADR-0102: E27 Link and Session Key Lifetimes
- ADR-0111: E27 Request Concurrency and Backpressure
- ADR-0112: E27 Bootstrap and Configuration Download Sequencing
- E27 API Comms Protocol
