Skip to content

Commit d56135c

Browse files
fix(docs): add outer frame encapsulation preamble to SPEC.md §3 (PILOT-419) (#2)
Add a preamble to §3 (Packet Format) explaining that all wire-format frames are encapsulated in a tunnel envelope identified by 4-byte magic bytes. Documents the four frame types (PILT, PILS, PILK, PILA) with their magic byte values and clarifies that §3 describes the inner header for PILT frames while §4 covers the other frame type layouts. A first-time reader encountering §3 would not know the header is tunnel-encapsulated — this preamble addresses that gap. Closes PILOT-419
1 parent 7bb297e commit d56135c

1 file changed

Lines changed: 15 additions & 0 deletions

File tree

SPEC.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,21 @@ Socket address includes a port: `1:0001.F291.0004:1000`
8787

8888
## 3. Packet Format
8989

90+
All Pilot Protocol wire-format frames are encapsulated in a tunnel envelope
91+
identified by a 4-byte magic byte prefix. Four frame types are defined:
92+
93+
| Magic | Frame Type |
94+
|-------------------------|--------------------------------------|
95+
| `PILT` (0x50494C54) | Unencrypted tunnel frame (plaintext) |
96+
| `PILS` (0x50494C53) | AES-256-GCM encrypted tunnel frame |
97+
| `PILK` (0x50494C4B) | X25519 key exchange frame |
98+
| `PILA` (0x50494C41) | Ed25519 + X25519 authenticated key exchange |
99+
100+
The frame types are detailed in §4 below. This section (§3) describes the
101+
inner 34-byte header shared by PILT (plaintext) frames. Encrypted (PILS),
102+
key-exchange (PILK), and authenticated (PILA) frames use different header
103+
layouts documented in §4.
104+
90105
### 3.1 Header Layout (34 bytes)
91106

92107
```

0 commit comments

Comments
 (0)