feat(protocol): define gateway control envelopes

2026-07-29 17:24:18 +07:00
parent 36f6edffca
commit 0ea21cd3f2
29 changed files with 1445 additions and 41 deletions
@@ -0,0 +1,50 @@
+## 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.