Skip to content

armgit / Piik

Public Imported from GitHub
0

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.md
index 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. Availability
repair may use one explicitly planned bounded-gap retirement after server
@@ -175,11 +177,55 @@ the committed graph, suppresses decoded-stall authority, and leaves new Viewers
waiting. Resume starts reconciliation from the current graph. Page-hidden wall
time 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 repair
may 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 Evidence
diff --git a/docs/adr/0007-path-isolated-representation-quality.md b/docs/adr/0007-path-isolated-representation-quality.md
index 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 uplink
capacity is insufficient; Screener does not silently remove constrained
Viewer 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-Viewer
encoder.
-- 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.md
index 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 the
Browser 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 lifecycle
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 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 through
an actual sender probe unless the Host explicitly selects VP8 or H264. Screen
audio uses 64/128/192 kbps ceilings with 128 default.
diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.md
index 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 produced
different presentation results, and the longest all-drop pulse crossed into
availability 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 its
BSD-style license, and Screego remains GPL research-only.
diff --git a/docs/status.md b/docs/status.md
index 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 work
prevents frozen JavaScript wall time from becoming an immediate route failure
but 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 beyond
deleting 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.md
index 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 for
autoplay, background audio, foreground recovery, lock/page reclamation,
rotation, network migration, and relay survival.