# ADR-0011: Dual Sequence Numbers in E27 Protocol (Envelope vs JSON)

Status: Accepted

## Context

The E27 protocol includes two distinct sequence number mechanisms:

- A sequence number in the framed protocol envelope
- A "seq" field inside the JSON application payload

Early implementations and documentation can blur these concepts,
creating a risk of conflation that would impact correctness,
replay protection, future crypto changes, and protocol evolution.

This distinction is fundamental to the meaning of the protocol,
not merely an implementation detail.

## Decision

The E27 protocol is defined as having two independent sequence numbers:

1. Envelope sequence number
   - Exists at the protocol framing level
   - Is protocol-facing and future-oriented
   - May be used for transport ordering, replay protection,
     or future protocol features
   - Is not authoritative for request/response correlation today

2. JSON sequence number ("seq")
   - Exists inside the JSON application payload
   - Is application-level
   - Is authoritative for request/response correlation
   - Is required for correct API dispatch and response handling

These two sequence numbers serve different purposes and
must never be conflated, substituted, or inferred from one another.

## Rationale

Treating the envelope and JSON sequence numbers as interchangeable
would incorrectly collapse protocol and application layers.

Preserving this separation:
- matches the protocol's layered design
- enables future protocol evolution without breaking API logic
- avoids subtle correctness and security bugs

## Consequences

- All request/response correlation logic uses the JSON "seq" field
- Envelope sequence handling remains isolated to protocol framing
- Backends must track and reason about both sequences independently
- Tests must validate that the two sequences are not coupled

## Scope / Non-Goals

- Does not define how envelope sequence numbers are generated
- Does not mandate replay protection behavior
- Does not require current use of envelope sequence numbers

## References

- E27 API Comms Protocol
- Java reference implementation
- DDR-0004
