# ADR-0100: E27 Framing and Presentation Layer Semantics

Status: Accepted

## Context

E27 communication occurs over a framed binary transport that encapsulates
JSON payloads and applies encryption, padding, and integrity mechanisms.

Incorrect interpretation of framing semantics leads to decryption failures,
state machine corruption, and subtle replay or ordering bugs.

These semantics are fundamental to protocol correctness and must be
architecturally fixed.

## Decision

E27 communication uses a strict layered model:

1. Transport layer
   - Responsible for socket connectivity only
   - Has no knowledge of protocol framing or encryption

2. Framing / Presentation layer
   - Defines the binary envelope surrounding payloads
   - Indicates whether the payload is encrypted
   - Encodes padding length and framing metadata
   - Applies encryption and decryption as required

3. Application layer
   - Operates only on fully decoded JSON objects
   - Has no awareness of framing or encryption

Framing and presentation semantics are owned entirely by the E27 backend.

## Rationale

Separating framing from application logic:
- prevents protocol leakage
- simplifies testing
- aligns with the documented E27 protocol layering
- mirrors the Java reference implementation

## Consequences

- No application-layer code may inspect or depend on framing bytes
- All encryption, padding, and word-swap logic is confined to the backend
- Errors in framing are classified as protocol errors, not API errors

## Scope / Non-Goals

- Does not define socket buffering strategies
- Does not mandate a specific class or file layout
- Does not define cryptographic algorithms

## References

- E27 API Comms Protocol
- Java PresentationLayer implementation
