VerseVDI-Data-Plane/openspec/changes/phase3c-gateway-audit-remediation/design.md

Context

The implementation already contains a source-shaped Apollo fake, native recovery, bounded gateway queues, fair pacing, Verse framing/QUIC, independent client support, lifecycle reporters, and low-cardinality telemetry. Audit defects arise where those existing pieces are bypassed or not connected.

Goals / Non-Goals

Goals:

• Reuse the existing production path for policy, lifecycle, recovery, telemetry, and qualification.
• Delete duplicate qualification simulation.
• Preserve all trust, cleanup, and resource bounds.

Non-Goals:

• Add codecs, provider transports, dependencies, or a generic lifecycle/telemetry framework.
• Claim live Apollo/macOS/firewall interoperability.
• Run the normative qualification before immutable consumer resolution.

Decisions

• Format ANNOUNCE from ProviderStreamPolicy using the pinned Moonlight common-c bitrate and codec attributes. H.264 and HEVC with audio enabled are supported; AV1 and audio disabled fail before management/network readiness.
• Advertise ordered registered hevc-opus and h264-opus profiles and delegate policy-compatible selection to generated Protocol intersection behavior. There is no Data Plane capability grammar.
• Before /applist or /launch, validate the selected policy against source-backed Apollo /serverinfo codec flags and HEVC luma bounds plus reviewed source limits for dimensions, frame rate, bitrate, and audio where Apollo exposes no dynamic field. Reject rather than cap or downgrade.
• Quiesce provider media sockets and the bounded forwarding path before emitting an existing terminal or disconnected event. Reuse current cleanup/release/reporting machinery and its cleanup-pending result; final control delivery has no fixed drain delay.
• On a full audio FEC map, evict the oldest block according to existing block ordering and increment existing drop telemetry.
• Carry provider receipt and queue-enqueue timestamps through the existing bounded media value. Queue residence, active processing, and scheduler pacing are sampled separately, once per complete provider media unit.
• Sample existing process counters at heartbeat time; calculate rate from byte and monotonic-time deltas while leaving configured capacity in registration.
• Build qualification on source-shaped pinned-mTLS Apollo management, encrypted RTSP, ENet, and provider UDP plus the public QUIC client path. Per-traversal stage deltas replace the standalone codec/parser and arithmetic impairment simulator; short smoke gates freeze the wiring, while normative durations remain deferred.
• Preserve the production fair-pacer schedule across short host-timer overshoots so measured allocation can catch up within the already bounded provider queue instead of accumulating timer granularity as lost capacity.

Risks / Trade-offs

• [Apollo cannot represent disabled audio truthfully] → Reject it rather than silently streaming stereo.
• [Provider event races with queued or new media] → Quiesce ingestion and serialize forwarding with terminal event delivery before cleanup.
• [Counter reset or zero elapsed time] → Emit zero measured rate and establish a new baseline.
• [Corrected qualification is more expensive] → Run only short smoke tests until the immutable candidate is frozen.
• [Apollo exposes incomplete dynamic capability detail] → Use only source-backed fields and explicit reviewed bounds; never infer support by silent capping.
• [Pacer catch-up can emit a short burst after timer overshoot] → Clamp schedule debt to five milliseconds in addition to the existing 16-packet provider queue.

Migration Plan

Land focused red/green repairs locally, verify through the temporary Protocol workspace, preserve old artifacts as superseded, and stop at the publication boundary. After a separately authorized immutable Protocol release is pinned, freeze inputs and run the corrected normative qualification once.

Open Questions

None.