Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs: accept native-edge route convergence (#297)
AAA9468234d8606
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex b7ec3b7b..f8cb958c 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -1,6 +1,6 @@# ADR-0005: Automatic Hybrid Media Routing-- Status: accepted; base route and evidence-only quality shadow deployed+- Status: accepted; base route and quality shadow deployed; native-edge convergence not implemented- Date: 2026-08-20- Last updated: 2026-08-27@@ -88,14 +88,16 @@ stale asynchronous results fail closed.The old committed route remains authoritative while the candidate prepares.Parent and child prepare the same server-issued connection identity. Standard-ICE connected is progress only. The exact candidate child decoding its first new-video frame is the sole application commit proof.+ICE connected is progress only. For availability work, the exact candidate child+decoding its first new video frame is the application commit proof.-The media-ready call commits typed endpoint/SFU admission before graph promotion.-Success broadcasts the candidate revision. Failure, timeout, pause, or stale-authority destroys the candidate, releases reservations idempotently, and-broadcasts a strictly newer rollback revision before another prepare. Clients-never infer rollback from silence or an older revision.+For availability work, the media-ready call commits typed endpoint/SFU+admission before graph promotion. A quality trial treats first decoded frame as+readiness and requires the native edge proof below. Success broadcasts+the candidate revision. Failure, timeout, pause, or stale authority destroys+the candidate, releases reservations idempotently, and broadcasts a strictly+newer rollback revision before another prepare. Clients never infer rollback+from silence or an older revision.Make-before-break is used only when all required reservations exist. Availabilityrepair may use one explicitly planned bounded-gap retirement after server@@ -175,11 +177,55 @@ the committed graph, suppresses decoded-stall authority, and leaves new Viewerswaiting. Resume starts reconciliation from the current graph. Page-hidden walltime is rebaselined before it can contribute to a stall decision.-Quality evidence is observation-only. Current low bitrate/FPS/resolution, loss,-RTT, jitter, freeze, or sender limitation does not change candidates, capacity,-SFU use, or graph authority. Screener has no weighted route score, parent-wide-quality inference, all-pairs probe, hysteresis controller, or periodic rebalance.-Open investigation remains in [TODO](../todo.md).+Deployed quality evidence remains observation-only. The accepted next slice is+continuous local convergence inside the same graph, reconcile loop, and+room-serial child operation. Availability first gets every Viewer usable media;+quality work runs only while no join, failure, pause, identity, departure,+capacity, or SFU-resource work needs that operation.++Each exact current or pending edge has one native state: `unknown`, `healthy`, or+`degraded`. For ordinary P2P, the parent reports the exact outbound sender's+WebRTC `qualityLimitationReason` and cumulative durations. One complete+same-identity delta in `none` is healthy; one in `bandwidth` or `cpu` is+degraded; `other`, missing, reset, hidden, or stale evidence is unknown. SFU+publication and subscription state remains owned by LiveKit plus the exact+Viewer's continuing decoded progress. Screener does not combine loss, RTT,+jitter, bitrate, FPS, resolution, or freezes into another score.++When the current source path remains degraded, the controller considers the+shallowest affected child first and uses the existing deterministic candidate+filters, ordering, cursor, reservations, and total deadline. Candidate parents+must have a healthy source path and available steady capacity. Only one+candidate runs at a time; the old route keeps playing. First decoded frame proves+candidate usability, and a complete healthy native edge delta proves the new+path has escaped the old limitation. If the old edge recovers, the candidate is+degraded or unknown, authority changes, or the deadline expires, the candidate+is aborted and the graph stays unchanged. A successful commit clears and+rebaselines quality state for that edge and its affected subtree.++The same rule supplies both active parent change and relay abdication. A bad+relay ingress reparents that relay while retaining its subtree. A bad exact+parent-to-child sender moves only that child. If several senders on one parent+are degraded, one child moves and all remaining native states are observed+again; relief can cancel the remaining work without a parent score or explicit+capacity penalty.++The Host capture/source is a separate fact. A stalled source cannot be repaired+by topology. When capture is progressing but Host-origin edges remain degraded,+healthy Peer candidates stay first. If no Peer candidate can establish a healthy+edge, the same operation may create or reuse the one bounded SFU publication as+the suffix. Host-to-SFU publication health and the first SFU Viewer's decoded+progress must both hold before commit. That SFU-fed Viewer then remains an+ordinary Peer parent, allowing `SFU -> Viewer -> Peer` distribution without+turning every Viewer into an SFU subscription.++After commit, the new active identity starts from unknown and must establish a+fresh healthy delta before a later degradation can trigger another move. There+is no periodic wake, weighted prediction, global optimizer, persistent parent+blacklist, custom congestion controller, or manual SFU layer selection. The+result converges gradually to a local stable topology: no current degraded edge+has a proved healthy candidate under the current graph and resource facts. It+does not promise a static mathematical global optimum.## Consequences@@ -196,6 +242,8 @@ Negative:- Browser relay creates per-child decode/re-encode cost;- make-before-break requires temporary reservations and some availability repairmay require a bounded gap; and+- active quality work is local and event-driven, so it does not promise a+ globally optimal tree or react when native evidence remains unknown; and- UDP-only media ends in explicit failure on fully blocked networks.## Related Decisions And Evidencediff --git a/docs/adr/0007-path-isolated-representation-quality.md b/docs/adr/0007-path-isolated-representation-quality.mdindex b92698b7..7eaeac82 100644--- a/docs/adr/0007-path-isolated-representation-quality.md+++ b/docs/adr/0007-path-isolated-representation-quality.md@@ -109,9 +109,8 @@ LiveKit HIGH+LOW publication without backup codec.- A Host may need to lower its explicit share profile when encoder or uplinkcapacity is insufficient; Screener does not silently remove constrainedViewer support.-- Quality-based topology optimization remains unimplemented. Accepting it later- requires evidence for alternative-path measurement and a separate route-model- decision.+- ADR-0005's native-edge local convergence remains unimplemented. Weighted or+ global topology optimization still requires another route-model decision.## Stop Lines@@ -121,8 +120,8 @@ LiveKit HIGH+LOW publication without backup codec.local pre-share Host selector is the only manual codec surface.- No manual SFU layer selector, forced single HIGH publication, or per-Viewerencoder.-- No quality score, all-pairs probing, periodic rebalancing, or speculative- parent switching.+- No quality score, all-pairs probing, periodic rebalancing, or parent switching+ outside ADR-0005's native-edge operation.- No AdaptiveStream while a subscriber can relay the track.- No quality or hardware claim from configured options alone.diff --git a/docs/product/media-quality.md b/docs/product/media-quality.mdindex e79bacc4..7a42f3f8 100644--- a/docs/product/media-quality.md+++ b/docs/product/media-quality.md@@ -95,8 +95,9 @@ resolution, FPS, bitrate, loss, jitter, RTT, and encode/decode behavior when theBrowser exposes them; missing or reset counters remain unknown.The current quality shadow accepts only current foreground presentation evidence-and never changes routes or media settings. Quality-driven topology work is-parked in [TODO](../todo.md).+and never changes routes or media settings. ADR-0005 accepts native-edge local+topology convergence that is not implemented or deployed; weighted/global+optimization remains parked in [TODO](../todo.md).Web pages cannot guarantee Host background capture, mobile background playback,or relay execution after Browser/OS suspension. Those remain physical lifecyclediff --git a/docs/project-memory.md b/docs/project-memory.mdindex 31230b11..73acb204 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -34,10 +34,13 @@ implementation and routine UI detail.publication; Screener configures no TURN or TCP media route.- Every endpoint shares one steady outbound-copy cap, default `2` and limited to`1..3`. One room controller owns one committed graph, one reconcile loop, and- one serial child operation. First decoded frame is candidate commit proof.+ one serial child operation. First decoded frame commits availability work;+ accepted quality work adds native edge proof before commit in that operation.- WebRTC and LiveKit own congestion control, media adaptation, reconnect, and SFU- layers. Current route quality is diagnostic; no weighted score, all-pairs- probe, parent-wide inference, or periodic rebalance is accepted.+ layers. Current source keeps route quality diagnostic. The accepted next slice+ is event-driven local topology convergence from their native edge state, with+ bounded SFU only after healthy Peer escape fails. No weighted score, all-pairs+ probe, parent-wide prediction, or periodic rebalance is accepted.- Browser video uses `motion`; each share chooses H.264 with VP8 fallback throughan actual sender probe unless the Host explicitly selects VP8 or H264. Screenaudio uses 64/128/192 kbps ceilings with 128 default.diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex 1cc3d6f3..ff6d39de 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -189,7 +189,39 @@ A controlled production direct-P2P canvas run injected packet-loss pulses:All comparable arms had zero recovered pauses. The same loss rate produceddifferent presentation results, and the longest all-drop pulse crossed intoavailability recovery. This proves the shadow path, not an active threshold or-counterfactual parent quality. Quality-driven routing is parked in TODO.+counterfactual parent quality.++## Route-Selection Evidence Boundary++Current Viewer evidence cannot identify whether a poor result came from source+capture, an ancestor, the exact sender, the child decoder, or presentation. It+also cannot prove an unconnected path is better. A route decision therefore+needs exact sender evidence and real candidate media; combining current loss,+RTT, bitrate, FPS, resolution, and freezes into a score would not repair either+information gap. [ADR-0005](../adr/0005-automatic-hybrid-media-routing.md) owns+the accepted local-convergence algorithm.++W3C `qualityLimitationReason` is only the most limiting factor at one instant.+Its cumulative `qualityLimitationDurations` can prove a same-identity interval+spent in `none`, `bandwidth`, or `cpu`; missing or reset values remain unknown.+This supplies a categorical native edge state rather than an application score.+One report is still not a future guarantee, so a candidate must carry real media+while the working route remains and prove a complete healthy delta before+commit. Failure remains inconclusive without cutting the old route.++SFU has asymmetric evidence. The Browser publication proves shared Host-to-SFU+ingress, while exact SFU-to-Viewer sending and layer selection live inside+LiveKit. The accepted model therefore keeps SFU as a bounded suffix: LiveKit+owns its stream state and adaptation, and the exact Viewer proves continuing+decoded progress. The application does not manufacture a per-Viewer SFU sender+score or layer choice.++This structure follows libwebrtc's native limitation classification instead of+reimplementing congestion control. QUIC path validation supports retaining a+working path until a new one is proved, but its timers and congestion state are+not copied. Overcast and End System Multicast demonstrate gradual measured+overlay parent changes; their periodic probes, scalar metrics, published+percentages, and tuning loops are not adopted for this Browser product.## Open Evidence@@ -222,6 +254,9 @@ counterfactual parent quality. Quality-driven routing is parked in TODO.- [Screego VP9 regression](https://github.com/screego/server/pull/132)- [Media Capabilities](https://www.w3.org/TR/media-capabilities/)- [Chrome DevTools Protocol Network domain](https://chromedevtools.github.io/devtools-protocol/tot/Network/)+- [QUIC path validation and migration](https://www.rfc-editor.org/rfc/rfc9000.html#name-path-validation)+- [Overcast overlay parent selection](https://cs.brown.edu/~jj/papers/overcast-osdi00.pdf)+- [End System Multicast adaptation](https://static.usenix.org/events/usenix04/tech/general/full_papers/chu/chu_html/index.html)No implementation code was copied. LiveKit is Apache-2.0, libwebrtc uses itsBSD-style license, and Screego remains GPL research-only.diff --git a/docs/status.md b/docs/status.mdindex 070525ab..5c6ebb73 100644--- a/docs/status.md+++ b/docs/status.md@@ -69,8 +69,9 @@ This is the current execution index. Git history owns completed timelines;## Current Milestone-The documentation truth architecture is at its acceptance boundary. Product and-source implementation remain parked pending owner direction.+The native-edge local-convergence design is accepted at its truth boundary.+Current source and production remain on the evidence-only shadow;+implementation has not started.## Active Boundaries@@ -78,9 +79,9 @@ source implementation remain parked pending owner direction.screening did not reproduce a Host-page drop; accepted Viewer lifecycle workprevents frozen JavaScript wall time from becoming an immediate route failurebut is not capture keepalive.-- Current-path quality is diagnostic. High loss, RTT, jitter, low bitrate,- resolution, FPS, or freeze counters do not trigger relay abdication or parent- switching.+- Current-path quality is diagnostic in source and production. The accepted next+ slice is ADR-0005 native-edge local convergence; weighted/global optimization+ remains parked.- Repository simplification does not change or deploy product behavior beyonddeleting proven dead private surfaces.- Native/executable senders, shared encode, distribution packages, broad UI@@ -88,5 +89,5 @@ source implementation remain parked pending owner direction.## Current Hold-No source or deployment P0/P1 is open. Product evidence work is parked in TODO-while the truth and mechanism ownership is simplified.+No source or deployment P0/P1 is open. Native-edge convergence is the next+source task in TODO; broader product evidence remains parked.diff --git a/docs/todo.md b/docs/todo.mdindex 3c1c6f6f..764bfdb0 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -7,8 +7,10 @@ topics are not implementation authority.## Now-No product or source implementation is open after the documentation checkpoint.-Await owner direction.+1. **Native-edge topology convergence.** Implement ADR-0005's categorical+ `unknown | healthy | degraded` evidence, availability-first local moves, one+ serial candidate, and bounded Host-to-SFU suffix. Current production remains+ observation-only until focused route and Browser gates pass.## Parked Repository Work@@ -21,9 +23,10 @@ Await owner direction.## Parked Product Work-1. **Quality-driven route selection.** Strict v13 evidence remains diagnostic.- Any future decision must use the existing graph/operation and must not add a- score, all-pairs probe, periodic rebalancer, or ordinary SFU preference.+1. **Broader quality optimization.** Weighted/global optimization,+ parent-wide prediction, startup-limited inference, and alternative SFU+ policies remain unaccepted. Reopen only from exact path evidence; do not add+ a score, all-pairs probe, periodic rebalancer, or ordinary SFU preference.2. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari matrices forautoplay, background audio, foreground recovery, lock/page reclamation,rotation, network migration, and relay survival.