# ADR-0103: Session Lifecycle Boundaries — Unframed vs Framed Traffic and Responsibilities

Status: Accepted

## Context

The E27 protocol transitions through multiple lifecycle phases,
during which different message formats and responsibilities apply.

Specifically:
- Early session establishment exchanges are not fully framed
- Later communication requires strict framing, encryption, and validation

Failing to clearly define where these boundaries lie leads to:
- incorrect decoding assumptions
- premature framing or decryption attempts
- leakage of protocol responsibilities into application logic

This boundary is fundamental to protocol correctness.

## Decision

The E27 session lifecycle is divided into distinct phases with
clear framing and responsibility boundaries:

1. Pre-session phase (unframed / partially protected)
   - Includes initial panel hello and client hello exchanges
   - Outer JSON payloads are not framed by the presentation layer
   - Sensitive fields within JSON may be field-level encrypted
   - No session keys are active
   - No framed or session-encrypted traffic is permitted

2. Session bootstrap completion boundary
   - Occurs once client hello response is received, validated,
     and session keys are installed
   - Marks the transition to framed session traffic

3. Online session phase (fully framed)
   - All subsequent traffic is framed
   - Encryption and padding semantics apply per ADR-0100 and ADR-0101
   - Application-layer code sees only decoded JSON
   - Authorization escalation occurs within this phase

All transitions between these phases are owned and enforced
by the E27 backend state machine.

## Rationale

Explicitly defining the unframed-to-framed boundary:
- prevents incorrect decryption attempts
- avoids heuristic parsing
- preserves clean layering between protocol and application logic
- matches documented and observed panel behavior

This separation is essential for future protocol evolution.

## Consequences

- Application-layer code must never receive unframed data
- Presentation/framing logic must be disabled until session bootstrap completes
- Session-encrypted traffic must not occur prior to key installation
- Errors crossing phase boundaries are protocol errors

## Scope / Non-Goals

- Does not define the exact wire format of unframed messages
- Does not mandate timing or retry policies
- Does not define authorization privilege levels

## References

- ADR-0100: E27 Framing and Presentation Layer Semantics
- ADR-0101: Schema-0 Envelope Semantics and Protocol Byte Meaning
- ADR-0102: E27 Link and Session Key Lifetimes
- E27 API Comms Protocol
