# Protocol Versioning Plan
## Objectives
- Keep launcher/runtime message protocol evolvable without silent breakage.
- Make every protocol change explicit, reviewable, and testable.
- Provide a rollback-safe upgrade path.
## Versioning Policy
Use semantic protocol versions: `MAJOR.MINOR.PATCH`.
Current baseline: `1.0.0` (mapped to runtime `protocol_version = 1`).
- `MAJOR`: breaking message schema or state machine changes.
- `MINOR`: backward-compatible fields/events added.
- `PATCH`: non-semantic fixes (doc, validation text, telemetry-only fields ignored by old peers).
## Envelope Requirements
Every protocol message should carry:
- `protocol_version`
- `job_id`
- `seq`
- `kind`
- `src_rank`
- `dst_rank` (or broadcast marker)
## Compatibility Rules
- New runtime must reject unknown `MAJOR` with explicit error code.
- New runtime must accept older `MINOR` in the same `MAJOR` when defaults are defined.
- Optional fields require stable defaults.
- Removed fields require at least one deprecation cycle.
## Error Codes
Reserve protocol-focused errors:
- `PROTO_UNSUPPORTED_VERSION`
- `PROTO_INVALID_ENVELOPE`
- `PROTO_INVALID_STATE_TRANSITION`
- `PROTO_PAYLOAD_TOO_LARGE`
- `PROTO_SEQUENCE_GAP`
## Change Workflow
1. Open a Protocol Versioning Task issue from the template.
2. Update schema docs and state machine docs.
3. Add unit tests for success and reject paths.
4. Add e2e case if behavior visible in demo.
5. Bump protocol version according to policy.
6. Document migration and rollback in release notes.
## Definition of Done
- Protocol change reviewed by runtime owner.
- CI green with protocol tests.
- Docs updated in technical spec.
- Release checklist includes compatibility note.