# ADR-0106: Replay, Ordering, and Idempotency Policy (Current and Deferred)

Status: Accepted

## Context

E27 provides two sequence mechanisms:
- an envelope sequence number at the framing/protocol layer
- a JSON "seq" field at the application layer

The protocol may evolve to incorporate stronger replay protection or ordering
constraints at the envelope level. Today, the documented and observed behavior
primarily uses the JSON "seq" field for request/response correlation.

Tests and maintainers need a clear statement of current expectations and what is
explicitly deferred, to avoid locking in accidental behaviors.

## Decision

Current (enforced) policy:

1. Application-level correlation is authoritative
   - The JSON "seq" field is authoritative for matching responses to requests.
   - A response that cannot be correlated by JSON "seq" is treated as an ApiError.

2. Envelope sequence is protocol-level and non-authoritative today
   - Envelope sequence numbers are treated as protocol metadata.
   - They are not used for request/response matching.
   - They are preserved and tracked independently (see ADR-0011).

3. Duplicate handling
   - Duplicate responses with the same JSON "seq" are permitted to be ignored
     once the request has been completed.
   - Duplicate uncorrelated responses are treated as ApiError.

4. Ordering
   - The system does not assume strict in-order delivery.
   - Correctness relies on correlation by JSON "seq", not on arrival order.
   - Out-of-order delivery that still correlates correctly is acceptable.

5. Idempotency expectations
   - Read/query APIs are assumed safe to retry.
   - Command/mutation APIs must not be automatically retried unless explicitly
     documented as safe, or unless a higher layer determines idempotency.

Deferred (explicitly not yet enforced) policy:

6. Replay protection
   - Strong replay protection using envelope sequencing is deferred.
   - HMAC validation enforcement policy is addressed separately.

7. Session-scoped ordering guarantees
   - No global ordering guarantee beyond JSON correlation is claimed.
   - Any future ordering guarantees require a new ADR.

## Rationale

This policy:
- matches the current observed use of JSON "seq"
- avoids conflating protocol and application layers
- permits future evolution (envelope seq, replay protection) without breaking semantics
- provides a stable basis for tests and contributor expectations

## Consequences

- Tests should validate JSON "seq" correlation as the primary mechanism
- Envelope sequencing must remain logically independent
- Retry behavior must be conservative for mutating operations
- Future replay protection, if implemented, will require new ADR(s)

## Scope / Non-Goals

- Does not define how envelope sequence numbers are generated
- Does not mandate a specific storage window for replay detection
- Does not define transport buffering or pipelining strategy

## References

- ADR-0011: Dual Sequence Numbers in E27 Protocol (Envelope vs JSON)
- ADR-0105: E27 Error Classification and Responsibility Boundaries
- HelpDealerAPI_UL documentation
