# DVeProto — Compatibility Policy

This is **not** a protocol feature. It is the ruleset for how versions relate across the project lifetime (1.x LTS → 2.x → … → Stable).

Applies from **Alpha Released** onward; 1.x rules already match Wire Freeze practice.

---

## Branches

| Line | Policy |
|------|--------|
| **1.x LTS** | Security fixes and critical bugfixes only. No new wire features. Binary wire stays `ver=0x14` (package 1.5 LTS). |
| **2.x** | Within one major (`2.*`), implementations MUST remain as interoperable as practical. Prefer additive caps over breaking layout changes. |
| **Next major (3.x, …)** | May break wire/handshake; requires new major, new vectors, and a new freeze report. |

---

## Negotiation

1. At handshake, peers advertise supported **protocol / wire / suite / caps**.
2. They select the **highest mutually supported** version and capability set.
3. If no common version or required suite exists, the connection **MUST abort** with a **documented error reason** (stable error code or cleartext close cause — defined per major; Alpha uses HandshakeError / disconnect).
4. Unknown caps bits/fields MUST be ignored by receivers (forward compatibility), unless marked mandatory in the negotiated set.

---

## Wire stability (within one major)

**Forbidden** inside the same major (e.g. all `2.x` after Alpha freeze):

* Removing an existing Wire header field;
* Changing field size, order, or endianness;
* Reusing a PacketType / flag bit for a different meaning;
* Changing HKDF labels or AEAD nonce construction for an already-shipped suite id.

**Allowed** (additive):

* New optional flags / PacketTypes behind capability bits;
* New cipher suites with new suite ids (old suites remain);
* New documents, carriers, and higher layers (DVeNet, …) that reuse frozen Alpha crypto/transport.

Alpha snapshot: [`ALPHA_FREEZE_REPORT.md`](./dveproto-tests/ALPHA_FREEZE_REPORT.md) (filled at Alpha Released).

---

## Identity

* **NodeID** (Ed25519 public key) is stable node identity across connections.
* **ConnectionID** is per-path/session and MUST NOT be treated as NodeID.
* A node MAY hold many ConnectionIDs; peers MUST key long-term trust on NodeID (and explicit policy), not on IP or ConnectionID alone.

---

## Test obligation

Any claimed-compatible implementation MUST pass the shared suite for that release line:

* `v2/test_vectors.json` (and later vector files for that major);
* `dveproto-tests/` runners applicable to the release;
* Exit / entry criteria docs for that milestone.

---

## Error documentation

Abort / reject reasons SHOULD be:

* Machine-distinguishable where possible (exception type, close code, or error frame);
* Listed in release notes / CHANGELOG when newly introduced;
* Never silent accept of failed AEAD, bad signatures, or unsupported mandatory versions.

---

## Summary

```
1.x LTS     → security only
2.x         → negotiate max common; additive only inside major
no common   → abort with documented reason
wire fields → no remove/resize/reorder inside major
```