VerseVDI-Protocol/frames/datagram-v1.md

VerseVDI control datagram v1

Phase 3C adds bounded encoded video/audio and sequenced-input channels to the same transport envelope. The gateway forwards encoded bytes; it does not decode, encode, transcode, render, or expose provider traffic. Arbitrary binary clipboard data remains rejected.

All multi-byte integers are unsigned big-endian. The fixed header is 21 bytes:

Offset	Size	Field	Rule
0	2	magic	ASCII VD (0x56 0x44)
2	1	version	1 only
3	1	channel	registered channel identifier
4	1	flags	registry-defined; unknown bits reject
5	4	sequence	session-local wrapping sequence
9	8	timestamp_ms	sender timestamp, bounded by transport skew policy
17	1	fragment_index	zero-based; 0 when not fragmented
18	1	fragment_count	1 when not fragmented; index less than count
19	2	payload_length	exact payload byte count

The complete frame is at most 65,536 bytes and payload_length is at most 65,515. Truncated, oversized, unknown-version, unknown-channel, invalid-fragment, and length-mismatch frames are rejected before allocation proportional to the claimed payload. Media/provider identifiers are not registered channels.

Registered channels are control.ack.v1, control.cancel.v1, clipboard.text.v1, media.video.v1, media.audio.v1, and input.sequenced.v1. Media/input frames use application flow IDs 10, 11, and 12 and a path-MTU-safe payload limit of 1,179 bytes; larger encoded units use at most 16 validated fragments. Clipboard payloads are UTF-8 JSON text contracts and remain subject to the 65,536-byte text limit and explicit Server-owned direction, rate, and loop-token policy as defined in gateway-clipboard-v1.md.

Within an active Phase 3C gateway session, input.sequenced.v1 and the bidirectional reliable control.ack.v1 payloads additionally use the exact provider-neutral grammars in gateway-input-feedback-v1.md. Those grammars do not alter this datagram header or make provider traffic visible to the Verse client.