# DDR-0016: Cleartext E27 Messages Are Not Link-Framed

Status: Approved
Date: 2025-12-22

## Related Architecture Decisions
- ADR-0003: E27 API Message Layer Architecture
- ADR-0006: E27 Transport and Link Layer Separation
- DDR-0007: E27 Link Layer Framing and CRC Handling

## Context

ADR-0006 establishes a strict separation between transport, link, presentation,
and application layers for the E27 protocol.

During live testing against a real E27 panel, it was observed that several
initial handshake messages are exchanged as cleartext JSON over TCP and are
*not* wrapped in the E27 link-layer framing (STARTCHAR, escaping, CRC).

This behavior was validated via:
- Node-RED reference implementation
- Live panel traffic inspection
- Successful end-to-end authentication and command execution

Incorrectly applying link-layer framing to these messages causes the panel
to silently ignore requests.

## Decision

The following messages MUST bypass the E27 link-layer framer/deframer:

- Discovery response reception ("ELKWC2017")
- `api_link` request
- `api_link` response (encrypted payload, but not link-framed)
- `hello` request
- `hello` response (clear JSON containing encrypted `sk` / `shm`)

Only encrypted schema-0 application messages exchanged *after* authentication
are passed through the link-layer framing defined in DDR-0007.

## Consequences

- Connection logic must branch based on protocol phase:
  - Cleartext JSON path (no framing)
  - Encrypted path (link framing + CRC)
- Link-layer helpers must never be implicitly applied to all outbound traffic
- Smoketest tooling must explicitly reflect this split behavior

## Notes

Although not clearly emphasized in vendor documentation, this behavior is
consistent and required for interoperability.
