fix(gateway): close Phase 3C audit gaps

2026-07-30 01:46:00 +07:00
parent 040ca73ce9
commit d3852d15f3
23 changed files with 1619 additions and 219 deletions
@@ -0,0 +1,47 @@
+## 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.
+- Treat the current exact `client_decode` string as the negotiated decode profile. The default advertises the bounded H.264+HEVC set, and provider work must be a member of it.
+- Consume existing provider events in the gateway session loop. Termination and disconnect cancel forwarding, then reuse current cleanup/release/reporting machinery and its cleanup-pending result.
+- On a full audio FEC map, evict the oldest block according to existing block ordering and increment existing drop telemetry.
+- Sample existing process counters at heartbeat time; calculate rate from byte and monotonic-time deltas while leaving configured capacity in registration.
+- Build qualification on the existing native/provider fixture and public QUIC client path. Production stage observations replace the standalone codec 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 media] → Cancel the session first and let bounded cleanup serialize final release/reporting.
+- [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.
+- [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.