# gateway-input-feedback Specification

## Purpose
Define the provider-neutral typed input, feedback, and text-clipboard envelopes
used across the authenticated Verse gateway boundary.
## Requirements
### Requirement: Typed sequenced input envelope
The `input.sequenced.v1` payload SHALL begin with ASCII `VGI1`, a one-byte
event kind, and one-byte payload length. It SHALL contain exactly one bounded
keyboard, mouse-button, relative-mouse, UTF-8 scalar, or controller-state
event. False keyboard/mouse state and zeroed controller state are explicit
releases. Multibyte integer fields SHALL be big-endian. Unknown kinds,
length mismatches, malformed UTF-8, unsupported controller indices, and
reserved fields SHALL be rejected before provider translation.

#### Scenario: Keyboard state change
- **WHEN** a client sends a valid keyboard press or release envelope
- **THEN** the gateway forwards the corresponding typed provider input on its
  reliable keyboard channel and records the pressed state for cleanup.

#### Scenario: Invalid input envelope
- **WHEN** a client sends an envelope with an unknown event kind, invalid
  length, malformed UTF-8 scalar, or nonzero reserved field
- **THEN** the gateway rejects it without sending provider input or changing
  pressed state.

### Requirement: Explicit input release
The typed input envelope SHALL represent release of each keyboard key,
mouse button, and controller state. Gateway cleanup SHALL send a typed release
for every accepted pressed state before provider disconnect; it SHALL NOT use
an implementation-specific release-all provider command.

#### Scenario: Tunnel cleanup with pressed input
- **WHEN** a tunnel closes after accepted pressed keyboard, mouse, or
  controller input
- **THEN** the gateway emits the corresponding individual provider release
  packets reliably before starting provider disconnect.

### Requirement: Bounded provider feedback control envelope
The registered bidirectional reliable `control.ack.v1` flow SHALL define an ASCII `VGF1` envelope
with a direction byte, type byte, big-endian payload length, and exact payload
bytes. Only host termination, rumble, and HDR feedback SHALL be valid from the
gateway to the client. Only IDR, FEC/loss feedback, and an empty terminal receipt
SHALL be valid from the client to the gateway. The terminal receipt SHALL be
valid only while the same session awaits receipt of its one terminal event and
MUST NOT be forwarded to the provider. The envelope SHALL contain no provider
address, certificate, credential, or opaque provider packet.

#### Scenario: Host termination forwarding
- **WHEN** the Apollo adapter receives an authenticated host termination
  packet
- **THEN** the gateway forwards a bounded `VGF1` termination envelope over
  reliable Verse control and reports the provider state separately.

#### Scenario: Terminal event receipt
- **WHEN** a client receives the reliable typed terminal event
- **THEN** it sends the empty terminal receipt and the gateway owns bounded
  tunnel closure without forwarding the receipt to the provider.

#### Scenario: Unauthorized or malformed feedback
- **WHEN** feedback is disabled by policy, has an invalid direction/type/length,
  contains a forbidden provider field, or sends a terminal receipt outside the
  awaiting-terminal state
- **THEN** the gateway rejects it without forwarding or provider mutation.

### Requirement: Policy-bound text clipboard envelope
The reliable `clipboard.text.v1` flow SHALL carry only a typed UTF-8 text
envelope with exact direction and a 16--128 character canonical unpadded ASCII
base64url loop token. The Server SHALL mint
the enabled directions, maximum text bytes, and maximum updates per minute in
authenticated provider work. The gateway SHALL reject disabled direction,
unknown fields, files, file URLs, client folders, binary data, malformed UTF-8,
oversized values, rates above policy, and reflected/replayed loop tokens. It
SHALL not put clipboard content, provider routes, or credentials in telemetry,
audit, state, or errors.

#### Scenario: Clipboard audit metadata
- **WHEN** the gateway successfully delivers, suppresses, or rejects a clipboard update
- **THEN** it sends an authenticated Server audit record with only direction,
  bounded byte count, outcome, and a fixed reason; it never includes text or
  the loop token.

#### Scenario: Clipboard delivery failure
- **WHEN** provider-to-client control delivery fails
- **THEN** the gateway does not report the update as forwarded.

#### Scenario: Reflected clipboard value
- **WHEN** a client-originated text value returns from the provider with the
  matching retained token/value pair
- **THEN** the gateway suppresses the reflected update without a second
  provider mutation or client delivery.