# ADR-0101: Schema-0 Envelope Semantics and Protocol Byte Meaning

Status: Accepted

## Context

E27 framed messages include a protocol byte and schema identifier
that determine how the payload must be interpreted.

Misinterpreting the protocol byte or schema semantics leads to
invalid decryption, incorrect padding removal, and message loss.

These semantics are invariant across E27 operation and must be fixed.

## Decision

For schema-0 E27 envelopes:

- The protocol byte is authoritative
- Bit 7 (0x80) indicates whether the payload is encrypted

If the payload is encrypted:
- The lower 4 bits of the protocol byte encode the padding length (0–15)
- Padding length must be honored exactly during decryption

If the payload is not encrypted:
- The lower 4 bits of the protocol byte are forced to 0x0F
- No padding removal is performed

The receiver must use the protocol byte, not payload inspection,
to determine encryption and padding behavior.

## Rationale

Encoding encryption and padding metadata in the protocol byte:
- avoids ambiguity
- allows future schema evolution
- prevents heuristic-based decoding

This matches both documentation and observed reference behavior.

## Consequences

- Padding length is never inferred
- Incorrect protocol byte values are fatal protocol errors
- Application-layer code never handles padding

## Scope / Non-Goals

- Does not define future schema versions
- Does not define checksum or MAC placement
- Does not define message ordering guarantees

## References

- E27 API Comms Protocol
- ADR-0100
