VerseVDI-Protocol/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/design.md

Context

The registered input.sequenced.v1 flow has a payload bound but no typed payload grammar. RC5 also has no provider-to-client envelope for host termination, rumble, or HDR feedback. The Data Plane must translate these states to the provider without exposing Apollo packet formats or credentials.

Goals / Non-Goals

Goals:

• Define fixed, bounded, endian-explicit gateway payloads for keyboard, mouse, UTF-8 text, and controller state.
• Define a reliable control envelope for provider feedback and termination.
• Define an explicit release operation for every pressed key/button/controller.
• Keep provider packet encodings and endpoint details internal to the Data Plane.

Non-Goals:

• Touch, pen, motion, file transfer, binary clipboard, or provider-specific packets.
• Changing RC5, moving an existing tag, or making the Connection Server parse streaming input.

Decisions

• Define a new binary payload grammar beneath the existing registered flows. This avoids changing the authenticated tunnel header while removing the untyped device/opaque-payload ambiguity. JSON was rejected because input is latency-sensitive and fixed binary bounds are simpler to validate before allocation.
• Input events use explicit event kinds and fixed payload lengths except UTF-8 text, which is limited to one valid Unicode scalar value. This permits exact provider translation and deterministic cleanup.
• Provider feedback and termination use the existing bidirectional reliable control channel with a distinct magic, direction, type, and length. A new channel was rejected because the existing channel is already authenticated, reliable, and versioned.
• Protocol contents and fixtures are finalized before a new immutable release candidate is created. RC5 remains an unchanged dependency for current consumers until they explicitly adopt the new revision.

Risks / Trade-offs

• [New client adoption is required] -> retain RC5 unchanged and publish an explicit capability/version mismatch before any provider allocation.
• [Provider feedback can be high rate] -> allow only termination, rumble, and HDR payload types with fixed maximum sizes; other types reject.
• [Pressed-state loss during disconnect] -> gateway records accepted presses and emits typed releases during cleanup before provider disconnect.