Appendix B — Reserved ranges

Protocol reference

Appendix B — Reserved ranges

TL;DR. The reserved-discriminant ranges for future protocol extensions: which message-ID slots are earmarked for which categories (lifecycle, hot path, control plane, events, L1 lifecycle), the command-tag allocations within the lifecycle range, and the enum-allocation discipline for PhysicalKey and ErrorCode. Implementers extending the protocol pick from these ranges via PR.

1. Reserved message-ID ranges

For implementers extending the protocol:

  • Message IDs 0x04..=0x0F and 0x83..=0x8F: reserved for connection- lifecycle messages.
  • Message IDs 0x14..=0x1F and 0x93..=0x9F: reserved for hot-path messages.
  • Message IDs 0x24..=0x2F and 0xA3..=0xAF: reserved for further L1 Terminal lifecycle / per-pane control frames (phux-4li.10 allocated 0x22..=0x23 C→S and 0xA1..=0xA2 S→C from these ranges).
  • Message IDs 0x31..=0x3F and 0xC2..=0xCF: reserved for control plane.
  • Message IDs 0x41..=0x4F and 0xB3..=0xBF: reserved for events (phux-y2t allocated SUBSCRIBE_EVENTS = 0x41 C→S and EVENT = 0xB3 S→C from these ranges; 0x42..=0x4F and 0xB4..=0xBF remain open).

2. Command-tag allocations

Commands ride the generic COMMAND envelope (L1.md §1) and carry their own one-byte tag inside it. Allocated tags:

TagCommandOwnerStatus
0x07GET_SCREENL1.mdshipped
0x08ROUTE_INPUTL1.mdshipped
0x09KILL_TERMINALSL1.mdshipped
0x0cGET_TERMINAL_STATEL1.mdshipped
0x0dSUBSCRIBE_TERMINAL_EVENTSL1.mdshipped
0x0eUPGRADEL1.mdshipped
0x0fACQUIRE_INPUTL1.mdshipped
0x10RELEASE_INPUTL1.mdshipped
0x11SIGNAL_TERMINALL1.mdshipped
0x12REPORT_ASKEDL1.mdshipped
0x13DETACH_CLIENTSL1.mdshipped
0x14APPLY_INPUTL1.mdshipped
0x15PUT_FILEL1.mdshipped

KILL_TERMINALS at tag 0x09 reuses the slot freed by the removed CREATE_SESSION command. Per ADR-0030 (option B), the leaked session/collection lifecycle verbs are withdrawn and their tags are freed:

  • 0x09 — formerly CREATE_SESSION; reallocated to KILL_TERMINALS.
  • 0x0a — formerly RENAME_SESSION; freed, reserved, not reallocated. Rename is now an L3 metadata SET on phux.session.name/v1 (L3.md §3).
  • 0x0b — formerly KILL_COLLECTION; freed, reserved, not reallocated. Group teardown is KILL_TERMINALS.

A freed tag SHALL NOT be reallocated to an unrelated command without a PROTOCOL_VERSION bump, so that an old client speaking a withdrawn verb fails loudly rather than invoking new behavior.

3. Reserved enum ranges

PhysicalKey enum values and ErrorCode enum values are allocated sequentially. Implementers proposing new values open a PR against this document.

(Earlier drafts of the SPEC reserved a DiffOp tag range here; per ADR-0013, Terminal content is now a VT byte stream and DiffOp no longer exists as a wire concept.)