From 5ea4b6add7a9f91c57a70580869493140383d418 Mon Sep 17 00:00:00 2001 From: AAA <35992542+TNTcraftHIM@users.noreply.github.com> Date: Thu, 27 Aug 2026 01:25:21 +0800 Subject: [PATCH] docs: record candidate quality route model (#288) --- docs/research/realtime-quality-adaptation.md | 80 ++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.md index ded6dd7..fe6156c 100644 --- a/docs/research/realtime-quality-adaptation.md +++ b/docs/research/realtime-quality-adaptation.md @@ -425,6 +425,77 @@ no quality-driven relay-wide abdication. Freeze entry/exit, probation evidence, improvement margin, cooldown, and room disruption budget must be calibrated from real annotated sessions; paper and library defaults are not Screener thresholds. +The candidate active model has one `QualityEpisode` inside the existing room +controller, not a second optimizer. It keeps only the exact subject, prior +route or capacity, trigger-evidence revision, trial revision, probation +baseline, one restore flag, and a cooldown `notBefore`. Cooldown expiry does not +wake the room; the next real room or evidence event may reconsider it. Join, +hard recovery, departure, pause, capacity, and SFU drain work always preempt and +clear lower-priority quality work. + +One episode asks the existing deterministic filters and ordering for only the +first eligible candidate. It prepares that single route through the existing +capacity and server-resource reservations, retains the old route until first- +frame commit, then measures the new presented path sequentially in probation. +Failure is inconclusive and enters cooldown; it does not enumerate more parents. +Probation may restore the old tuple once through the same child operation. A +quality-only trial is skipped when make-before-break overlap is unavailable; +bounded-gap cutover remains reserved for availability recovery. + +The same episode model covers every transport without a P2P/SFU state matrix: + +- one degraded child is the subject of an ordinary reparent operation; +- a relay with degraded ingress is itself the child, so its subtree remains; +- healthy ingress plus corroborated degradation across multiple exact child + sender/receiver pairs may reduce that parent's effective capacity by one, + letting existing overflow reconciliation move one child at a time; +- a Host-wide egress problem with a healthy source may trial the existing SFU + publication as one candidate, but only with normal Host overlap, publication, + subscription, and admission reservations; and +- an SFU-fed Viewer remains an ordinary peer parent candidate and never creates + a second publication. + +Capacity recovery is event-driven half-open: after cooldown, a later real demand +may use one provisional slot, and that child supplies probation evidence. No +demand means no probe or rebalance. At `C=3`, a full Host has no fourth-copy +overlap; it must first move one child make-before-break through an already +eligible peer or skip the Host-to-SFU quality trial. SFU admission rejection +keeps the healthy route and ends the episode without joining the availability +resource-wait queue. + +Current-path evidence cannot prove an unconnected path is better. FPS, +resolution, and bitrate require a same-window source baseline; configured +ceilings are not delivered floors. Loss, RTT, jitter, NACK/PLI, encode/decode +time, and `qualityLimitationReason` remain attribution unless corroborated by +presented-path evidence. Parent-wide abdication additionally needs evidence from +multiple distinct current children plus their exact sender constraints while +the parent ingress remains healthy; `C=1` therefore cannot infer parent-wide +quality from one child. + +Production shadow data must determine every policy number: entry/exit floor, +minimum eligible windows and duration, aligned-window tolerance, probation, +meaningful improvement margin, cooldown, per-room disruption budget, `C=3` +quorum, Host-to-SFU gate, inconclusive rate, and browser/mobile missing-field +rate. Overcast's percentage, End System Multicast's hold-down/probe cadence, +QUIC path timers, circuit-breaker defaults, and paper test payloads are evidence +about structure only and are not accepted thresholds. + +Overcast and ALMI support measured gain versus disruption before switching. +RFC 8326 supports drain-before-removal; RFC 9000 supports validating a new path +while the old path remains usable and not inheriting old congestion state. RFC +7196's documented damping false positives support shadow-first observation, but +its penalty score is not adopted. A half-open concept is useful without adding +a circuit-breaker dependency or sliding failure-rate controller. SplitStream, +CoolStreaming/DONet, and SAAR require multi-tree striping, mesh/block pull, or a +second active control overlay and remain explicit no-go references for this +single-graph product. + +This research adds no dependency and copies no implementation. LiveKit is +Apache-2.0, libwebrtc uses its BSD-style license, and Resilience4j is +Apache-2.0; papers, RFCs, and W3C documents are referenced only for design +evidence. GPL/AGPL reference implementations remain study-only under the +repository license boundary. + ## Current Verification Gaps - Real games under competing CPU/GPU load at 720p30, 1080p30, and 1080p60. @@ -477,4 +548,13 @@ interval. Missing counters and identity changes remain unknown, not zero. - [LiveKit advanced and backup codec contract](https://github.com/livekit/client-sdk-js/blob/v2.22.0/src/room/track/options.ts) - [Overcast parent measurement and hysteresis](https://pdos.csail.mit.edu/~jj/jannotti.com/papers/overcast-osdi00/) - [ALMI application-level multicast](https://www.usenix.org/legacy/event/usits01/full_papers/shi/shi_html/) +- [End System Multicast](https://static.usenix.org/events/usenix04/tech/general/full_papers/chu/chu_html/index.html) +- [RFC 8326 graceful routing shutdown](https://www.rfc-editor.org/rfc/rfc8326.html) +- [RFC 9000 path validation and migration](https://www.rfc-editor.org/rfc/rfc9000.html) +- [RFC 7196 route-flap damping](https://www.rfc-editor.org/rfc/rfc7196.html) +- [RFC 8836 WebRTC congestion-control interactions](https://www.rfc-editor.org/rfc/rfc8836.html) +- [Resilience4j circuit-breaker states](https://resilience4j.readme.io/docs/circuitbreaker) +- [SplitStream](https://www.microsoft.com/en-us/research/wp-content/uploads/2003/02/castro03splitstream.pdf) +- [CoolStreaming/DONet](https://researchportal.hkust.edu.hk/en/publications/coolstreamingdonet-a-data-driven-overlay-network-for-peer-to-peer/) +- [SAAR](https://static.usenix.org/event/nsdi07/tech/full_papers/nandi/nandi_html/index.html) - [Media Capabilities](https://www.w3.org/TR/media-capabilities/)