Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs(route): simplify controller reconciliation
AAAf99551518158
diff --git a/docs/README.md b/docs/README.mdindex b4079e35..ef3ea6cc 100644--- a/docs/README.md+++ b/docs/README.md@@ -12,18 +12,18 @@- [Peer-assisted media research](./research/peer-assisted-media.md): browser shared-encode limits, standard relay re-encoding, deterministic sticky topology, runtime relay-capacity extension, and abandon gates.- [Low-server-cost media routes](./research/low-server-media-routes.md): Host-publication/SFU distribution, selected-edge TURN, hop-level accounting, privacy-safe ICE evidence, and bounded transport gates.- [Built-in peer ICE TURN candidate](./research/built-in-peer-ice-turn.md): rejected canary record, retained standards/resource findings, and the selected-edge replacement boundary.-- [Advanced peer distribution](./research/advanced-peer-distribution.md): multi-tree/SVC, encoded-object relay, native RTP forwarding, FEC/network-coding, MoQ, and measurable go/no-go gates.+- [Advanced peer distribution](./research/advanced-peer-distribution.md): generic local-reconcile evidence plus multi-tree/SVC, encoded-object relay, native RTP forwarding, FEC/network-coding, and MoQ gates.- [Native shared-encode sender](./research/native-shared-encode-sender.md): consolidated Draft #16/#18/#22/#23/#25/#28 ladder, unclassified product-gate failure, staged revalidation, and stop line.- [Native H.264 hardware decision](./research/native-h264-hardware-decision.md): bounded WebCodecs no-go, proved Media Foundation/NVIDIA hardware encode, the default-fmtp `42c01f` stop, and the retained interop boundary.- [Native H.264 opt-in path](./research/native-h264-opt-in-path.md): explicit H.264 sender mode, exact Pion profile registration, and one bounded Host/Viewer loopback with hardware caveats.-- [Realtime quality adaptation](./research/realtime-quality-adaptation.md): correlated capture/send/receive diagnosis, production generation-rebuild gate, path-isolated dual representations, and bounded simulcast/Dynacast/SVC checks.+- [Realtime quality adaptation](./research/realtime-quality-adaptation.md): diagnostic-only capture/send/receive correlation, production generation-rebuild evidence, path-isolated dual representations, and bounded simulcast/Dynacast/SVC checks.- [Browser screen-audio quality](./research/browser-screen-audio-quality.md): capture/source compatibility, standard readback limits, Opus negotiation boundaries, and the retained no-control decision.- [Display name and presence boundaries](./research/display-name-presence.md): browser-local storage failure behavior, Unicode normalization, control-character policy, and the Web-only presence capability boundary.- [Agent context governance research](./research/agent-context-governance.md): official Codex, Claude Code, Hermes Agent, and GitHub practices adopted by this repository.- [ADR-0001](./adr/0001-p2p-first-media-topology.md): historical P2P-first baseline; later access and automatic-routing decisions supersede its stale current-state details.- [ADR-0002](./adr/0002-persistent-protected-rooms.md): site access, room-scoped private Viewer grants, explicit public-watch, rotation, and minimal SQLite persistence.- [ADR-0004](./adr/0004-peer-assisted-media-experiment.md): historical standard-WebRTC peer-assisted experiment and reusable evidence.-- [ADR-0005](./adr/0005-automatic-hybrid-media-routing.md): accepted automatic P2P-first route model, capacity/accounting, fallback roles, and generation safety; runtime migration and validation remain in the current TODO.+- [ADR-0005](./adr/0005-automatic-hybrid-media-routing.md): accepted automatic P2P-first single-reconcile route model, capacity/accounting, fallback roles, and exact first-frame transaction; runtime migration remains in the current TODO.- [ADR-0006](./adr/0006-fixed-high-native-sender-canary.md): proposed fixed-`HIGH` native canary, current no-go result, and staged revalidation boundary.- [ADR-0007](./adr/0007-demand-driven-dual-representation-quality.md): accepted path-isolated `HIGH + at most one LOW` policy, optional idle-layer stop, evidence contract, and SVC boundary.- [ADR-0008](./adr/0008-window-scoped-audio-capture.md): browser window-audio hint and the Windows WASAPI process-loopback boundary.diff --git a/docs/adr/0004-peer-assisted-media-experiment.md b/docs/adr/0004-peer-assisted-media-experiment.mdindex fa447e39..e71f2d8d 100644--- a/docs/adr/0004-peer-assisted-media-experiment.md+++ b/docs/adr/0004-peer-assisted-media-experiment.md@@ -54,8 +54,8 @@ The experiment established these durable facts:safety invariant;- route replacement must be bound to exact sessions, revision, sharegeneration, assignment generation, and connection identity;-- ICE `connected` is not media proof; positive RTP, decoded-frame progress, and- a live current-generation track are required before switching; and+- ICE `connected` is not application readiness; the exact candidate child's+ first newly decoded frame is required before switching; and- loopback tests can prove graph and signaling invariants but cannot establishreal-device encoding cost, target-network latency, or production capacity.diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex dd423db3..b5fcf5b8 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -30,8 +30,10 @@ capacity:- an upstream receive edge does not consume this downstream budget;- role, browser, user agent, device class, and page visibility do not create adifferent release tier;-- a client advertisement may reduce its usable capacity but cannot exceed the- deployment value; and+- a connected endpoint's server-authoritative effective downstream capacity is+ the deployment value clamped by its current `0..C` availability advertisement;+ `0` means it currently accepts no downstream child and does not create another+ release tier; and- one named configuration value and one shared implementation boundary own thepolicy. Route code must not repeat literal policy numbers.@@ -78,39 +80,62 @@ Direct or peer UDP remains the first media choice. Ordinary peernot distributed to ordinary peer edges by default. HTTPS and WSS continue touse TLS/TCP independently of media transport.-Routing is event-driven. Join, capacity release, endpoint departure, current-edge-failure, and accepted path-health evidence may open a bounded reassignment. The-controller does not continuously optimize the room, infer policy from a user-agent, or aggregate unrelated paths into a room-wide quality score.+Routing is event-driven. Join, capacity release or reduction, endpoint departure,+current-edge hard failure, and a non-paused decoded-frame stall wake the same+reconciliation loop. The controller otherwise leaves the room unchanged.Parent selection is deterministic and local. The controller first filters on-current authority, source reachability, acyclicity, depth, sender reservations,-relay eligibility, exact-edge exclusion/cooldown, and server admission. It then+current authority, source reachability, acyclicity, effective downstream+capacity, sender reservations, candidate tuples already tried by the current+operation, and server admission.+It thenorders eligible parents lexicographically by the shallowest resulting depth,the greatest remaining steady sender capacity, stable join order, and peeridentity. It prepares one candidate at a time. The candidate's standard ICE-checklist proves connectivity and current-generation RTP plus decoded frames-prove media; raw addresses, a claimed NAT class, geography, user agent, or a+checklist proves transport connectivity; the exact candidate child's first new+decoded video frame is the application media-ready event. Raw addresses, a+claimed NAT class, geography, user agent, or aweighted room-wide score never choose a parent. A failed candidate releases its-reservation before the next candidate is attempted. Join and hard-failure repair-accept the first candidate that reaches the media-usable floor; a soft-quality-move also needs the quality owner to prove recovery and improvement over the-still-healthy old edge.+reservation before the next candidate is attempted. The first candidate that+reaches the media-usable floor commits; otherwise the loop reaches the next+candidate, an explicit wait, or bounded failure.++There is no independent maximum-depth policy. Acyclicity and room admission+bound the graph, while shallowest-first ordering minimizes depth. Depth remains+an observed acceptance metric.++A candidate identity is one logical upstream plus one transport. For an invalid+ordinary child edge, the operation may create a fresh direct/STUN connection to+the same parent, another eligible peer parent, an admitted selected-TURN+transport, or an SFU subscription. All eligible direct/STUN tuples use+deterministic parent order before admitted selected-TURN tuples, followed by SFU+fallback. If the Host has no usable direct first-level peer path, the operation+prefers its single Host publication, using selected TURN for that ingress when+needed, rather than enumerating Host-TURN Viewer edges. The operation records+only exact tuples already tried; failure does not globally exclude that parent+from later room events.### Authorization and transition-Every prepare, signal, recovery, commit, and rollback is bound to the exact-room, share generation, endpoint sessions, route revision, assignment-generation, connection identity, media-binding generation, and publication-generation when one exists.+Every prepare, signal, recovery, commit, and rollback is bound to the+authenticated room and endpoint sessions, current share generation, base route+revision, and unique pending revision. Connection identity fences the candidate+PeerConnection, and publication generation remains owned by the SFU resource+lifecycle.+A single pending child-operation object aggregates these bindings, the+deterministic candidate list and cursor, its current candidate and reservations,+and one total operation deadline. Candidate failure advances the cursor without+resetting that deadline. These fields do not become separate gates or state+machines, and this route wave adds no+assignment, media-binding, or proof generation to the wire.A stale or mismatched asynchronous result fails closed and cannot revive an oldedge.A route replacement uses make-before-break only when the typed endpoint andserver-resource ledger atomically admits the required reservations. The old-route remains authoritative until the new route proves current-generation media-with a live track, positive RTP progress, and decoded-frame progress. ICE-`connected` alone is insufficient. Commit promotes that exact candidate+route remains authoritative until the exact candidate child decodes its first+new video frame. ICE `connected` alone is insufficient. Commit promotes that+exact candidateatomically; timeout, failure, stale identity, or revoked authority destroys it,releases reservations idempotently, and keeps or restores the previous validroute. When a full sender has no overlap slot, the controller may preconnect@@ -123,26 +148,28 @@ server fanout, or an untracked parallel route.## Accepted Assisted-Route Model-One room controller owns three operations: allocate/distribute, child reparent,-and relay abdicate/drain. It is the only owner of the committed graph, pending-target, and transition lifecycle. Topology helpers retain participant metadata-and purely plan candidates; they do not retain a second mutable route graph.-The operations share one target snapshot, one pending transition, one resource-ledger, and monotonic room/session/revision fences.-+One room controller owns the committed graph, one pending child operation, and one+event-driven reconciliation loop. Allocate/distribute, child reparent, and relay+abdicate/drain are inputs to that loop rather than separate state machines.+Topology helpers retain participant metadata and choose candidates without a+second mutable graph.++- The loop first removes disconnected childless participants, then selects one+ connected waiting Viewer or one child whose parent is disconnected,+ lacks effective capacity for that child, or owns the exact failed edge. It+ prepares one upstream change and wakes again after commit, abort, or another+ room event.+- A relay whose ingress fails is itself the child being reparented; its subtree+ remains attached. A disconnected endpoint, or one with effective downstream+ capacity `0`, accepts no new children. Direct or deterministic overflow children+ are reparented one at a time by the same loop, and disconnected leaves are+ removed naturally.- The Host is the only source publisher. There is at most one authoritative Hostpublication per share generation, and every SFU-fed Viewer subscribes to it.- An SFU-fed Viewer is not a committed relay parent merely because it advertises- capacity or proves its SFU ingress. The controller may reserve one formal- sender slot and prepare one exact provisional ordinary-child edge as the proof- transaction. Connected transport, a live video track, and positive current-- window RTP-receive and decoded-frame deltas at that child prove the outbound- path end to end; exact sender ownership and controller admission prove resource- and slot availability. Only atomic commit makes the Viewer relay-eligible.- Failure, timeout, stale authority, pause, or identity change destroys the- candidate and leaves the Viewer a leaf. Every later child still requires its- own exact media proof. Viewer republishing into a second SFU publication is- outside the current product.+ Any source-reachable endpoint with effective capacity may be a parent+ candidate; SFU-fed and peer-fed endpoints use the same provisional-child+ transaction and each child edge commits independently. Viewer republishing+ into a second SFU publication is outside the current product.- TURN is a selected transport for an existing authorized logical edge or theHost-to-SFU ingress. It is not a topology node, a second source, or a globalroom lease. Existing direct/STUN edges remain preferred; a failed selected@@ -156,45 +183,20 @@ ledger, and monotonic room/session/revision fences.`min(steadyCap + 1, 3)` only for one fenced, deadline-bound handoff and mustreturn to steady bounds at commit. There is no fixed SFU-root count orroom-wide selected-lease count.-- Every candidate carries exact room, share, endpoint sessions, route revision,- assignment/connection generations, publication generation when applicable,- and media-binding generation. Reserve, prepare, current-generation media- proof, atomic commit, drain, and idempotent release are one transaction.- TTL cleans abandoned reservations; it never revokes a healthy committed edge.-- A child that observes its own upstream as bad uses correlated C+B evidence- for that edge and invokes child-scoped reparent. If an exact current ordinary- peer edge stops current-generation RTP and decoded-frame progress while- signaling and the PeerConnection remain present, expiry of the bounded parent-- proof deadline authorizes hard reparent of that child if the stall remains,- whether matching positive non-server-parent outbound-media proof arrived or- not. Parent sending or non-response does not change parent eligibility.- Downstream evidence drains a relay only when the trigger has at least one- distinct current sibling edge and every current authoritative child edge has- independently completed a current-generation unusable proof. Positive- progress, unknown evidence, or unfinished proof on any current child blocks- that drain; positive progress clears the exact edge's unusable evidence. A- lone child is reparented without draining its parent. A relay parent enters- `suspect` for its own ingress evidence, stops accepting new children, and- repairs that ingress with reparent or branch-preserving `replaceIngress`.- Parent/session hard failure or failed ingress repair independently authorizes- drain. An endpoint-wide sender/resource failure independently authorizes drain- only when a concrete server-verifiable producer establishes that scope; a- generic per-edge failure remains edge-scoped. Host source failures instead use- publication repair and child migration. Drain retains a healthy ingress and- replaces or removes a failed ingress in the same target. If a new ingress- restores downstream media, the subtree remains unchanged. Hard failure- preempts confirmed parent drain, which preempts a single-edge soft reparent. A- feasible child migration is never blocked by a sibling with no destination.-- Unexpired evidence follows its exact edge identity across unrelated route- revisions and broadcasts; the controller advances its revision guard without- resetting unaffected siblings. Identity change, positive progress, or- successful migration clears only that edge's evidence. An authoritative pause- stops and clears current-generation quality correlation. Resume starts a fresh- baseline, so intentional pause silence cannot trigger reparent or drain.-- Healthy edges are sticky. Join, departure, capacity release, hard failure,- confirmed ineligibility, server-resource change, and explicit ingress restore- are the route-changing events. Quality evidence changes topology eligibility,- not built-in media layers and not a second route authority.+- Candidate-list creation, reserve, prepare, the child's first decoded frame,+ atomic commit, abort, and idempotent release are one bounded child operation.+ Its one total deadline cleans abandoned reservations and never revokes a+ healthy committed edge.+- A child invalidates only its own exact edge after PeerConnection hard failure+ or a named non-paused interval without a newly decoded frame. Bitrate, FPS,+ resolution, blur, and sender statistics remain diagnostics or stock+ WebRTC/LiveKit adaptation inputs; they do not change+ parent eligibility. Multiple bad child edges recover independently through the+ same loop and naturally empty an unusable relay.+- Authoritative pause aborts the pending child operation, including its current+ candidate and reservations, keeps the active graph, suppresses decoded-frame-+ stall decisions, and leaves new participants waiting. Resume wakes a fresh+ reconciliation. Healthy unaffected edges remain sticky.SFU and TURN remain bounded fallback resources with independent deployment-wideadmission. Resource exhaustion produces the next bounded candidate, an explicit@@ -247,7 +249,7 @@ deployment-wide.Production release `9461e20` predates this revision. Its exact behavior is ownedby the deployment document. Generation guards, scoped authorization,-media-proven transitions, and bounded recovery remain reusable only where they+first-decoded-frame transitions, and bounded recovery remain reusable only where theysatisfy this ADR.That release remains a deployment fact and rollback reference. It must not be@@ -262,8 +264,8 @@ Before a revised controller ships:- property tests cover capacity `1`, `2`, and `3`, one active upstream,acyclic and source-reachable assignments, stale generations, duplicatesignals, departure, rollback, and admission exhaustion;-- route changes preserve unaffected branches and never commit before media- proof;+- route changes preserve unaffected branches and never commit before the exact+ candidate child's first decoded-frame ready;- SFU lifecycle tests keep reserved, committed, and draining generations chargeduntil deletion plus absence proof, reject stale-token room recreation, prove acompeting listener owner makes no LiveKit call, fence startup against stale or@@ -271,19 +273,13 @@ Before a revised controller ships:without cutting a live Host participant, and keep two rooms under one globalcapacity owner;- candidate lists are deterministic under input permutation, preserve a healthy- current edge, prefer the shallowest least-loaded eligible parent, and try only- the next eligible candidate after exact failure and idempotent cleanup;-- quality tests distinguish child-scoped C+B reparent from parent-scoped drain;- require at least two current children and independently unusable proof on all- current child edges; prove that same-edge C+B, a healthy/unknown/unresolved- sibling, or a lone child cannot drain a parent; and cover independent- parent/session hard failure and failed-ingress-repair drain;-- quality tests bind evidence to exact media identity, preserve unaffected-edge- evidence across unrelated revisions, clear only changed or recovered edges,- suspend and clear correlation during authoritative pause, and start a fresh- baseline on resume. They include a Viewer that is both child and parent, the- Host-source publication-repair exception, bounded child-only recovery while- signaling remains present, and suspect/local-repair before drain;+ current edge, prefer the shallowest least-loaded parent with capacity, and+ advance one cursor after exact failure and idempotent cleanup without resetting+ the total operation deadline;+- focused controller tests cover first-frame commit, candidate failure and stale+ ready, relay-ingress reparent with its subtree intact, disconnected relay and+ nested-disconnect convergence, effective capacity `0..C` and overflow drain,+ SFU-fed first-child use, selected TURN on the same edge, and pause/resume;- real-browser tests cover direct peer media, peer relay, server-assisted media,selected transport when configured, failure, and recovery;- deployment preflight proves the LiveKit instance is dedicated, uses@@ -335,8 +331,8 @@ Negative:- ADR-0001 owns the original browser P2P baseline.- ADR-0004 is historical evidence about browser peer relay and re-encoding; itdoes not set current capacity or server-assisted policy.-- ADR-0007 owns path-quality evidence and representation behavior. Quality may- affect route eligibility but does not become a second route controller.+- ADR-0007 owns diagnostic path-quality evidence and representation behavior;+ it does not create route eligibility.## Referencesdiff --git a/docs/adr/0007-demand-driven-dual-representation-quality.md b/docs/adr/0007-demand-driven-dual-representation-quality.mdindex b7fd744c..b1f05147 100644--- a/docs/adr/0007-demand-driven-dual-representation-quality.md+++ b/docs/adr/0007-demand-driven-dual-representation-quality.md@@ -29,13 +29,10 @@ Use path-isolated dual representations:publishes one shared `HIGH+LOW` pair and lets LiveKit BWE independentlychoose and recover the forwarded layer for each subscriber. If that gatepasses, Screener does not add a media-layer selector.-3. Correlated sender/viewer evidence and asymmetric windows classify topology- eligibility and diagnostics only. An observed downshift is `suspect`; a- confirmed `FALLBACK` relay parent cannot remain a parent. The edge-versus-- parent scope, same-edge C+B handling, local repair, and drain actions are- owned by ADR-0005's `EdgeHealth`/`RelayEligibility` controller; this ADR- does not turn representation evidence into a second topology authority or- command ordinary built-in layer changes.+3. Sender/viewer evidence diagnoses capture, encode, transport, receive, and+ decode behavior. It does not change topology or command ordinary built-in+ layer changes. ADR-0005 reacts only to an exact child edge's hard connection+ failure or non-paused decoded-frame stall.4. Explicit subscriber quality or sender layer activation is considered onlyif the built-in candidate fails its bounded gate. Deactivating an unused`LOW` is a resource optimization, not an acceptance requirement.@@ -54,12 +51,9 @@ cannot reliably provide the one shared `LOW`, either always-on or on demand,fails quality acceptance; optimize its encode path or markthat cohort unsupported. Never protect a weak path by reducing `HIGH`.-The durable topology states use explicit predicates and asymmetric-entry/recovery windows; `suspect` is the sampling interval before a transition,-not a third media mode. There is no weighted score, device ranking,-machine-learning controller, custom media selector, or continuous room-wide-optimizer. Exact thresholds remain implementation inputs until the controlled-quality matrix establishes them.+There is no weighted score, device ranking, machine-learning controller, custom+media selector, or continuous room-wide optimizer. Representation evidence does+not create route states.The topology and representation budgets are independent invariants. Eachnon-server endpoint follows ADR-0005 steady outbound media-copy capacity `C`@@ -69,25 +63,16 @@ encoded packets without decoding or re-encoding. Future dual-tree or stripeddelivery may reduce host upload from about two full copies toward one copy plusnecessary redundancy, but it does not block this decision.-The application must not stably retain a confirmed `FALLBACK` relay parent as a-parent. A later planned or explicit `LOW` fallback is leaf-only: complete a-generation-guarded child evacuation before changing its quality, and preserve-the prior assignment and quality if evacuation fails or becomes stale. An SFU-may make an unannounced congestion-protection downshift before the application-can react. Treat that observation as `suspect`, not confirmed `FALLBACK`; the-representation evidence may contribute to the bounded topology evidence, but-ADR-0005 decides whether it is an edge-local reparent or a relay-parent-cordon/repair/drain. C+B from one edge alone never proves parent-wide failure;-parent drain requires the independent-edge or hard-failure conditions in-ADR-0005. This cannot promise packet-level preemption, so the root-with--children gate must bound temporary descendant impact before default enablement.-Re-advertising relay capacity still needs the longer recovery window and a-cooldown. A viewer's advisory request cannot trigger this sequence by itself.+LiveKit may downshift an SFU subscription before the application observes it.+That is normal per-subscriber adaptation and does not alter relay eligibility.+If the exact ingress later hard-fails or stops decoding while unpaused,+ADR-0005 reparents that Viewer as a child and retains its subtree. A viewer's+advisory quality request cannot trigger route mutation by itself.## Evidence Contract-Before enabling quality-aware topology changes, correlate the same time-interval and stream generation across three stages:+For diagnosis and representation acceptance, correlate the same time interval+and stream generation across three stages:| Stage | Required evidence || --- | --- |@@ -111,25 +96,18 @@ field, stream/stat ID change, or counter reset. Missing values remain unknown;they are not zeros.Implementation is staged. First correlate A and B locally in one sampling tick,-with an explicit interval, media/stat identity, and valid deltas. Only after-that probe is trustworthy may the product add a minimal authenticated C report-for the few receive/decode signals required by the topology predicate. The B/C-correlation uses normalized fields derived from negotiated parameters/stats and-actual decode behavior; it must never upload raw SDP, raw stats, candidate-addresses, or raw device/network identifiers. Opaque server-issued path and-connection-generation IDs remain required for authorization and correlation,-and the evidence carries ADR-0005's exact route identity: room/share-generation, both endpoint sessions, assignment/connection generation,-media-binding generation, route revision, and publication generation when-applicable.+with an explicit interval, media/stat identity, and valid deltas. A minimal+authenticated C report may add receive/decode diagnosis after that probe is+trustworthy. The B/C correlation uses normalized fields derived from negotiated+parameters/stats and actual decode behavior; it must never upload raw SDP, raw+stats, candidate addresses, or raw device/network identifiers. Opaque+server-issued path and connection IDs authorize diagnostic correlation only.Do not build a general telemetry schema.A viewer may request `LOW`, but the request is advisory. It must be carried onan authenticated, current room/path session and be rate-limited and deduplicated.-The topology classifier accepts it only when viewer receive/decode behavior and-derived negotiated codec/profile/parameters (including applicable-`scalabilityMode`) agree with sender transport/GCC and encode evidence. A-request alone cannot lower quality or start a representation.+It may be shown with matching sender/viewer diagnosis, but it cannot lower+quality, start a representation, or change topology.UA, platform, and device-model detection does not participate in quality orrelay-capacity selection. Browser capability queries can guide a bounded probe,@@ -141,8 +119,7 @@ Inspect standard capabilities in order and stop at the first accepted pathbefore custom dual-representation media. Static API or pinned-protocolincompatibilities can close a candidate without a browser run; runtime mediagates start only after the A+B/C evidence contract is trustworthy. These-results do not create an application media-layer selector; the asymmetric-evidence windows remain limited to topology eligibility and diagnostics:+results do not create an application media-layer selector or route authority:1. **Web P2P simulcast: rejected(`no-go-web-p2p-simulcast-layer-selection`).** WebRTC exposes@@ -180,12 +157,8 @@ evidence windows remain limited to topology eligibility and diagnostics:Screener'ssubscriber does not attach a `RemoteTrack`, so LiveKit `adaptiveStream` is notdirectly usable without changing that ownership; it is not required for the- SFU bandwidth-adaptation candidate. Before default enablement, a separate- root-with-children gate must inject an autonomous downshift and observe it as- suspect. ADR-0005 then chooses local repair, edge-local reparent, or- RelayEligibility parent drain; only that drain branch evacuates children and- limits temporary descendant impact. No confirmed `FALLBACK` root may retain- children. If built-in selection+ SFU bandwidth-adaptation candidate. A root with children uses the same+ built-in BWE; an automatic downshift does not mutate topology. If built-in selectionfails the product gates, test explicit standard subscriber quality selectionbefore sender activation/deactivation. The gate must prove that a healthyP2P/`HIGH` path is unchanged, no third layer appears, the expected layer is@@ -199,8 +172,8 @@ evidence windows remain limited to topology eligibility and diagnostics:prevents the pinned multi-codec path from enabling it automatically.The 2026-08-22 executable preflight verifies this configuration, retains azero-child subscriber, and rejects excess central roots. Per-subscriber BWE,- actual layer forwarding, hardware cost, and root-with-children behavior- remain unverified, so no runtime performance claim follows. If the always-on+ actual layer forwarding for leaves and relay roots, and hardware cost remain+ unverified, so no runtime performance claim follows. If the always-oncost fails, test manual standard sender activation/deactivation next;custom/native dual encoding follows only if built-in and manual standardprimitives fail.@@ -264,7 +237,7 @@ Positive:subscriber; its idle deactivation is allowed but not required. Physicalencoder instances and resource cost remain measured outcomes.- Encode cost is bounded independently of viewer count.-- The topology classifier and its evidence remain inspectable.+- The diagnostic evidence remains inspectable.Negative:@@ -288,7 +261,7 @@ Negative:- Do not start or retain `LOW` when its measured hardware, game, or upload costviolates budget.- Do not add a composite health score or media selector when built-in adaptation- plus topology predicates suffice.+ and ADR-0005 edge recovery suffice.## Verification Gates@@ -302,13 +275,9 @@ Negative:- Representation count never exceeds two. Host and relay endpoint media copiesfollow ADR-0005 steady capacity `C`; the two-edge result is only the boundedexperiment configuration.-- A later planned/explicit `LOW` fallback evacuates children first and preserves the- prior state on stale/failed evacuation. An autonomous BWE downshift enters- `suspect`; ADR-0005's bounded edge/parent evidence then chooses local repair,- child reparent, or parent drain, and no confirmed `FALLBACK` relay parent- retains downstream capacity. The root-with-children gate measures temporary- descendant impact before default enablement.-- Relay capacity returns only after the longer stable recovery plus cooldown.+- Built-in BWE downshift and recovery remain local to each SFU subscription and+ do not change topology. Exact ingress failure is handled only by ADR-0005's+ generic child reparent operation.- An unavailable/over-budget `LOW` fails visibly for weak paths while healthypaths and `HIGH` remain unchanged.- Every supported sender cohort can reliably provide the one shared `LOW`,diff --git a/docs/deployment.md b/docs/deployment.mdindex fd0bf5a2..24772bca 100644--- a/docs/deployment.md+++ b/docs/deployment.md@@ -129,11 +129,11 @@ instance, and its tracked configuration sets `room.auto_create: false`.The accepted target for `share.bonfire.icu` remains distributed and automatic:direct/peer UDP first, with one Host publication available to authorized SFU-subscriptions when a logical edge cannot use peer transport. An SFU-fed Viewer-may continue as a peer relay only after independent outbound proof; strict-fallback Viewers remain leaves. Server-assisted subscriptions and allocations-use independent deployment admission rather than an endpoint-cap or fixed-root-rule.+subscriptions when a logical edge cannot use peer transport. SFU-fed and+peer-fed endpoints use the same provisional-child transaction, and the exact+candidate child's first newly decoded frame commits that edge. Server-assisted+subscriptions and allocations use independent deployment admission rather than+an endpoint-cap or fixed-root rule.The repository requires STUN and ordinary peer connections receive STUN-onlyICE. An existing logical edge prefers direct/peer UDP and may use exact selecteddiff --git a/docs/project-memory.md b/docs/project-memory.mdindex 547b0cca..73cbf524 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -9,9 +9,9 @@ Last updated: 2026-08-23- Web is the current delivery target. Viewers join from desktop or mobile browsers; a packaged or native sender is a later optimization.- Keep routing automatic and media distributed. Direct/peer UDP is preferred; centralized media is fallback infrastructure, not the default topology.- Every non-server endpoint uses one server-authoritative steady outbound media-copy capacity: default `2`, statically configurable as `1`, `2`, or `3`. A peer child or the Host publication consumes one slot; upstream receive is free, selected TURN replaces the same copy's transport, and SFU subscriber egress is accounted at the server. Browser role/UA/visibility does not create a separate tier, and clients cannot raise the deployment value.-- The stable routing invariants are one authoritative upstream per Viewer, an acyclic active graph, exact room/session/share/revision/generation authorization, media-proven make-before-break, and bounded success or failure.-- The accepted route model is one room controller with allocate/distribute, child reparent, and relay abdicate/drain operations. The controller is the only committed and pending graph owner; topology helpers hold participant metadata and plan candidates without restoring another mutable baseline. One Host publication may serve all SFU-fed Viewers. An SFU-fed Viewer stays a leaf until one controller-owned formal provisional child edge proves connected transport, live video, and positive current-window RTP receive and decode under exact sender-slot admission; only atomic commit makes it a relay parent, and every later child proves its own edge. Selected TURN changes an authorized edge transport and is not a topology node. A confirmed bad edge, or an exact ordinary peer edge whose current-generation receive/decode progress remains absent through a bounded parent-proof challenge, reparents only that child regardless of whether the parent proved sending. Downstream evidence drains a relay only when every current authoritative child edge independently remains unusable and at least one different sibling edge corroborates the trigger; positive progress, unknown evidence, or an unfinished proof on any current child blocks that drain. A lone child is reparented without draining its parent. A relay parent's own ingress failure first enters suspect/cordon and attempts local repair; only failed repair, independently corroborated downstream failure, a parent/session hard failure, or server-verifiable endpoint-wide sender/resource failure drains its children. Generic edge failure is not endpoint-wide evidence. Host source failures use publication repair and child migration. Endpoint capacity, temporary overlap, SFU/TURN admission, exact fallback, media binding generations, and rollback are one bounded transaction model.-- Parent choice is sticky and deterministic: hard-filter current authority, reachability, cycles, depth, capacity, eligibility, exact-edge cooldown, and server admission; then order by shallowest result, remaining steady sender capacity, stable join order, and peer identity. Standard ICE and exact media proof test one candidate at a time. Raw IP, claimed NAT type, UA, geography, all-pairs probes, weighted scores, and periodic room rebalancing are not route inputs.+- The stable routing invariants are one authoritative upstream per Viewer, an acyclic source-reachable active graph, exact authenticated route attempts, endpoint and server admission, one room-serial child operation, and bounded success, wait, or failure.+- One room controller reconciles allocation, child reparenting, and relay drain through the same operation. It finds one waiting Viewer or invalid edge and builds one deterministic candidate list. The operation owns its cursor, current candidate and reservations, plus one total deadline; only its current candidate may produce media. A usable old edge remains until the exact candidate child decodes its first new video frame. That event commits; failure advances the cursor, while total deadline or exhaustion ends in wait or failure. A relay with a bad ingress reparents itself as a child and retains its subtree. A disconnected endpoint, or one whose effective downstream capacity falls below its current child count, accepts no excess children; its direct or overflow children enter the same operation and a disconnected endpoint is removed when childless. Authoritative pause aborts the operation, suppresses stall decisions, and resumes from a fresh reconciliation.+- One Host publication may serve all SFU subscriptions. SFU-fed and peer-fed endpoints use the same provisional-child transaction, and selected TURN changes only the transport of an authorized logical edge. Parent choice hard-filters authority, reachability, cycles, effective capacity, and server admission, then orders by shallowest result, remaining steady sender capacity, stable join order, and peer identity. Acyclicity and room admission bound maximum depth; depth is observed but has no separate hard cap. Raw IP, claimed NAT type, UA, geography, all-pairs probes, weighted scores, and periodic room rebalancing are not route inputs.- Ordinary peer ICE is STUN-only. Credentials, room secrets, candidate details, and diagnostic data remain private and narrowly scoped.- Screen audio offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The existing last-wins quality wire owns desired state; each endpoint serially applies and reads back current Host/relay/SFU audio senders, exposes local failures, and gives future senders the latest desired value. Opus remains fixed, and without an applied-ack wire the Host does not claim room-wide atomic convergence. These are configuration ceilings, not fidelity claims.- Video codec selection remains `automatic | H.264 | VP8`. The accepted first switching boundary is a generation-fenced renegotiation/republish transaction while sharing is explicitly paused; unpaused hot switching is later reuse of that transaction, not an independent mechanism.@@ -22,7 +22,7 @@ Last updated: 2026-08-23## Current Source And Production- Canonical source is the clean `main` branch. New branches and worktrees start from its exact current commit after accepted truth is merged.-- Current source implements the uniform `1/2/3` endpoint cap through one shared accounting guard, advances Web/server/Native to `screener-v6`, rejects v5 before room authority, and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted assignments, and sender slots use the same authority. SFU-fed Viewers remain leaves without outbound proof. SFU admission uses explicit no-default ingress/egress capacities, exact `reserved | committed | draining` lifecycle accounting, and a listener-fenced dedicated LiveKit owner. Selected TURN uses its own explicit no-default deployment capacity and exact logical-allocation ledger shared by independent peer edges and Host-SFU ingress.+- Current source implements the uniform `1/2/3` endpoint cap through one shared accounting guard, advances Web/server/Native to `screener-v6`, rejects v5 before room authority, and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted assignments, and sender slots use the same authority. Its current SFU-fed-leaf and route-quality behavior predates the accepted generic reconciliation model. SFU admission uses explicit no-default ingress/egress capacities, exact `reserved | committed | draining` lifecycle accounting, and a listener-fenced dedicated LiveKit owner. Selected TURN uses its own explicit no-default deployment capacity and exact logical-allocation ledger shared by independent peer edges and Host-SFU ingress.- Production runs exact `9461e207af62b4f38f6b7a8aa16f8beb49e0e4ee`, release `9461e20`, wire `screener-v5`; `21d5cd9f7139` is the rollback release.- Production still enforces Host downstream `2`, ordinary Browser downstream `1`, deployment values `1/2`, a fixed SFU-root limit of `2`, and legacy publication/selected accounting. This is a dated implementation divergence, not current product policy.- Production has automatic routing, bad-relay corroboration, peer-quality make-before-break with Viewer and Host provisional parents, selected-edge transport, stable route/connection details, 64/128/256 audio choices, access controls, self-check, diagnostic export, and signaling watchdog behavior.diff --git a/docs/research/advanced-peer-distribution.md b/docs/research/advanced-peer-distribution.mdindex fe937dee..45443c91 100644--- a/docs/research/advanced-peer-distribution.md+++ b/docs/research/advanced-peer-distribution.md@@ -1,12 +1,12 @@# Advanced Peer Distribution-- Research date: 2026-08-21+- Research date: 2026-08-23- Scope: at most eight trusted viewers, sub-second interactive media, endpointdownstream fanout at most two, and minimal central-server media egress-- Status: bounded C+B local reparenting and admission rescue are deployed;- one-root healthy SFU reselection is deployed but browser/media/production-route- evidence is unverified; relay-capacity `0 -> 1`, multi-root reselection, and- advanced encoded-media routes remain unimplemented candidates+- Status: deterministic peer distribution and provisional make-before-break are+ retained evidence; current routing converges through ADR-0005's single+ child-reparent reconciliation, while advanced encoded-media routes remain+ unimplemented candidatesThis document is research evidence, not current architecture or a backlog. See[ADR-0005](../adr/0005-automatic-hybrid-media-routing.md) for accepted routing@@ -41,10 +41,10 @@ overhead. Protocol headers, retransmission, and TURN overhead are additional.| Native full-stream RTP relay | at most `2B` | zero except TURN edges | relay zero encode; native host can share one encode || Two encoded-object stripe trees | about `(1+r)B` | zero except TURN edges | host one encode; relay zero encode || Host publication with bounded SFU subscriptions | measured `B_pub` | per-subscriber egress; see low-server model | one publication may carry at most two active representations; physical encoder count remains measured evidence |-| Full central SFU/MoQ fanout | about `B` | ingress `B`, egress `N*B` | comparison class, not the accepted fallback shape |+| Full central SFU/MoQ fanout | about `B` | ingress `B`, egress `N*B` | a possible bounded fallback result, never the default topology or mode |Useful last-hop traffic remains approximately `N*B`; these routes only decide-which nodes emit the copies. Exact `B_pub`/`B_i`, root, TURN-hop, and billing+which nodes emit the copies. Exact publication/subscription, TURN-hop, and billingaccounting is owned by [Low-Server-Cost Media Routes](./low-server-media-routes.md).TURN is edge transport; it is not a peer/SFU topology.@@ -174,7 +174,7 @@ is isolated behind a small adapter.## Candidate 6: Bounded Capability-Aware Local Reparenting-This remains a bounded topology candidate outside ADR-0004. Narada and Overcast+This is the research basis for ADR-0005's bounded local reconciliation. Narada and Overcastdemonstrate measurement-driven overlay improvement, but neither supplies amaintained WebRTC RTP/RTCP routing library. BitTorrent/WebTorrent and P2P MediaLoader use chunk-pull swarms and@@ -183,176 +183,47 @@ Their exploration and hysteresis ideas are useful, but none is a drop-in routecontroller for sub-second screen sharing. A mature SFU is the directly reusablelow-latency alternative, with central egress rather than audience forwarding.-The first quality-driven slice reuses the authenticated Viewer C window and-existing route intent, plus one strict parent-to-server B message. Signaling-binds C to room, Viewer session, connection ID, active revision, parent-peer/session, sequence, two-second rate and 2 KiB size, then forwards the same-sanitized object. The current parent answers that exact sequence within five-seconds only when its current outbound sample has a positive `packetsSent`-delta. The existing discriminated proof is `sending` for diagnostic liveness,-`sender-limited` only for an exact `qualityLimitationReason` of `cpu` or-`bandwidth`, or `remote-loss` when that interval has at least 100 sent packets-and RTCP-reported remote loss divided by sent packets is at least 30%; it never-carries a null placeholder. One current connection cannot reuse the same-`sampleTimestampMs` for multiple C sequences; fractional stats windows are-rounded before applying the protocol bounds. The-server accepts one B from the bound parent session and generation. The router-may retain C while awaiting B, but advances only when B is hard and C is either-severe or relatively degraded. The relative case exists only below a Viewer-relay: the relay's own latest correlated C must still match its session, active-route and connection and be at most five seconds old; the child must receive-less than two-thirds of that actual inbound FPS. The configured FPS ceiling is-not evidence. `sending`, either report alone, and healthy or ambiguous pairs-reset or do not advance the streak.-It holds at most one pending/streak state per connected Viewer and one room-cooldown, with no timer or weighted score. One confirmed child event stays-edge-local. Corroboration from two distinct current children can affect relay-parent eligibility only when the configured ordinary capacity makes that state-reachable; it does not define the capacity policy.--The accepted controller target also handles an exact ordinary peer edge whose-signaling and PeerConnection remain present while current-generation RTP and-decoded-frame progress stop. If the stall remains when the bounded parent-proof-deadline expires, only that child enters hard reparent whether matching positive-non-server-parent outbound-media proof arrived or not. Parent sending and parent-non-response are both edge-local here; parent cordon/drain still requires a hard-endpoint failure, explicit sender/resource failure, failed ingress repair, or-independent downstream evidence.--The conservative Viewer C hard predicates are: freeze duration at least half-of the one-to-five-second window; positive received-packet delta with zero-decoded frames; or at least 100 received-plus-lost packets with loss at least-30%. Parent B must independently report the exact `cpu`/`bandwidth` sender-limitation or at least 100 sent packets with remote loss divided by sent packets-at least 30%. Three consecutive windows of the same severe or relative kind are-required. A healthy or incomplete correlated window, any Viewer/parent session,-connection, route revision or parent change, or a gap over five seconds clears-the streak. Severe and relative-FPS quality evidence each tries one parent through-make-before-break: either a Viewer whose active upstream is peer/SFU or the Host.-Session/share/revision plus one strict ordinary-capacity reservation are required-before breadth-first selection continues. No candidate, probe failure, or timeout keeps-the old edge without SFU, TURN, or an error. A started attempt spends a-30-second room migration-budget, so a new public Viewer identity cannot bypass it. Per-edge state clears-on authentication/generation change, disconnect/removal and route replacement;-room stop/delete also clears the cooldown.--The candidate is bound to the exact Viewer/parent sessions, active and pending-route revisions, share lifecycle and a separate connection ID. Its parent owns-one provisional child PC outside the active child map and never auto-retries it-with another connection ID. Signaling keeps-the old connection ID authoritative until the Viewer proves positive RTP,-positive decoded-frame progress and a live video track on the candidate; commit-then promotes that same PC and changes topology, route and active connection-identity together. Failure after ready retains the exact provisional identity-across repeated matching active updates; the candidate parent stays fail-closed-and the target Viewer probe owns recovery. Rollback or another edge's-authoritative failure clears or aborts the soft probe before using the ordinary-ladder. A-successful relative move holds the old parent for 30 seconds or until its-session changes. A real active-route failure remains a separate hard recovery-trigger and can reuse an otherwise playable old parent.--W3C defines outbound `packetsSent` as the local cumulative RTP packet count.-`remote-inbound-rtp.packetsLost` is remote receiver data delivered by RTCP and-the corresponding stats object does not exist until that RTCP first arrives;-absence is therefore not zero. W3C's video-only `qualityLimitationReason` stays-an exact local sender predicate rather than an encoder score. Parent B and-Viewer C are gathered by stock browsers at separate endpoints, but RTCP remote-loss is receiver-originated and neither report is cryptographically independent-or resistant to colluding authenticated participants. W3C also defines-Viewer-side-`packetsReceived`, `packetsLost`, `framesDecoded`, `freezeCount` and-`totalFreezesDuration`; its WebRTC 1.0 diagnostic example treats loss over 30%-as a likely culprit. It does not define route-migration thresholds. The 50%-freeze share, two-thirds FPS ratio, 100-packet floor, three windows,-five-second gap and 30-second-cooldown are falsifiable candidate constants for production calibration, not-standards-derived or claimed optimum values.--One correlated pair still attributes a problem only to its current-parent-to-child edge generation: remote loss comes from that child and-`qualityLimitationReason` belongs to one outbound stream. Two independently-confirmed current children may provide bounded corroboration for that relay-parent, but do not prove device-wide quality or create a numeric score. Existing-children keep their old edge when no authorized alternate exists. The triggering-child uses media-proven make-before-break, and current Viewer/SFU-upstream and-Host provisional-parent paths preserve the candidate connection identity.+This product has too few children per relay to infer parent-wide quality from a+small set of sibling samples. Mature outlier detection requires materially more+independent hosts and request volume before statistical ejection; route policy+therefore does not use sender/viewer correlation, sibling voting, relative FPS,+or a room score. Those metrics remain diagnostic.++The application consumes only an exact child edge's hard connection failure or+a non-paused interval with no newly decoded frame. That child enters ADR-0005's+single reconciliation loop. If the child is itself a relay, changing its ingress+retains its subtree. If several downstream edges fail, each child reparents+independently and the old relay naturally empties. WebRTC and LiveKit retain+transport connectivity, consent, congestion control, reconnection, and SFU+stream-state ownership.++Every upstream change uses one bounded transaction. The candidate is bound to+the authenticated endpoint sessions, share generation, base and pending route+revisions, and candidate connection. A usable old edge stays authoritative until+the candidate child decodes its first new video frame. That single event already+proves the candidate's ICE/DTLS/RTP/decode path; failure or deadline expiry+releases the candidate and wakes the same loop for the next choice.For `N` Viewers a peer tree still has `N` media edges and approximately `N*B`useful upload in aggregate. Local reparenting redistributes that traffic; it does-not eliminate it. Reordering a healthy tree therefore needs a discrete current-benefit rather than a continuous optimizer.--The source admission-rescue slice is limited to its discrete capacity case. If-a relay-capable viewer is unassigned because two zero-capacity roots occupy-both host slots, it inserts that viewer above-one deterministic childless root:--```text-host -> new relay -> existing leaf-host -> other root-```--At the exact release that introduced this rescue, the move kept Host fanout at-two and Browser Viewer fanout at one. The router permits it only on an active peer-only route with no SFU-publication or pending prepare, when the connected candidate currently has no-upstream or children, offers relay capacity, and has no failed-parent-history. The host must have exactly two children and the chosen child must be a-connected, childless, zero-capacity leaf. Existing server join order chooses the-oldest eligible leaf. One synchronous topology snapshot changes the host,-candidate, and leaf; one route revision replaces both upstream generations and-clears their old connection IDs. The Host reconciler closes every stale child-edge before starting replacement children, so its physical fanout does not-temporarily exceed two.--Eligibility remains discrete: an active authenticated session, explicit relay-capacity, compatible representation, a free downstream slot, acyclicity, and-depth/edge budgets. The implemented rescue never moves a candidate that already-has an upstream, never handles a failed-path intent, and never selects a root by-quality. An authenticated viewer can still lie about its relay capacity, so the-exact-room canary and ordinary route-failure recovery remain required; the lie-can cause at most this one local move before the candidate is no longer-unassigned. Broader experiments may react to a hard media failure, a reviewed-threshold-crossing event from correlated path evidence, or a proven native-capacity change, but never a continuous optimizer. Standard ICE already owns-candidate-pair priority, pruning, connectivity checks, peer-reflexive discovery,-and nomination inside one `RTCPeerConnection`; the application should not build-a second ping mesh. Route selection first applies exact authority, reachability,-acyclicity, depth, sender-slot, eligibility, exclusion/cooldown, and server-admission filters, then uses a small lexicographic order: shallowest resulting-tree, most remaining steady sender slots, stable join order, and peer identity.-Only the selected provisional edge receives real connectivity and media proof;-failure releases it before the next candidate. Do not use a weighted score,-UA/device model, IP geography, claimed NAT type, or one party's unverified-report. Keep healthy assignments sticky, move only one affected subtree, use-separate enter and recovery thresholds plus a cooldown, and disable proactive-moves for the share after repeated rollback.--Use make-before-break only when the new parent has a free ordinary downstream-slot under the server-authoritative configured cap. A provisional child reserves-that slot until commit or rollback. Admission rescue-starts with both host slots occupied, so it is break-before-make: retire the-chosen host-to-leaf media edge before activating host-to-new-relay media. A-control-only `RTCPeerConnection` may prewarm ICE but cannot prove media uplink:-WebRTC exposes `availableOutgoingBitrate` only after congestion-controlled RTP-has used that candidate pair. Zero interruption, active standby media, and a-hard endpoint edge limit cannot all be guaranteed at once.--Any calibration study must retain configured fanout limits at every sampled-instant; unaffected branches-must not freeze; make-before-break must decode at every affected receiver on the-new path before retiring the old edge, while break-before-make must do so within-one second p95 after the break and before declaring the move successful. Stable-reference runs must not migrate; each move must record one discrete benefit,-avoid reversal during cooldown, and restore the prior deterministic route on-rollback. Reject this candidate if it needs all-pairs probing, a continuous-optimizer, temporary fanout above budget, self-reported geography or device-quality, or cannot beat the unchanged route. The earlier admission-rescue case-remains valid. The implemented quality slice moves only the affected-Viewer-rooted subtree, keeps its old edge until the candidate decodes, and does-not enter SFU or selected-edge TURN. Those transports remain available only to-the separate real-failure route owner.+not eliminate it. The controller therefore keeps a healthy tree sticky and only+handles waiting or invalid edges.++Candidate inputs remain discrete: an active authenticated session,+effective capacity with a free downstream slot, acyclicity, source reachability,+and server admission. Standard ICE owns candidate-pair+priority, pruning, connectivity checks, peer-reflexive discovery, and nomination+inside one `RTCPeerConnection`; the application does not build another ping mesh.++The controller orders eligible parents by shallowest resulting tree, remaining+steady sender slots, stable join order, and peer identity. It keeps healthy+assignments sticky and changes only one child upstream per room transaction. A+provisional child reserves the required endpoint and server resources until+commit or abort. If an old edge is usable, make-before-break retains it until the+candidate child decodes; a hard-invalid edge uses the same transaction without+pretending the old media still works. No weighted score, UA/device model, IP+geography, claimed NAT type, cooldown optimizer, or role-specific rescue path is+part of selection.## Staged Connection Recovery Evidence@@ -368,17 +239,14 @@ mismatches before a full reconnect. Jitsi Videobridge similarly defaults to areference boundaries, not universal prescriptions. Screener's separately owned15-second initial deadline remains a candidate pending mobile-network evidence.-The peer-local repair phase is bounded: show progress while initial ICE still-advances, attempt one ICE restart on hard failure, and rebuild the same logical-edge at most once under current transport authority. If that edge remains-unusable, emit one exact failed-edge event to the ADR-0005 controller. The-controller may reparent the child, authorize selected TURN for an exact edge, or-choose a Host-publication SFU ingress under current capacity and server-admission; these are not a fixed global retry ladder. Each success cancels the-remaining work. Every completion is guarded by the current session, route-revision, assignment/connection generation, and cooldown. Connected-but-bad-media is a separate correlated-quality trigger and must not be treated as a-connection retry.+WebRTC/LiveKit first owns transient reconnect. A hard failure or non-paused+decoded-frame stall wakes ADR-0005 once. The same room transaction may try a+fresh connection to the same parent, another parent, exact selected TURN, or a+Host-publication SFU subscription as ordinary bounded candidates under current+capacity and server admission. There is no separate same-edge repair ladder.+Every completion is guarded by the current authenticated sessions, share+generation, pending route revision, and candidate connection. Sustained bitrate,+FPS, resolution, and blur remain diagnostic.The first room-1 production trace on 2026-08-20 observed two short Hostparticipants while two roots remained for roughly 4.6 seconds; all ended with@@ -404,30 +272,21 @@ above; passing their own gates may change capability, but does not insert theminto the current route model.The SFU uses one authoritative Host publication and exact per-Viewer-subscriptions. SFU-fed Viewers may retain bounded peer descendants when their-outbound relay eligibility is independently proven. Server ingress/egress and+subscriptions. SFU-fed and peer-fed endpoints use the same provisional-child+first-frame transaction. Server ingress/egress andTURN allocations use deployment-wide admission rather than a fixed root countor room-wide lease. The SFU/UDP and optional selected-edge TURN accounting lives in[Low-Server-Cost Media Routes](./low-server-media-routes.md). ADR-0005 owns the-accepted target; the current source still contains legacy controller slices and-the one-root healthy-reselection behavior described below. None changes the sticky-local reparenting candidate above.--The controller must be automatic and invisible. It uses explicit capability-bits, route revisions, media generations, edge budgets, and discrete failures;-it does not expose topology choices to host or viewers. Initial hard triggers-are capacity, maximum depth, ICE/media failure, unsupported codec, and bounded-send-queue overflow. Measurements may later justify additional triggers.--For healthy SFU-to-peer reselection, W3C inbound RTP counters expose the needed-bounded observations: `packetsReceived` counts received RTP packets and-`framesDecoded` counts successfully decoded video frames. Neither ICE state nor-a track object alone proves decodable progress. Pinned LiveKit client 2.22.0-already exposes reconnecting/reconnected room events, so recovery is a discrete-trigger; no network-type poll or new timer is required. The current source arms-the same two-window gate when a refreshed signaling session receives an-authoritative sticky SFU assignment. This avoids immediately reversing an-ordinary peer-to-SFU fallback, whose initial authenticated assignment was peer.+accepted behavior.++The controller is automatic and invisible. It uses participant metadata, route+revisions, endpoint capacity, server admission, and discrete exact-edge failure;+it exposes no topology choices. One reconcile loop handles join, waiting,+disconnect, effective-capacity overflow, and failed edges. W3C+`framesDecoded` counts successfully decoded video frames, so the first new+candidate frame is the only application readiness event. LiveKit owns SFU+reconnection and stream state; the application adds no network-type poll or+SFU-specific timer.The overlap edge is physical: an active Host SFU publication consumes one steadysender slot, and a media-producing provisional peer candidate consumes another.@@ -436,12 +295,12 @@ Browser tier. A free steady slot permits ordinary make-before-break; otherwise asingle fenced `TransitionOverlapSlot` may raise the physical count only to`min(C + 1, 3)`. A full `C=3` endpoint must wait, use a bounded-gap transition,or fail before creating a fourth copy. Failed or stale probes restore the prior-controller revision and release their reservation without writing ordinary-failed-parent state.+controller revision and release their reservation before reconciliation+continues.## Sources And License Boundary-Sources checked on 2026-08-20, 2026-08-21, and 2026-08-22:+Sources checked on 2026-08-20 through 2026-08-23:- [WebRTC SVC](https://www.w3.org/TR/webrtc-svc/),[Encoded Transform](https://www.w3.org/TR/webrtc-encoded-transform/),@@ -458,9 +317,12 @@ Sources checked on 2026-08-20, 2026-08-21, and 2026-08-22:[room defaults](https://github.com/livekit/client-sdk-js/blob/v2.22.0/src/room/defaults.ts),and [state reconciliation](https://github.com/livekit/client-sdk-js/blob/v2.22.0/src/room/Room.ts)- pinned implementation behavior, not a universal timeout prescription.-- [Kubernetes cordon/drain](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands)- - operational analogy for stopping new children before bounded evacuation;- no scheduler or disruption framework is copied.+- [Kubernetes controllers](https://kubernetes.io/docs/concepts/architecture/controller/)+ - event-driven desired/current reconciliation reference; no scheduler or+ disruption framework is copied.+- [Envoy outlier detection](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/outlier_detection.proto)+ - statistical host ejection defaults require at least five hosts and material+ request volume, unlike Screener's one-to-three child sample.- [LiveKit server 1.13.5 participant quality aggregation](https://github.com/livekit/livekit/blob/v1.13.5/pkg/rtc/participant.go)and [connection scorer](https://github.com/livekit/livekit/blob/v1.13.5/pkg/sfu/connectionquality/scorer.go)- Apache-2.0; studied only, with no source copied.diff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.mdindex 1b796517..d88b2ef3 100644--- a/docs/research/low-server-media-routes.md+++ b/docs/research/low-server-media-routes.md@@ -72,50 +72,41 @@ select the current resource model.## Traffic Conservation And The Impossible TriangleThis is an engineering accounting identity, not a named theorem. Let `B` be-the measured useful media bitrate for one same-representation branch, `B_pub`-the actual SFU publication bitrate, `B_i` server-fed subscriber `i`'s selected-bitrate, `N` the Viewer count, `R` the number of server-fed subscribers, and `D`-their peer descendants. Thus `N = R + D` for this screening model. For the-equal-representation baseline,-useful last-hop delivery is approximately `N*B`. Ignoring protocol overhead:+the measured useful media bitrate for one same-representation edge, `B_pub` the+actual SFU publication bitrate, `N` the Viewer count, `P` the number of Viewer+upstreams carried by peer edges, and `S` the number carried by SFU subscriptions.+Thus `N = P + S`. Split peer edges by sender: `H` are Host-to-Viewer and `V` are+Viewer-to-Viewer, so `P = H + V`. Useful last-hop delivery is approximately+`N*B`. Ignoring protocol overhead:`host last-hop copies + peer last-hop copies + server last-hop copies = N * B`| Full-stream shape | Host upload | Viewer-relay upload | Central media traffic || --- | ---: | ---: | ---: |-| Peer roots, direct edges | `R*B` | `D*B` | none |-| Peer roots, all `R` seed edges through TURN | `R*B` | `D*B` | TURN ingress `R*B` + egress `R*B` |-| SFU virtual parent to the same relay seeds | `B_pub` | `D*B` | SFU ingress `B_pub` + egress `sum(B_i)` |-| Same-representation full-room SFU | `B` | `0` | SFU ingress `B` + egress `N*B` |--The table's `R*B` and `D*B` rows are equal-representation screening cases with-`E=0`.-With mixed root representations, direct peer-root traffic is `sum(B_i)` and-descendant upload is `sum(B_edge)`. SFU host upload and ingress are `B_pub`, the-sum of all actively published representations; if simulcast `HIGH` and `LOW`-both remain active, that may be `B_HIGH+B_LOW`, not one root bitrate. The-SFU-fed relay-seed row, not full-room SFU, is the retained fallback shape. For equal-representations, `B_pub = B` and `sum(B_i) = R*B`. Publisher-to-SFU and every-SFU-to-seed subscriber transport are independent ICE connections and may use a-separately deployed LiveKit transport. Ordinary descendants are STUN-only;-selected coturn is issued only for an exact authorized edge or Host-SFU ingress.+| Peer-only, `S=0` | `H*B` | `V*B` | none |+| Mixed peer/SFU, `S>0` | `H*B + B_pub` | `V*B` | SFU ingress `B_pub` + egress `sum(B_s)` |+| Same-representation full-room SFU, `S=N` | `B` | `0` | SFU ingress `B` + egress `N*B` |++For mixed representations, replace `H*B` and `V*B` with the sums of their+actual peer-edge bitrates, and use each SFU subscription's selected `B_s`. SFU+host upload and ingress are `B_pub`, the sum of all actively published+representations; if simulcast `HIGH` and `LOW` both remain active, that may be+`B_HIGH+B_LOW`. Publisher-to-SFU and every SFU subscription are independent ICE+connections. Whether a subscribed endpoint also sends peer edges is represented+only by its actual committed children and those edges are already counted in+`V`. Ordinary peer edges are STUN-only; selected coturn is issued only for an+exact authorized edge or Host-SFU ingress.If apublisher leg separately uses LiveKit TURN, retain host upload`B_pub`, TURN ingress `B_pub`, TURN egress `B_pub`, and SFU ingress `B_pub` as-distinct interface/service traffic. A relayed root leg likewise adds TURN-ingress and egress `B_i`; a selected-edge relay adds both directions for that-edge's actual bitrate. They are one logical useful payload copy but real-physical hops, so NIC, service, and billing counters must never be folded.--If `E>0`, SFU relay-seed/exception egress is-`sum(B_i) + sum(B_exc,j)` and central SFU traffic is-`B_pub + sum(B_i) + sum(B_exc,j)`. Peer descendant upload remains-`sum(B_edge)`. Any separately TURN-relayed LiveKit subscription or-controller-selected peer edge adds TURN ingress and egress equal to that leg's-measured bitrate. Server-fed subscriptions are never hidden inside endpoint-child capacity or the equal-representation formulas. Their ingress, egress and-TURN allocations are admitted explicitly; `R` is a measured scenario variable,-not a fixed product root limit.+distinct interface/service traffic. Any separately TURN-relayed LiveKit+subscription or controller-selected peer edge adds TURN ingress and egress equal+to that leg's measured bitrate. These are one logical useful payload copy but+real physical hops, so NIC, service, and billing counters must never be folded.+SFU+subscriptions are never hidden inside endpoint child capacity. Their ingress,+egress, and TURN allocations are admitted explicitly; `S` is a measured route+result, not a fixed root limit.RTP/RTCP/SRTP, DTLS, ICE/TURN and IP headers, retransmission, FEC, and redundantpaths only add traffic. W3C candidate-pair byte counters exclude some transport@@ -192,7 +183,7 @@ change or explicit reconnect; it does not support periodic probing, a carrier- Acceptance: owned desktop, Wi-Fi, and cellular probes select an IPv6 P2P pathand an IPv6 SFU/selected-TURN path where available; broken IPv6 still reachesthe IPv4 ladder within the current route deadline. Retain only an `ipv4|ipv6`- enum with the existing opaque generation and media proof, never a raw address.+ enum with the exact candidate first-frame transaction, never a raw address.- Stop line: if any required public media endpoint has no routed IPv6, record thedeployment as incomplete and keep the IPv4 ladder. Do not build a custom IPv6selector or claim NAT bypass from an `AAAA` record alone.@@ -218,30 +209,16 @@ change or explicit reconnect; it does not support periodic probing, a carrierdependent mappers. Do not add a third server or a NAT classifier without ameasured failure that the second server fixes.-**3. Healthy SFU-to-P2P bounded re-probe**--- Historical checkpoint: production `27ad90d` had the first deployed one-root slice: it- reserves bounded capacity, keeps the healthy SFU route playing, proves one- fresh P2P generation with current decoded-media progress, then commits- atomically and closes the old route. Source `4c9174d` additionally- retains one cooldown-time opportunity as a current tuple and requires two new- evidence windows at expiry. Later production deployed that bounded continuation- and subsequent peer-quality MBB work. Exact current capacity, SFU, TURN, and- accounting semantics remain unaccepted pending the holistic route model. None- of these generations polls network state.-- Retained candidate: a discrete network-change or explicit-reconnect event may- open one opportunity through that same controller after cooldown. It must not- create a second route controller or treat an ICE restart on the SFU- `RTCPeerConnection` as P2P discovery.-- Acceptance: an owned viewer that fell back to SFU changes Wi-Fi/cellular,- receives one bounded fresh probe, and moves to P2P without playback loss or- duplicate active edges. A failed probe leaves the healthy SFU route unchanged;- stale answers or repeated browser events cannot start another generation or- leak capacity.-- Stop line: no polling loop and no periodic probing. If one discrete probe- causes SFU playback regression, overlapping offers, cap violation, or route- churn, keep the healthy SFU route and fix the generation/commit boundary before- another rollout.+**3. SFU-to-P2P recovery**++- WebRTC/LiveKit first owns network change and reconnect. Only an exact hard+ failure or non-paused decoded-frame stall wakes the room reconciliation used+ for every child.+- The existing SFU edge remains active when usable. One P2P candidate receives+ standard ICE checks and commits only after its child decodes the first new+ frame; failure releases it and preserves SFU.+- No polling loop, periodic probing, or second route controller+ is authorized. Capacity and server admission use ADR-0005.### Isolated Bounded Guessed-Candidate Spike@@ -302,7 +279,7 @@ not authorize a guessed production path.after a connectivity check succeeds. RFC 8863's recommended 39.5-second PACtimer is an ICE-agent failure boundary, not a JavaScript tuning API. Do notextend Screener's current route deadline to 40 seconds; measure late recovery- behind a playing SFU route through the bounded re-probe instead.+ behind a playing SFU route through an isolated measurement instead.- The April 2026 ICE-renomination draft requires opt-in from both ICE agents andthe W3C `RTCConfiguration` exposes no renomination switch. Historicallibwebrtc native code has a disabled-by-default flag for an older renomination@@ -470,19 +447,19 @@ as wide as the CPU count for performance. Embedded TURN/UDP defaults to 3478.The current nginx template has no HTTP/3 listener, but that fact alone does notprove one UDP port is the best production layout.-For one equal representation of measured bitrate `B` and `R` roots:+For `K` equal-representation first-level deliveries that cannot use direct media:-- `R` TURN seed edges: host upload `R*B`, server ingress `R*B`, server egress- `R*B`, total central traffic `2R*B`;-- one SFU publisher to `R` roots: host upload `B`, server ingress `B`, server- egress `R*B`, total central traffic `(R+1)*B`.+- `K` individual Host-to-Viewer selected-TURN edges: host upload `K*B`, server+ ingress `K*B`, server egress `K*B`, total central traffic `2K*B`;+- one Host publication with `K` SFU subscriptions: host upload `B`, server+ ingress `B`, server egress `K*B`, total central traffic `(K+1)*B`.-At `R=1` useful-payload traffic is equal, so the identity alone gives neither+At `K=1` useful-payload traffic is equal, so the identity alone gives neitherroute a preference; CPU and allocation cost require the same-host benchmark.-At `R=2`, the equal-representation SFU case halves host upload and+At `K=2`, the equal-representation SFU case halves host upload andcentral ingress and reduces total central traffic from `4B` to `3B`, with thesame `2B` egress. Mixed representations replace `B` with measured `B_pub` and-`sum(B_i)`; a HIGH+LOW publication may erase that advantage. Public LiveKit+`sum(B_s)`; a HIGH+LOW publication may erase that advantage. Public LiveKitbenchmarks and the Jitsi profiling breakdown establish capacity and componentcategories only. Different machines and implementations cannot support auniversal coturn/SFU CPU ratio or a claimed fixed percentage saving.diff --git a/docs/research/native-shared-encode-sender.md b/docs/research/native-shared-encode-sender.mdindex a1a0bc79..190a3007 100644--- a/docs/research/native-shared-encode-sender.md+++ b/docs/research/native-shared-encode-sender.md@@ -257,8 +257,8 @@ room-wide minimum controller.ADR-0007 keeps stock WebRTC GCC per direct/peer path. Each SFU path starts witha `HIGH` ceiling and built-in BWE selects from one shared `HIGH+LOW` pair. App-evidence affects topology eligibility and diagnostics, not ordinary layer-selection. `LOW` may already be active, and idle stop depends on the resource+evidence is diagnostic and does not select routes or ordinary layers. `LOW` may+already be active, and idle stop depends on the resourcegate. The active representation/layer limit is two, never one per viewer; thethe host follows the configured non-server outbound media-copy capacity; thetwo-edge result in this experiment is a historical configuration, not a fixed@@ -269,21 +269,18 @@ measured encoder/CPU/GPU game or upload load is unacceptable, `LOW` fails closedfor weak paths while healthy paths keep `HIGH`. `LOW` may remain active whenthat measured budget passes; stopping it while idle is an optimization.-The app's `HIGH`/`FALLBACK` states and asymmetric windows only classify topology-eligibility, not media layers, and do not form a composite score. Viewer-requests are authenticated, rate-limited, deduplicated advice and need sender-transport/encode plus viewer receive/decode corroboration. UA and device-identity do not participate.+The app does not derive topology eligibility from representation state. Viewer+quality requests are authenticated, rate-limited, deduplicated diagnostic advice+and do not form a composite score. UA and device identity do not participate.A native relay forwards the selected encoded packets and must not decode orre-encode them. An ordinary non-scalable representation cannot be forwardedinto a second quality; the bounded choices are a second encode, SVC, ortranscoding. ADR-0007 statically closes current Web P2P simulcast andWeb/LiveKit SVC as cross-path shortcuts, but keeps pinned LiveKit exactly-two-simulcast with built-in SFU bandwidth adaptation on zero-descendant leaves as-the priority runtime candidate. A root-with-children downshift/evacuation gate-must pass before default enablement. Explicit subscriber quality is next if-built-in selection fails; manual sender activation follows if always-on cost+simulcast with built-in SFU bandwidth adaptation as the priority runtime+candidate. SFU BWE does not change topology. Explicit subscriber quality is next+if built-in selection fails; manual sender activation follows if always-on costfails; custom/native dual encode is last. A future native SVC decision mayreopen only with an explicit hardware encoder contract, at most two decodablelayers, one encodeddiff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.mdindex f1b17d63..e2b9d643 100644--- a/docs/research/peer-assisted-media.md+++ b/docs/research/peer-assisted-media.md@@ -287,21 +287,15 @@ its affected descendant and resumed advancing frames in 5,380 ms while the Hostremained within two media edges. The requested synthetic source was 1280x720 at30 fps, but observed final samples remained 320x180 at roughly 9-11 fps. This isreal local `RTCPeerConnection` media and hard-participant-departure evidence. It-does not exercise correlated bad-quality detection or provisional MBB, a silent+does not exercise decoded-frame-stall recovery or provisional MBB, a silentsocket partition, SFU, TURN, a public network, game capture, or resource quality.A 2026-08-22 opt-in `BENCHMARK_CANARY=viewer-mbb` run on the same Chrome build-used one Host and three Viewers. The harness injected three valid two-second-viewer-quality windows and parent-limited proof messages through the existing-authenticated socket, then observed the real provisional `RTCPeerConnection`-retain the old edge, promote to a Viewer candidate, and keep the same connection-identity while decoded frames advanced. It also checked the ordinary one-edge-cap and absence of route-failed messages. The report contains only booleans and-sanitized counters; it emits no participant IDs, SDP, or ICE candidates. The-windows are synthetic control input, so this proves the state-transition and-continuity path only, not bad-relay detector quality, network performance, or a-real heterogeneous route. Host-candidate and signaling-response-blackhole-canaries remain deferred.+used one Host and three Viewers. It observed a real provisional+`RTCPeerConnection` retain the old edge, promote the candidate, preserve the+connection identity, and continue decoded-frame progress within the ordinary+edge cap. This is reusable make-before-break control evidence only; its+synthetic trigger is not route policy or heterogeneous-network evidence.A 2026-08-21 local Chrome 151 capacity-two run used one Host and five Viewerswith a synthetic 720p30 stream. Host and relay fanout peaked at two; one Viewerdiff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex c939d672..f1f7a249 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -57,8 +57,8 @@ hypothesis, not a conclusion. A further report that quality may remain lowafter the old viewer leaves and a new viewer joins must likewise be testedagainst lifecycle evidence rather than assumed.-Use this as the first A+B/C reproduction before quality-aware topology-classification or dual-layer publication:+Use this as the first A+B/C reproduction before any route change or dual-layer+publication:1. Reproduce one wired LAN/direct viewer first, then Wi-Fi, two/three viewers,and forced TURN, using the same high-motion scene for 60 to 90 seconds.@@ -76,9 +76,9 @@ classification or dual-layer publication:A single-edge rebuild passes only if the affected viewer recovers, unaffectedviewers neither migrate nor interrupt, and the host-edge cap holds. Only proven-generation-specific failure can justify a later automatic one-edge recovery-with sustained-bandwidth and healthy-counterpart evidence, cooldown, and a-generation guard. Do not add periodic reconnect, blindly raise a ceiling, or+generation-specific hard failure or non-paused decoded-frame stall can justify+automatic one-edge recovery under the current route attempt. Do not add+periodic reconnect, blindly raise a ceiling, orchange the current routing behavior before this gate.Missing `scaleResolutionDownBy` is not itself a root cause for a single encoding@@ -377,7 +377,7 @@ one unambiguous encoding. Current quality settings do not request a mode, sothe requested value remains null and a browser-reported default is not calleda mismatch; multiple encodings remain unknown. Inbound stats provide no currentstandard `scalabilityMode` source, so C does not carry a null-only placeholder.-The topology classifier and shared `HIGH+LOW` publication remain unimplemented,+The shared `HIGH+LOW` publication remains unimplemented,and browser support remains subject to the controlled matrix. Physicallystopping an unused `LOW` is a resource optimization rather than a prerequisite.@@ -414,11 +414,10 @@ passes, Screener does not add a media-layer selector. The hard activerepresentation/layer limit is two, never one per viewer, and stopping idle`LOW` remains optional.-Correlated sender/viewer evidence and asymmetric entry/recovery windows classify-topology eligibility and diagnostics only. An observed BWE downshift is-`suspect`; sustained evidence confirms `FALLBACK`, removes parent capacity, and-longer recovery plus cooldown can restore that capacity. These application-states do not command ordinary built-in layer changes.+Sender/viewer evidence diagnoses capture, encode, transport, receive, and decode+behavior. It does not classify topology eligibility. An observed BWE downshift+is ordinary per-subscriber adaptation and does not command route or media-layer+changes.`LOW` itself is conditional: if no qualified hardware/power-efficient mediapath exists or the additional representation exceeds the measured@@ -435,17 +434,10 @@ remains protected in either case.A viewer's `LOW` request is advisory and must be authenticated, session-bound,rate-limited, deduplicated, and corroborated by sender transport/encode andviewer receive/decode stats. UA or device-model detection is not quality or-relay-capacity evidence. A valid report may affect confirmed topology eligibility; it does not-command built-in WebRTC/LiveKit media adaptation.--The application must not stably retain a confirmed `FALLBACK` parent. For a-later planned or explicit quality fallback it evacuates children under the current generation-before setting `LOW`, preserving the prior state on failure. Built-in SFU BWE-can downshift before application evidence exists; record that as `suspect`, then-evacuate and set capacity zero only after bounded correlated confirmation. The-system cannot promise packet-level preemption of that congestion response, so a-root-with-children gate must measure and bound temporary descendant impact-before default enablement.+relay-capacity evidence. A valid report does not change topology or command+built-in WebRTC/LiveKit media adaptation. Built-in SFU BWE may downshift and+recover a subscription without any Screener route action; only the exact+ingress's hard failure or non-paused decoded-frame stall wakes ADR-0005.An ordinary non-scalable stream cannot yield a second independent quality bypacket forwarding alone. The alternatives are a second representation,@@ -480,17 +472,15 @@ a product no-go. The Firefox branch's 4x scale, 10 bps, and non-standardlayer; it does not invalidate the always-on two-layer candidate.The next runtime gate must publish exactly `HIGH+LOW` with standard-simulcast/send encodings, leave each zero-descendant SFU leaf's ceiling at-`HIGH`, and first test built-in per-subscriber SFU bandwidth adaptation and+simulcast/send encodings, leave each SFU subscription's ceiling at `HIGH`, and+test built-in per-subscriber SFU bandwidth adaptation andrecovery. Start with Dynacast off for a deterministic always-on measurement;pinned cumulativeDynacast-on is another always-on form, not a third representation. Prove thereceived layer, the two-layer ceiling, unchanged healthy P2P/`HIGH`, andhardware encoder, game FPS/p1 low, CPU/GPU, interval encode cost, upload, and-per-layer byte budgets. Before default enablement, a separate root-with-children-gate must inject an autonomous downshift, observe `suspect`, evacuate after-bounded confirmation, and limit temporary descendant impact; no confirmed-`FALLBACK` root may retain children. Screener's current publisher always+per-layer byte budgets for both leaves and relay roots. An autonomous downshift+does not evacuate children or alter route state. Screener's current publisher alwaysconfigures exactly two ordered `q`/`h` encodings whenever an SFU publication isactive, explicitly constructs `Room({ dynacast: false })`, disables backup-codecpublication, and its subscriber sets a `HIGH` ceiling after selectively@@ -527,8 +517,8 @@ This preflight does not start LiveKit 1.13.5, a browser, or a network shaper. Ittherefore does not prove packet receipt/forwarding, autonomous BWE downshift andrecovery, actual `LOW`/`HIGH` dimensions, per-layer bytes, encoder count, CPU/GPU,game frame time, or upload cost. Those remain acceptance requirements for the-isolated zero-descendant run below; root-with-children behavior remains a later-default-on gate.+isolated run below; relay-root behavior remains resource and quality evidence,+not a route gate.### Per-Flow Shaping Preflight@@ -774,8 +764,7 @@ oscillates or makes the wrong tradeoff on supported machines, revise thatexplicit option before enabling ADR-0007. Its acceptance matrix must prove that built-inLiveKit BWE independently moves one shaped SFU leaf to the shared `LOW` and backwhile a healthy leaf remains `HIGH`, without an application media selector. The-application's asymmetric evidence windows must affect only confirmed topology-eligibility and diagnostics. Each supported sender cohort must provide `LOW`+application's evidence windows remain diagnostic only. Each supported sender cohort must provide `LOW`within measured hardware, game, and upload budgets; idle-layer resource releaseis a separate optimization.diff --git a/docs/status.md b/docs/status.mdindex 78e35fb9..2afcf5ca 100644--- a/docs/status.md+++ b/docs/status.md@@ -15,16 +15,16 @@ This is the current execution index. Git history owns completed timelines; [veri- Canonical source is the clean `main` branch; auxiliary branches and worktrees do not own current truth.- Current source implements one steady outbound media-copy cap for every non-server endpoint: default `2`, static `1/2/3`, a peer child or Host publication consumes one slot, upstream receive is free, a committed selected TURN transport replaces the same copy while hidden carry consumes another, and no Browser/UA/visibility tier exists. One shared guard owns the accounting and transition work is bounded by `min(C + 1, 3)`.-- The v6 release boundary rejects v5 before room authority and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted child assignments, and sender slots share the server authority. It leaves an SFU-fed Viewer childless without independent outbound proof and keeps quality events child-scoped without a fixed two-child parent drain.+- The v6 release boundary rejects v5 before room authority and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted child assignments, and sender slots share the server authority. Current `main` still carries the legacy childless-SFU-fed and route-quality slices that the pending generic reconciliation replaces.- Current source also implements explicit no-default SFU ingress/egress capacities and exact `reserved | committed | draining` accounting. The listener owner reconciles its dedicated non-auto-create LiveKit namespace before serving, creates each generation before token issuance, releases only after delete-plus-absence proof, and reclaims Host-offline generations through bounded exact-participant checks. Selected TURN has an independent explicit no-default deployment capacity; one process-local ledger charges every exact peer-selected edge and Host-SFU ingress through reserve, commit, drain, and release.-- Automatic P2P-first routing, one active upstream, an acyclic graph, exact identity/generation authority, media-proven make-before-break, and bounded failure remain accepted.-- The holistic assisted-route model is accepted: one controller performs allocation, child reparenting, and relay abdication/drain. One Host publication serves SFU subscriptions; TURN is an exact edge transport, not a topology node. Controller convergence includes one formally admitted provisional child proof before an SFU-fed Viewer can atomically become a relay parent; advertisement or ingress readiness alone leaves it a leaf, and every later child proves its own edge. Endpoint accounting, the wire boundary, SFU lifecycle, and TURN admission are implemented; controller convergence remains pending.-- Parent selection is deterministic rather than random or score-based: hard eligibility filters, then shallowest result, remaining sender capacity, stable join order, and peer identity; one provisional edge uses standard ICE and media proof at a time. Viewer connection feedback and the strict-NAT emulator gate are accepted follow-up work, not deployed behavior.+- Automatic P2P-first routing, one active upstream, an acyclic source-reachable graph, exact attempt authority, first-decoded-frame make-before-break, and bounded failure remain accepted.+- The accepted controller has one event-driven reconciliation loop and at most one room-serial child operation. That object owns one deterministic candidate list/cursor, one current media candidate, its reservations, and one total deadline. Join, exact-edge failure, relay disconnect, and effective-capacity reduction all enqueue that operation. A relay repairs its own ingress as a child while retaining its subtree; excess direct children use the same operation before a disconnected childless relay is removed. One Host publication serves SFU subscriptions, SFU-fed endpoints use the ordinary provisional-child path, and TURN changes edge transport rather than topology. Endpoint accounting, the wire boundary, SFU lifecycle, and TURN admission are implemented; this controller convergence remains pending.+- Parent selection is deterministic rather than random or score-based: hard eligibility filters, then shallowest result, remaining sender capacity, stable join order, and peer identity. The exact candidate child's first new decoded frame is the only application media-ready event. Moderate bitrate, FPS, or visual degradation remains with stock WebRTC/LiveKit adaptation and diagnostics; only hard connection failure or a non-paused decoded-frame stall invalidates a route edge. Viewer connection feedback and the strict-NAT emulator gate are accepted follow-up work, not deployed behavior.- Live 64/128/256 audio-ceiling mutation and paused-share video codec switching are accepted but not yet implemented on canonical `main`. H.264 startup blur/low-FPS reports remain an evidence-led diagnosis, not a presumed codec defect. Public-server and fully local distribution packages are later work after the functional, NAT, and real-network ledger is complete.## Current Milestone-1. Complete and release the remaining route-controller convergence with deterministic local parent selection and quality ownership.+1. Complete and release the generic route reconciliation loop with deterministic parent selection and one first-frame candidate transaction.2. Release live audio-ceiling mutation and paused-share codec switching on the resulting generation/transition boundary.3. Reproduce the H.264 startup report before any codec-specific repair, and build the strict-NAT emulator gate before any manually approved canary in an operator-owned test room.4. Add first-frame-driven Viewer connection stages and finish the remaining accepted functional and real-network work.@@ -39,7 +39,7 @@ This is the current execution index. Git history owns completed timelines; [veri## Next Stop-Implement the controller-convergence wave from this source. The route release+Implement the minimal controller-convergence wave from the accepted truth checkpoint. The route releasestill requires measured TURN and SFU capacities, adedicated LiveKit instance with the documented private control-plane contract,and the focused real-network and Native `C=1/2/3` acceptance matrix.diff --git a/docs/todo.md b/docs/todo.mdindex d25ecb1a..5d558460 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -6,15 +6,15 @@ Only items in **Now** are executable after their stated decision gate. A branch## Now-1. **Route Wave D: controller convergence.** Make the room controller the only committed/pending graph owner and keep topology helpers to participant metadata plus pure candidate planning. A signaling-connected ordinary peer edge whose current-generation RTP and decode progress remain absent through the bounded parent-proof deadline hard-reparents only that child whether the parent proves sending or stays silent. Downstream-only relay drain requires at least one different current sibling edge and independently confirmed unusable evidence on every current authoritative child; any positive, unknown, paused, or unfinished current-child evidence blocks the drain, while a lone child only reparents. Parent/session hard failure and failed own-ingress repair remain independent drain triggers. Treat endpoint-wide sender/resource failure as held until a concrete server-verifiable producer exists; generic per-edge `route-failed` is not that producer. Carry unchanged exact-edge evidence across unrelated route revisions, clear only changed/stale bindings, and suspend correlation during authoritative pause. Parent candidates use hard filters followed by deterministic shallowest, remaining-capacity, join-order, and peer-identity ordering; standard ICE plus exact media proof tests one candidate at a time. Close the SFU-fed relay bootstrap with one controller-owned formal provisional child edge: capacity advertisement and SFU ingress do not authorize relay, while exact sender-slot admission plus child-side connected/live/positive RTP receive and decode proof permits only the atomic committed parent; every later child still proves its own edge. Do not add raw-IP/NAT ranking, all-pairs probes, a weighted score, UA/visibility tiers, periodic rebalancing, or a second graph/controller.+1. **Route Wave D: one reconciliation loop.** Make the room controller the only committed graph owner and keep topology helpers to participant metadata plus pure deterministic candidate planning. Join, a hard-failed or non-paused decoded-frame-stalled edge, relay disconnect, and effective-capacity reduction all enqueue the same room-serial child operation. That one object owns a deterministic candidate list/cursor, one current candidate and its reservations, and one total deadline. Retain a usable old edge and commit only after the exact candidate child decodes its first new video frame; candidate failure advances the cursor, while operation exhaustion or deadline reaches explicit wait or failure. A relay with a bad ingress reparents itself and retains its subtree. Excess children use the same operation, and a disconnected endpoint is removed when childless. SFU-fed and peer-fed parents use this same first-child path; one Host publication serves all SFU subscriptions, and TURN changes only authorized edge transport. Authoritative pause aborts the operation and suppresses stall decisions until resume. Keep routing event-driven and edge-local; do not add proactive scoring, probing, rebalancing, or another graph/controller.2. **Switch screen-audio ceilings live.** Keep Opus fixed and serialize 64/128/256 kbps desired profile updates across every current Host, relay, and SFU audio sender. Each endpoint uses fresh `getParameters()`/`setParameters()` readback, ignores stale completions, retains media plus its prior applied value on failure, and applies the latest desired value to future edges. Do not add a remote applied-ack protocol or claim room-wide atomic convergence in this slice.3. **Switch video codec while paused.** After the route/media-generation boundary is available, serialize the change with route mutation, freeze exact current route/media bindings, hold new joins, renegotiate P2P/relay and republish SFU while paused, then verify actual codec plus decoded frames on resume. A binding invalidated by leave or hard route failure exits this proof set and waits for routing to rebuild from the final committed preference after the bounded codec transaction settles. On failure pause again and perform bounded rollback; rollback proves the prior preference was reapplied plus a newly negotiated actual codec and decoded progress, not literal equality with the old actual codec. Zero targets update only the future-edge preference. Reset `automatic` with empty codec preferences. This is a paused bounded-gap transaction; unpaused make-before-break is a later extension.4. **Diagnose the production H.264/blur report.** Reproduce exact release `769de201f7cc` against current `main` on the same Host/browser/driver/game and one wired direct Viewer, changing one variable at a time. Implement a codec-specific repair only if codec/encoder evidence identifies it; otherwise fix the proven capture, sender, BWE, or lifecycle cause.5. **Gate the strict-NAT guessed-candidate experiment.** Build only the isolated endpoint-dependent NAT emulator and browser harness first. Standard ICE must fail in the owned fixture, the capped candidate set must pass the documented repeatability, deadline, privacy, and cleanup gates in stable Chrome and Firefox, and fallback must remain unchanged. Only then may one manually approved, operator-owned test room run a default-off, kill-switched canary with explicit consent from both endpoints and exact room/edge/generation/budget bounds; failure closes the candidate. Do not ship guessed candidates to ordinary rooms or infer NAT type from IP, UA, carrier, or two STUN observations.6. **Make Viewer connection progress explicit.** Derive one stable stage from existing access, route, peer/SFU, media, autoplay, and bounded-failure state. Keep the overlay until a composited current-generation frame, show `Play` only for actual autoplay rejection, preserve a still-valid old frame during recovery, and expose retry only through the bounded controller. Measure the existing token-free SFU prewarm and route stages before adding another connection mechanism.-7. **Validate and release in priority order.** Review, merge, and deploy each coherent slice from canonical `main`: route first, then audio/codec mutation, then H.264/NAT evidence and any proven repair, then connection feedback and remaining tools. Before the route release, explicitly exercise Native `C=1/2/3` ordinary admission, waiting promotion, peer-assisted assignment, and physical sender-slot allocation. Run the focused state machine and browser/network matrix relevant to each slice, plus independent review, build/full gates, bounded production preflight, postflight, and rollback verification. A parallel branch may finish early but does not jump this rollout order.+7. **Validate and release in priority order.** Review, merge, and deploy each coherent slice from canonical `main`: route first, then audio/codec mutation, then H.264/NAT evidence and any proven repair, then connection feedback and remaining tools. Before the route release, exercise `C=1/2/3`, effective capacity `0..C`, first-frame commit and rollback, stale ready, candidate cursor/total deadline, relay ingress reparent, disconnect/cap drain, SFU-fed first child, selected TURN, and pause/resume through focused contract tests plus one bounded browser/network smoke. Run independent review, builds, production preflight, postflight, and rollback verification. A parallel branch may finish early but does not jump this rollout order.-The existing route implementation is an input to these tasks. Preserve its verified generation, authorization, make-before-break, and media-proof invariants while migrating capacity and fallback accounting. The accepted model is the destination; each wave must remain safe and truthful on its own rather than installing a name-only controller or an unreserved overlap.+The existing route implementation is an input, not an integration base. Reuse only scoped authorization, capacity, admission, deterministic-planning, and provisional-media primitives that fit the accepted single-loop model; rebuild the controller from the truth checkpoint rather than carrying role-specific state forward.## Accepted Later Roadmapdiff --git a/docs/verification-status.md b/docs/verification-status.mdindex 9d3c759d..42f703b2 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -13,9 +13,9 @@ Capacity and routing entries below describe the exact tested source or release o- Production runs exact `9461e207af62b4f38f6b7a8aa16f8beb49e0e4ee`, release `9461e20`, with `21d5cd9f7139` retained for rollback.- Local/public health return 200; `screener`, LiveKit, coturn, and nginx are active; `screener` reports zero restarts. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner `screener:screener`, and mode 0600.- Room admission defaults to eight and accepts explicit limits from one through sixteen. In the exact release, the unset endpoint-cap environment yielded Host2/ordinary Browser Viewer1, active/provisional/selected overlays were charged, SFU roots were limited to two, and one `peer-selected` lease was allowed per room excluding Host ingress. Those are release facts only. Current source uses steady endpoint cap `2` with static `1/2/3`, Host-publication slot accounting, same-edge TURN transport, and independent bounded server admission.-- The deployed SFU path enforces the release's controller/token root cap, Host-publication edge accounting, zero-child assignment/subscriber retention, and `dynacast: false`. The tagged local gate covers those release invariants; the accepted route migration still requires real shaped LiveKit packet flow, BWE downshift/recovery, resource, and root-with-children validation.+- The deployed SFU path enforces the release's controller/token root cap, Host-publication edge accounting, zero-child assignment/subscriber retention, and `dynacast: false`. The tagged local gate covers those release invariants; the accepted route migration still requires real shaped LiveKit packet flow, BWE downshift/recovery, and resource validation.- Share audio presets and local-only Host SFU, codec/encoder, A/V, and selected-candidate diagnostics are deployed. Their target-browser field availability and actual media values remain unverified.-- The bounded pre-share self-check, privacy-safe local JSON export, signaling-partition recovery, and peer-quality MBB are deployed. An ordinary Viewer with a peer/SFU upstream or the Host may own a separately budgeted provisional child; sibling MBB remains open. Real-route behavior remains part of the routing gate.+- The bounded pre-share self-check, privacy-safe local JSON export, signaling-partition recovery, and peer-quality MBB are deployed. An ordinary Viewer with a peer/SFU upstream or the Host may own a separately budgeted provisional child. Real-route behavior remains part of the routing gate.- Earlier exact-`16f6eab` evidence proves active Host ingress only; it does not prove the current release, initial Viewer ingress, healthy reselection, last-mile quality, or TURN performance.## Retained Functional Evidence@@ -25,7 +25,7 @@ Capacity and routing entries below describe the exact tested source or release o- Current source TURN-admission unit and signaling tests cover independent peer and Host-SFU logical edges, shared capacity exhaustion, exact reserve/commit/drain/release identity, current-share cleanup, and graceful shutdown. This is local authorization evidence, not real coturn, network-media, or production-capacity proof.- Chrome 151 synthetic `1/3/5/8` and 720p30 runs preserved bounded fanout and decoding. A `9461e20`-era three-Viewer rerun kept Host2/Browser Viewer1, decoded every Viewer, and recovered a hard first-level relay departure in 5,380 ms; it did not exercise quality-triggered MBB. Sixteen-Viewer cap2/cap3 loopbacks decoded all Viewers and a ten-second follow-up recorded guarded sender and aggregate Chromium CPU evidence, but resolution/FPS remained low and the ordinary-PC data cannot rank caps, select product policy, or prove sustainable heterogeneous-network quality. See [peer-assisted media](./research/peer-assisted-media.md).- Chrome 151 with local LiveKit 1.13.5/client 2.22.0 proved one SFU/UDP root after `q,f` -> `q,h`: decoded frames advanced 3 -> 23, rendered frames reached 26, Host used one edge, leaves were clean, and TURN was absent. This is functional evidence only. See [low-server media routes](./research/low-server-media-routes.md).-- Host A+B and authenticated P2P Viewer C evidence is sanitized, generation-bound, read-only, and closed for stale, ambiguous, or SFU-fed reports. Production can expose a Host-local current SFU `h` snapshot and clears it on publisher identity changes; raw media metadata is not retained. See [realtime quality adaptation](./research/realtime-quality-adaptation.md).+- Host A+B and authenticated P2P Viewer C evidence is sanitized, generation-bound, diagnostic-only, and closed for stale or ambiguous reports. Production can expose a Host-local current SFU `h` snapshot and clears it on publisher identity changes; raw media metadata is not retained. See [realtime quality adaptation](./research/realtime-quality-adaptation.md).- The built-in peer TURN canary was rejected after allocation passed but the direct Host/Pion Viewer path failed before forced relay. Full rollback restored STUN-only client ICE and zero allocations. See [built-in peer ICE TURN](./research/built-in-peer-ice-turn.md).- Chrome H.264 loopback proves negotiation and decode interoperability, not encoder performance or hardware attribution. Native WGC/MF has a one-Viewer Windows proof with 203 rendered 1280x720 frames, 500 Opus packets, and nonzero process/LUID-correlated `VideoEncode`. See [Native H.264](./research/native-h264-hardware-decision.md) and [Native shared encode](./research/native-shared-encode-sender.md).- Native Windows 11 process audio is source-only and default-off. A retained run isolated the target by about 4018x and delivered 495 Opus packets to one Viewer; package download, game sync, Windows 10, and other routes remain open. See [ADR-0008](./adr/0008-window-scoped-audio-capture.md).@@ -33,10 +33,10 @@ Capacity and routing entries below describe the exact tested source or release o## Open Proof Boundaries-- Routing: verify current-release initial ingress, `peer-selected` expiry/failure, corroborated bad-relay reassignment, one-root healthy SFU reselection, silent control partitions, signaling-connected current-generation RTP silence, and bounded failure on real browser/media paths. Silent control partitions may wait 30 to 60 seconds for heartbeat detection before the default five-second grace; RTP-silence acceptance must prove child-scoped recovery without granting one uncorroborated child authority to drain its parent.+- Routing: verify current-release initial ingress, exact candidate first-frame commit and rollback, `peer-selected` expiry/failure, relay-ingress reparent with subtree retention, disconnect/effective-capacity drain, pause/resume, and bounded failure on real browser/media paths. Silent control partitions may wait 30 to 60 seconds for heartbeat detection before the default five-second grace; a non-paused decoded-frame stall may invalidate only that exact child edge.- Quality: production startup blur remains unclassified. One same-`balanced` local A/B retained route/PC/SSRC/track while 720p rose to 1080p, but natural ramp prevents causal, production, or SFU conclusions. Correlate Host capture/encode/send with Viewer receive/decode before changing policy.- Relay resources: current source has the authenticated `1/2/3` endpoint-cap boundary, while production `9461e20` remains Host2/ordinary Browser Viewer1 and rejects Viewer child2 regardless of advertised capacity. Before release, explicitly exercise Native `C=1/2/3` admission, waiting promotion, peer-assisted assignment, and physical sender slots; CPU/GPU/upload and heterogeneous-network measurements remain evidence, not authority to change the contract.-- SFU: production `9461e20` deploys ordered `q,h`, roots <=2, and Dynacast off. Those are release facts; the accepted model has no fixed root-count or room-wide lease rule. Current source still needs real LiveKit lifecycle/JWT replay and shaped packet-flow, BWE downshift/recovery, resource, and root-with-children validation. Use Linux `tc` or an authorized public canary for per-leaf shaping, never CDP throttling.+- SFU: production `9461e20` deploys ordered `q,h`, roots <=2, and Dynacast off. Those are release facts; the accepted model has no fixed root-count or room-wide lease rule. Current source still needs real LiveKit lifecycle/JWT replay and shaped packet-flow, BWE downshift/recovery, resource, and SFU-fed first-child validation. Use Linux `tc` or an authorized public canary for per-leaf shaping, never CDP throttling.- Audio: verify the 64/128/256 kbps Share settings, negotiated/observed bitrate, audible music quality, route changes, and game A/V synchronization. Bitrate settings are ceilings, not quality proof.- Observability: the UI and local stats plumbing are deployed, including identity-bound relayed-detail retention and export freshness guards, but target-browser availability and actual values remain unverified for Host SFU sender evidence, codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, A/V playout/jitter/concealment, selected candidate endpoints, and bounded same-pair STUN-response observation. These fields diagnose and have no recovery authority; they do not by themselves prove hardware encode, synchronization quality, or route quality.- Mobile: Android/iOS remain Viewer-only. Autoplay, rotation, iOS lock-screen/page reclamation, background reconnection, and network changes need device evidence. AirPlay/system mirroring is Viewer-local output, not a portable in-app WebRTC output contract.diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index 5ed9c4e6..1561fcfe 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -186,9 +186,9 @@ Viewer 本地连接详情只从当前 route 的唯一 inbound screen video/audio`frameRate` 约束和 sender 的 `maxFramerate` 都是目标或上限;浏览器仍控制实际捕获、重复帧处理、编码和拥塞降级。静态画面可能由浏览器减少实际编码数据,但标准没有保证每个实现以同一种方式节省采集或 GPU 开销。本 PoC 不添加画面差分、定时改约束或自定义动态 FPS 状态机,先用 `framesEncoded`、实际发送码率、`totalEncodeTime`、质量受限原因和主机资源占用测量真实问题。-质量自适应采用 ADR-0007 的 built-in-first 路径隔离双表示,而不是全房间按最差链路降档。Direct/peer 保留每条 PeerConnection 的 stock WebRTC GCC。每条 SFU path 从 `HIGH` ceiling 开始;优先发布共享 `HIGH+LOW` 并让 LiveKit BWE 独立降层和恢复。若该 gate 通过,Screener 不实现媒体层 selector。应用证据只决定下述 parent/leaf 拓扑资格与诊断。`LOW` 可以常驻;关闭空闲层只是资源优化。active representation/layer 数量硬限制为二,不能按 viewer 增长。标准浏览器不保证跨 PeerConnection 共用一个物理编码器,inactive 层也不保证释放 GPU;实际层数、实例数、CPU/GPU、游戏 FPS/p1 low、区间 encode cost、上传与释放行为必须实测。若没有合格 hardware/power-efficient 路径或额外表示破坏游戏/上传预算,则 fail closed,保留健康路径并明确显示弱路径降级或失败。+质量自适应采用 ADR-0007 的 built-in-first 路径隔离双表示,而不是全房间按最差链路降档。Direct/peer 保留每条 PeerConnection 的 stock WebRTC GCC。每条 SFU path 从 `HIGH` ceiling 开始;优先发布共享 `HIGH+LOW` 并让 LiveKit BWE 独立降层和恢复。若该 gate 通过,Screener 不实现媒体层 selector。应用证据只用于诊断。`LOW` 可以常驻;关闭空闲层只是资源优化。active representation/layer 数量硬限制为二,不能按 viewer 增长。标准浏览器不保证跨 PeerConnection 共用一个物理编码器,inactive 层也不保证释放 GPU;实际层数、实例数、CPU/GPU、游戏 FPS/p1 low、区间 encode cost、上传与释放行为必须实测。若没有合格 hardware/power-efficient 路径或额外表示破坏游戏/上传预算,则 fail closed,保留健康路径并明确显示弱路径降级或失败。-质量证据保持 edge-local,只能影响证据覆盖的 parent/child authority,不能形成全房综合分数。现有实现包含 Viewer 与 Host provisional-parent、媒体证明后 promotion、失败保留旧边和 child-scoped reparent;relay-parent suspect/repair/drain 等待独立 evidence owner,不能从固定数量的 child 事件推断 parent failure。整体模型统一 candidate eligibility、质量 owner 的独立关联证据、sibling migration、migration mutex、capacity reservation 与 fallback 交互。无论策略取值如何,prepare/commit/rollback 都保留 exact session/share/revision/connection/media-binding identity,ICE connected 不能替代 live track、正 RTP 和 decoded-frame progress。+质量证据只用于诊断,不形成全房分数或 parent authority。路由只消费 exact child edge 的 `failed/closed` 和非暂停 decoded-frame stall。prepare/commit/abort 绑定 authenticated sessions、share generation、base/pending revision 与 candidate connection;candidate child 的第一帧新 decoded video 是唯一应用层 media-ready,ICE connected 不能单独提交。状态决策必须关联同一时间区间和媒体代次的三段证据:@@ -200,15 +200,15 @@ Viewer 本地连接详情只从当前 route 的唯一 inbound screen video/audio判断顺序固定为:Capture 低归为采集或约束;Capture 高而 outbound 低且 reason=`cpu` 归为编码资源;Capture 高而 outbound 低且 reason=`bandwidth` 归为 GCC、上行或 TURN/路径;outbound 正常而 inbound 低归为传输或接收;inbound 指标正常但肉眼模糊归为码率/量化、协商 codec/profile/parameters、适用的 scalable layer 或显示缩放。B/C 必须关联同一派生协商结果与实际解码表现。累计统计只计算相邻、不重叠区间的 delta;缺字段、stats ID/媒体代次变化或计数器回退时重新建立基线,不能把未知当零。-探针按最小顺序落地:先在 host 同一个采样 tick 内关联 A+B,并携带明确 window、媒体/stats identity 和有效 delta;验证可靠后才增加只包含拓扑判定所需字段的受限、已鉴权 C 上报。不建设通用遥测 schema,只传派生后的协商字段,绝不上传 raw stats、raw SDP、candidate 地址或原始设备/网络标识;鉴权与关联只使用服务端签发的不透明 path/connection generation ID。+探针按最小顺序落地:先在 host 同一个采样 tick 内关联 A+B,并携带明确 window、媒体/stats identity 和有效 delta;需要 Viewer 诊断时只增加受限、已鉴权 C 上报。不建设通用遥测 schema,只传派生后的协商字段,绝不上传 raw stats、raw SDP、candidate 地址或原始设备/网络标识;这些字段不产生路由 authority。-Viewer 可通过已鉴权、绑定当前房间/路径代次的控制面报告需要 `LOW`,但它只是一条拓扑观测输入,不能命令内建 WebRTC/LiveKit 媒体层。报告必须限频、去重,并与 sender 的 Transport-CC/GCC、实际码率、RTT、丢包、重传及编码限制、派生协商 codec/profile/parameters(适用时含 `scalabilityMode`)和 viewer 的实际解码/丢帧/冻结表现交叉验证。UA、平台和设备型号不参与质量或 relay capacity 决策。+Viewer 可通过已鉴权、绑定当前房间/路径代次的控制面报告需要 `LOW`,但该请求只用于表示诊断,不能命令内建 WebRTC/LiveKit 媒体层或改变拓扑。报告必须限频、去重;UA、平台和设备型号不参与质量或 relay capacity 决策。SVC 的标准能力门禁已经静态关闭为 `no-go-web-svc-cross-path-hardware-contract`。WebRTC-SVC 只配置单个 outgoing sender,direct/peer receiver 没有对应的按层选择 API,独立 PeerConnection 之间也没有 shared-encode 契约;requested/applied codec/`scalabilityMode`、Media Capabilities `powerEfficient` 与 RTCStats encoder 字段不能证明编码器一定是硬件。Pinned LiveKit 虽能在 SFU 内为每个 subscriber 设置最大空间/时间层请求,但实际选择依 codec/selector 而异:server 1.13.5 只为 VP8 安装 temporal selector,当前 H.264 `q,h` simulcast 只有空间层选择。Client 2.22.0 还会把 screen-share SVC 强制成三层 temporal-only `L1T3`,既没有低分辨率 base,也超过最多两层的门槛;这种 SFU 选层也不延伸到 direct/peer descendants。当前静态结论不运行 browser harness。未来只能由能明确锁定硬编、最多两层、跨 direct/peer/SFU 复用同一输出且通过游戏性能/延迟门槛的 native sender 以新决策重开。普通非分层编码包不能只靠转发生成另一档画质,实现路径差异只能用第二表示、合格的 scalable layers 或 relay/SFU 转码。质量控制不放宽稳态 outbound media-copy 预算:所有非服务器端点继续受统一静态 capacity 约束;native relay 只转发选定表示的编码包,不解码重编码。后续双树或条带化必须另行验收,不能绕过当前 graph、identity 和 capacity invariant。-质量证据形成两条正交状态:`EdgeHealth(parent, child, generation)` 控制 child-scoped reparent,`RelayEligibility(parent)` 仅适用于 relay parent,控制 `eligible -> suspect -> draining -> ineligible`。Viewer 的 C 证据和 parent 对同一 edge 的 B 证据必须按 exact route identity(room/share、双方 session、assignment/connection/media-binding generation、route revision,及适用时 publication generation)和 sequence 相关;同一 edge 的 C+B 不直接触发 parent drain。若 exact ordinary peer edge 在信令和 PeerConnection 存活时持续没有当前代 RTP/decoded progress,且有界 parent-proof deadline 到期后仍停滞,`EdgeHealth` 不论是否收到 matching positive non-server-parent outbound-media proof,都只为该 child 进入 hard reparent;parent 正在发送或未回应都不改变 `RelayEligibility`。仅靠 downstream evidence 退位时,必须存在一条不同的 current sibling edge,且每条 current authoritative child edge 都独立完成当前代 unusable 证明;任何正进展、未知或未完成证明都阻止 drain,正进展清除该 exact edge 的失效证据,只有一个 current child 时只迁走该 child。Relay parent 自身 ingress 失败先触发本地 reparent 或 branch-preserving `replaceIngress` 并进入 `suspect`;parent/session hard failure 或 ingress 修复失败可独立 drain。endpoint-wide sender/resource failure 只有存在服务端可验证且作用域明确的 producer 时才成立,普通单 edge `route-failed` 只影响该 edge。Host source 使用 publication repair/child migration。drain 停止新 child,仍健康的 ingress 保留,失效 ingress 在同一 target 中替换或移除,迁移有目标的 children,并让无目标者进入有界等待或失败;更长稳定证明和 cooldown 才恢复 `eligible`。同一个 controller 每房间只提交一个 target revision,按 hard failure、confirmed parent drain、single-edge soft reparent 的顺序合并事件;drain 吸收覆盖范围内的 child intent。exact edge identity 未变化时,未过期证据跨 unrelated revision 与 broadcast 保留并更新 guard;identity 变化、正进展或成功迁走该 edge 时只清对应证据。权威 pause 停止并清空当前 generation 的质量关联,resume 后从 fresh baseline 重建。+路由状态只有 committed graph 和一个 pending child operation;该对象聚合 candidate list/cursor、一个 current candidate/预留和一个总 deadline。relay 自身 ingress 失效时,它作为 child 进入同一 reparent 并保留 subtree;disconnect 或 effective capacity 降低时让 direct/overflow children 逐个回到 reconcile。多个下游 edge 若各自失效,会独立迁移并自然排空 relay。权威 pause abort operation、保持 active graph、抑制 stall;resume 重新 reconcile。标准表示能力排在任何自定义双表示媒体实现之前。当前 Web P2P simulcast 缺少 receiver 选 RID 与跨 PeerConnection shared-encode 契约;当前 Web/LiveKit SVC 也缺少 direct/peer 独立选层和可移植硬件保证。Production 的 exactly-two screen-share simulcast 与 `dynacast: false` 只是实现和质量实验事实,不证明 root topology、publication accounting 或 subscriber model。具体表示门槛由 ADR-0007 和[实时质量调研](./research/realtime-quality-adaptation.md)持有,不得绕过 stock WebRTC congestion control。@@ -244,27 +244,22 @@ candidate 预发给 participant、房间或普通 peer edge。HTTPS/WSS 始终receive 免费,committed selected TURN 不重复计数。服务端是权威,客户端广告只能收紧,不能按 Host/Viewer、浏览器、UA、设备或页面状态放宽或分叉。-每个 candidate 和异步结果都必须绑定 exact room、share generation、endpoint-sessions、route revision、assignment generation、connection identity、media-binding-generation,以及存在时的 publication generation。迁移保留旧 active media;只有新 candidate 的 live track、-正 RTP 与 decoded-frame progress 都属于当前代时才原子 commit。ICE-`connected`、token 签发或 assignment 本身都不是媒体证明。失败、超时、stale-identity 或授权撤销销毁 candidate,保留或恢复最后一个有效 route。+每个 candidate 和异步结果都绑定 authenticated room/endpoint sessions、share+generation、base/pending route revision 与 candidate connection identity;SFU+publication generation 由 resource owner 单独持有。迁移保留可用旧 media;只有+candidate child 解码出第一帧新画面时才原子 commit。ICE `connected`、token+签发或 assignment 本身都不是 media-ready。失败、超时、stale identity 或授权+撤销销毁 candidate,保留或恢复最后一个有效 route。SFU 与 TURN 是可选、有界的 server-assisted resources。一个 room controller-统一负责 allocate/distribute、child reparent 和 relay abdicate/drain:Host-拥有唯一 authoritative publication,所有 SFU-fed Viewer 订阅它。SFU-fed-Viewer 的容量广告或 ingress ready 不授予 relay eligibility;controller 只可预留-一个正式 sender slot,并以一条 exact provisional ordinary-child edge 作为证明事务。-该 child 同时证明 connected transport、live video、当前窗口正 RTP receive 与-decoded-frame progress,加上 exact sender ownership 和 controller admission 后才-atomic commit;失败、超时、暂停或 identity 变化销毁 candidate 并保持 leaf,后续-每个 child 仍分别证明自己的 exact edge。TURN 只替换授权 logical edge 或-Host-SFU ingress 的 transport,不是拓扑节点。现有 edge 优先保持 direct/STUN,-必要时使用 exact selected TURN,再按需要切换到 SFU;Host 无 direct first-level-path 时优先一条可经 TURN 的 Host-SFU publication。端点容量、SFU/TURN-ingress/egress、临时 overlap、media binding generation、server admission 和-bounded failure 在同一 reserve/proof/commit/rollback 事务中记账。+通过同一个 reconcile 处理 allocate/distribute、child reparent 和 relay drain。+Host 拥有唯一 authoritative publication,所有 SFU-fed Viewer 订阅它;SFU-fed+与 peer-fed endpoint 的新 child 都使用同一 provisional first-frame transaction。+TURN 只替换授权 logical edge 或 Host-SFU ingress 的 transport,不是拓扑节点。+现有 edge 优先保持 direct/STUN,必要时使用 exact selected TURN,再按需要切换到+SFU;Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU+publication。端点容量、SFU/TURN ingress/egress、临时 overlap、server admission+和 bounded failure 在同一 reserve/first-frame/commit-or-abort 事务中记账。短期 server-assisted credential 必须严格绑定当前 route identity、只存内存、受 TTL与 quota 限界,并且不进入 URL、日志、browser storage、room row 或 SQLite。Coturn@@ -339,7 +334,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio- 质量协议的 host 授权、严格字段与数值范围、last-wins、当前/未来 relay、已配置 SFU 和普通 P2P wire 兼容;sender 的四字段 requested/applied 读回、拒绝与持续受限提示;screen audio SDP helper 覆盖 CRLF、existing/missing fmtp、unknown key preservation、幂等、payload number、rejected/non-audio,以及 empty/no-Opus/ambiguous/parser 异常原对象 fallback,`ViewerPeer` 覆盖 initial/restart/rebuild 时同一结果的 local/signaling 一致性,SFU publisher 精确断言 high-quality stereo/forceStereo/DTX 且不覆盖 RED;- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 room policy;site-access cookie 不绕过 private grant/password,grant/password 不能建房、取得 Host 或跨房。覆盖 fragment/sessionStorage/replaceState、无 site access 的 public/password code-only 统一拒绝、通过 site access 后的 public/password 进入、不含明文于 URL/浏览器持久存储/SQLite/log、Native capability isolation,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;- 客户端策略与 stats 解析:会话替换不重连,ordinary ICE、LiveKit 与 selected-edge TURN protocol 分离,远端 TURN transport 保持未知;-- route planner property tests:候选输入乱序仍产生相同 target,健康边 sticky,硬过滤拒绝 stale/cycle/depth/cap/ineligible/cooldown/unadmitted parent,同深度优先剩余容量并稳定打破平局,失败候选清理后才尝试下一项;+- route planner property tests:候选输入乱序仍产生相同 list,健康边 sticky,硬过滤拒绝 stale/cycle/effective-capacity/unadmitted parent,优先结果深度和剩余容量并稳定打破平局;失败候选清理后 cursor 前进且总 deadline 不重置;- Viewer stage reducer:peer/SFU prepare、remote track 无首帧、首个 composited frame、autoplay rejection、恢复和 bounded failure 不互相冒充,动态状态不改变布局或 route authority;- TypeScript 类型检查、Vite production build 和仓库 hygiene。@@ -362,7 +357,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio2. 完成 RoomStore、建房 API、WebSocket 鉴权和定向信令。3. 完成屏幕捕获、逐观看者 PeerConnection、观看播放和手动质量档。4. 完成连接恢复和 stats 面板;随后以 STUN-only snapshot 替换旧全房 TURN credential/refresh wire。-5. 在已合入的 endpoint cap/accounting、`screener-v6` wire、SFU lifecycle 与 TURN allocation admission 边界上,按 ADR-0005 完成 route controller convergence:把 deterministic allocation、child reparent 和 parent drain 收到一个 controller;该 wave 独立可回滚。+5. 在已合入的 endpoint cap/accounting、`screener-v6` wire、SFU lifecycle 与 TURN allocation admission 边界上,按 ADR-0005 完成 route controller convergence:一个 event-driven reconcile 和一个 room-serial candidate 统一处理 deterministic allocation、child reparent 和 relay drain;该 wave 独立可回滚。6. 路由边界合入后依次落 live screen-audio ceiling 和 paused video-codec transaction;随后做 H.264 根因诊断与 strict-NAT emulator gate,门禁通过才允许 allowlisted canary。7. 加入 first-frame-driven Viewer connection stages。Site access、room-scoped Viewer grant、路由与 SQLite v3 合同保持唯一。8. Windows Native fixed-`HIGH` 保持可选且不改变 Web 默认;shared encode、移动 lifecycle 和平台输出按 TODO roadmap 后续推进。@@ -376,23 +371,23 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio启动 owner fence 复用配置的应用监听地址:进程必须先完成独占 bind,绑定失败时不得调用 LiveKit;bind 成功但 LiveKit 初始化未完成时,HTTP 只返回 `503` 且不安装 signaling upgrade handler。唯一 owner 完成 foreign-room 拒绝、遗留 managed-room 删除和 empty readback 后,才开放 HTTP 与 signaling。这个顺序使重启或竞争进程不能在失去应用 owner 身份时清理仍在使用的 LiveKit room。-服务端维护每个房间唯一的版本化 route owner,它独占 committed graph、pending target 和 transition lifecycle。拓扑 helper 只保存 participant metadata 并纯计算 candidate plan,不持有可回滚的第二份 active/pending graph。候选 parent 可以形成图,但 committed media graph 必须无环;Host 没有 upstream,每名 Viewer 同时只有零或一个 active upstream,且每个 active Viewer 必须沿 peer edges 到达 Host 或沿当前 authoritative Host publication 到达 source。加入、容量释放、节点离开、当前边失败和已接受的 path-health evidence 才能触发一次有界重选,未受影响分支保持 sticky。+服务端维护每个房间唯一的版本化 route owner,它独占 committed graph、一个 pending child operation 和 transition lifecycle。拓扑 helper 只保存 participant metadata 并纯计算 candidate list,不持有第二份 graph。operation 内聚 list/cursor、一个 current candidate/预留和一个总 deadline。committed media graph 必须无环且 source-reachable;Host 没有 upstream,每名 Viewer 同时只有零或一个 active upstream。加入、容量变化、节点离开、当前 edge `failed/closed`,以及非暂停时的 decoded-frame stall 都只唤醒同一个 `reconcileRoom(roomId)`;未受影响分支保持 sticky。-Parent selection 使用硬过滤加字典序,不建立综合质量评分器。先拒绝 stale session、不可 source-reachable、成环、超深、无 sender/overlap slot、relay-ineligible、位于 failed-edge cooldown 或 server resource 未准入的候选;对剩余候选依次比较结果深度、分配后剩余稳态 sender slots、稳定加入顺序与 peer identity。controller 每次只 reserve/prepare 一个候选,使用该 `RTCPeerConnection` 自带的 ICE checklist/connectivity checks,再以 current-generation RTP、live track 与 decoded frame 验证;初次加入或 hard failure 采用达到 media-usable floor 的首个候选,soft-quality reparent 还需 quality owner 证明候选达到 recovery threshold 且优于仍健康旧 edge。失败先幂等清理候选再取下一个;受管 SFU room 完成删除证明前仍占 server capacity。应用不做 all-pairs ping、raw-IP/NAT/地理排名、周期探测或全房重平衡。一个 exact edge 的近期失败只进入该 edge 的有界 exclusion/cooldown,不污染其他路径。+`reconcileRoom` 在没有 pending operation 时先删除 disconnected childless participant,再找一个 waiting Viewer,或 parent offline/effective-capacity 不足、exact edge 已失效的 child。Candidate planning 拒绝 stale session、不可 source-reachable、成环、无 sender/overlap slot或 server resource 未准入的 tuple;对剩余 upstream 依次比较结果深度、剩余 sender slots、稳定加入顺序与 peer identity,并建立 direct/STUN、selected TURN、SFU 的有界顺序。每次只 reserve/prepare cursor 指向的 candidate。WebRTC 负责 ICE/DTLS/consent;exact candidate child 解码出第一帧新画面后发送一次 ready,controller 才 commit。失败先幂等清理并推进 cursor,operation 总 deadline 或耗尽进入 waiting/failure。没有上述离散事件时不改变拓扑。无环和房间 admission 已约束最大深度,不增加独立 depth hard cap。-所有非服务器端点共享一个 server-authoritative steady outbound media-copy capacity:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。peer child 或 Host publication 各占一份,upstream receive 免费,committed selected TURN 只替换同一份 edge transport;SFU subscriber egress 与 TURN allocation 使用独立 server admission。客户端 capability 只能收紧该值,不能按角色、浏览器、UA、设备或页面可见性建立另一套 policy。服务端通过 v6 `authenticated.endpointMediaCopyCapacity` 把最终值交给 Web 与 Native;Native 不从 `maxViewers` 推导发送预算,普通 admission、peer-assisted child assignment 和槽位分配共用该值。代码通过一个 shared accounting guard 执行,不在 Host、Viewer、active、recovery 或 migration 分支重复 magic number;client/server/native wire 随该能力原子升级。Selected TURN 使用显式无默认值的正 safe-integer deployment capacity;同一个进程内 ledger 对每条 exact peer-selected edge 和 Host-SFU ingress 在 credential 签发前 reserve `1`,并让 reserved、committed、draining authorization 持续计费至 exact logical release。`C=3` 满载时只阻止会产生第四份 endpoint media copy 的 token/grant;同一 edge 改用 TURN 不增加 endpoint copy,但仍需独立 TURN admission。+所有非服务器端点共享一个 server-authoritative steady outbound media-copy cap `C`:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。服务端将 endpoint 当前广告的 `0..C` 可用值 clamp 为唯一 `effectiveDownstreamCapacity`;该值只表示当前可用 sender slots,不建立角色、浏览器、UA、设备或页面可见性 tier。peer child 或 Host publication 各占一份,upstream receive 免费,committed selected TURN 只替换同一份 edge transport;SFU subscriber egress 与 TURN allocation 使用独立 server admission。服务端通过 v6 `authenticated.endpointMediaCopyCapacity` 把部署 `C` 交给 Web 与 Native;Native 不从 `maxViewers` 推导发送预算。代码通过一个 shared accounting guard 执行,不重复 magic number;client/server/native wire 随该能力原子升级。Selected TURN 使用显式无默认值的正 safe-integer deployment capacity;同一个进程内 ledger 对每条 exact peer-selected edge 和 Host-SFU ingress 在 credential 签发前 reserve `1`,并让 reserved、committed、draining authorization 持续计费至 exact logical release。`C=3` 满载时只阻止会产生第四份 endpoint media copy 的 token/grant;同一 edge 改用 TURN 不增加 endpoint copy,但仍需独立 TURN admission。-SFU admission 在应用单进程中只有一个注入实例。LiveKit credential tuple 完整时,必须同时显式配置私有 `LIVEKIT_API_URL`、正 safe integer `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;容量没有产品默认值,也不从 Viewer 数、endpoint cap 或历史 root 数推导。专用 LiveKit 实例设置 `room.auto_create: false`。账本只保存全局已用计数和按 exact room/share/publication generation 索引的 `reserved | committed | draining` 条目:Host publication 计 ingress `1`,每个订阅计 egress `1`,candidate、committed 和未完成 drain 的旧 generation 同时计数。route controller 先 reserve,再通过 `RoomService.CreateRoom` 创建 exact-generation room,成功后才 prepare 和签发 token;media proof 后 commit candidate 并把旧 generation 转入 draining,失败、超时、失联、分享换代、停止或删房也只转入同一状态。只有 `RoomService.DeleteRoom` 成功且 follow-up lookup 证明 room 不存在,账本才扣除对应资源;auto-create 关闭后,旧 token 不能重建已删除 room。进程启动在接受流量前拒绝任何非 Screener room,删除全部遗留 Screener room 并确认 namespace 为空;关闭时先 drain 再遗忘计数。Host 信令离线期间若 exact room 中的 Host participant 仍存在就继续计费并保留健康媒体,participant 消失后在一个有界轮询周期内回收。稳态 reserve/commit/drain bookkeeping 仍是 Map lookup 与整数加减;只有 generation 创建、删除、启动清场和 Host 离线检查访问 LiveKit control plane。TURN allocation 使用独立的进程内 logical ledger;多应用进程部署必须先增加共享原子 admission/lifecycle owner。+SFU admission 在应用单进程中只有一个注入实例。LiveKit credential tuple 完整时,必须同时显式配置私有 `LIVEKIT_API_URL`、正 safe integer `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;容量没有产品默认值,也不从 Viewer 数、endpoint cap 或历史 root 数推导。专用 LiveKit 实例设置 `room.auto_create: false`。账本只保存全局已用计数和按 exact room/share/publication generation 索引的 `reserved | committed | draining` 条目:Host publication 计 ingress `1`,每个订阅计 egress `1`,candidate、committed 和未完成 drain 的旧 generation 同时计数。route controller 先 reserve,再通过 `RoomService.CreateRoom` 创建 exact-generation room,成功后才 prepare 和签发 token;exact candidate child 的 first decoded frame 后 commit candidate 并把旧 generation 转入 draining,失败、超时、失联、分享换代、停止或删房也只转入同一状态。只有 `RoomService.DeleteRoom` 成功且 follow-up lookup 证明 room 不存在,账本才扣除对应资源;auto-create 关闭后,旧 token 不能重建已删除 room。进程启动在接受流量前拒绝任何非 Screener room,删除全部遗留 Screener room 并确认 namespace 为空;关闭时先 drain 再遗忘计数。Host 信令离线期间若 exact room 中的 Host participant 仍存在就继续计费并保留健康媒体,participant 消失后在一个有界轮询周期内回收。稳态 reserve/commit/drain bookkeeping 仍是 Map lookup 与整数加减;只有 generation 创建、删除、启动清场和 Host 离线检查访问 LiveKit control plane。TURN allocation 使用独立的进程内 logical ledger;多应用进程部署必须先增加共享原子 admission/lifecycle owner。普通 Web relay 把收到的 remote track 加入独立 downstream `RTCPeerConnection`,因此可能逐跳解码和重编码;浏览器不保证跨连接 shared encode。每条 ordinary child 是独立网络副本,实际 encode time、CPU/GPU、bitrate、loss、frame rate、depth 和 recovery 必须测量。-迁移使用 exact room/share/session/revision/assignment/connection/media-binding identity。旧 route 保持 active,candidate 在 active map 外准备;只有当前代 live track、正 RTP 与 decoded-frame progress 同时成立时才原子 promotion。失败、超时、代次变化或授权撤销销毁 candidate 并保留或恢复旧 route。Make-before-break 的 overlap 由统一端点容量、单个有界 `TransitionOverlapSlot` 和 typed server-resource admission 同时决定。+迁移使用 authenticated room/endpoint sessions、share generation、base/pending route revision 与 candidate connection identity。可用旧 route 保持 active,candidate 在 active map 外准备;candidate child 的第一帧新 decoded video 原子触发 promotion。失败、超时、代次变化或授权撤销销毁 candidate 并保留或恢复旧 route。Make-before-break 的 overlap 由统一端点容量、单个有界 `TransitionOverlapSlot` 和 typed server-resource admission 同时决定;旧 edge 已 hard-invalid 时直接进入同一恢复事务而不伪装可用。-SFU/TURN 的 publisher、subscriber、selected transport、central admission、resource accounting、temporary overlap 和 exact fallback sequence 已由 ADR-0005 作为一个不可拆分的设计项接受。普通端点 child count 不能隐式成为 server cap,兜底也不能形成无界 whole-room fanout。一个 Host publication 服务所有 SFU subscriptions;SFU-fed Viewer 只有在独立出站证据成立时才可 relay。TURN 只替换授权 edge 的 transport,Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。+SFU/TURN 的 publisher、subscriber、selected transport、central admission、resource accounting、temporary overlap 和 fallback sequence 由 ADR-0005 统一定义。普通端点 child count 不能成为 server cap,兜底也不能形成无界 whole-room fanout。一个 Host publication 服务所有 SFU subscriptions;SFU-fed 与 peer-fed endpoint 使用相同的 provisional-child first-frame transaction。TURN 只替换授权 edge 的 transport,Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。-质量事件按影响范围分工,而不是按谁先发现分工。Viewer 对自己 upstream 的 C 证据与 parent 对同一 edge 的 B 证据相关后,只触发该 child 的换父;仅当至少还有一条不同 sibling edge,且所有 current authoritative child edges 都各自确认 unusable,downstream evidence 才把 parent 标为 directional-ineligible 并退位排空。同一 edge 的 C+B、未知 evidence、未完成 proof 或任一 current child 的正进展都不能完成 parent corroboration。parent/session hard failure、修复失败的 relay-parent ingress,以及由服务端可验证 producer 确认的 endpoint-wide sender/resource failure 可独立 drain。Host source 走 publication repair/child migration,不走 relay-parent reparent。节点同时是 child 和 relay parent 时,先用 reparent 或 branch-preserving `replaceIngress` 修复其自身 ingress、停止新 child;新 ingress 恢复下游媒体时保留子树,否则由同一 controller 合并下游 drain。C+B 不产生第二个 controller 或第二个 revision;pause、evidence carry 和 exact-edge invalidation 共用同一 generation fence。+relay 自身 ingress 失效时,reconcile 把它作为 child 换父并保留 subtree。endpoint disconnect 或 effective capacity 降低时,只保留稳定顺序内可容纳的 children,并把 overflow children 逐个送回同一 reconcile;offline childless participant 自然删除。权威 pause abort pending operation、保留 active graph、让新参与者 waiting,并抑制 decoded-frame stall;resume 重新 reconcile。A/B/C、码率、FPS、模糊和 SFU layer 只用于诊断。-实现迁移以当前 ADR-0005 invariants 为准;生产 release `9461e20` 仅是部署快照,代码迁移只保留仍满足当前 identity、media-proof 和 bounded-recovery 约束的部分。+实现迁移以当前 ADR-0005 invariants 为准;生产 release `9461e20` 仅是部署快照,代码迁移只保留仍满足当前 identity、first-frame commit 和 bounded-recovery 约束的部分。## 官方与参考资料访问日期为 2026-08-18 至 2026-08-21:diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index d1add6c4..222b1568 100644--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"@@ -8,7 +8,7 @@`PEER_ASSISTED_MEDIA=true` 是旗舰部署的单一总开关;每个房间独立保存 route revision、会话代次、失败状态和容量预算。系统优先使用 direct/peer UDP,普通 peer 连接保持 STUN-only。所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity:默认 `2`,只允许静态配置 `1`、`2` 或 `3`;peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算,selected TURN 只替换同一份 edge 的 transport,角色、浏览器、UA、设备或页面可见性不产生特例。-构建一个面向熟人游戏场景的低延迟屏幕共享工具。分享者可以在私密房间内分享游戏、应用窗口或显示器画面及声音,多名朋友可以即时观看。中心服务负责房间、身份、确定性路由和建立连接;每名 Viewer 同时至多一个 active upstream,活动媒体图保持无环。切换必须绑定精确身份与代次,保留旧边直到新边出现当前代 RTP、解码帧和 live track,所有路线最终进入有效媒体、明确等待或有界失败。系统自动完成分配和恢复,用户不手动选择拓扑。分享端 Web 优先并允许后续 Electron/原生增强;观看端使用普通桌面或手机浏览器。+构建一个面向熟人游戏场景的低延迟屏幕共享工具。分享者可以在私密房间内分享游戏、应用窗口或显示器画面及声音,多名朋友可以即时观看。中心服务负责房间、身份、确定性路由和建立连接;每名 Viewer 同时至多一个 active upstream,活动媒体图保持无环且可达源。切换绑定当前鉴权会话、分享代次和唯一 pending revision;可用旧边保留到 exact candidate child 解码出第一帧新画面,所有路线最终进入有效媒体、明确等待或有界失败。系统自动完成分配和恢复,用户不手动选择拓扑。分享端 Web 优先并允许后续 Electron/原生增强;观看端使用普通桌面或手机浏览器。SFU/TURN 的 publication、subscription、transport、server-resource accounting、临时 overlap 和具体 fallback 序列由 ADR-0005 的整体模型统一定义,不能从普通端点 child 数量推导。SFU 与 TURN 只能是有界兜底资源,不能把产品改成无界或 always-SFU 的整房转发。当前 PoC 的观看人数限制是实现事实,不是性能声明;任何扩容目标必须以真实资源、质量、深度和恢复矩阵另行验收。产品不承担公开直播或大规模观看。@@ -25,12 +25,12 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Web Host 与 Viewer 都必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份默认只显示名称;仅当房内出现同名时追加当前房间 `peerId` 的至少六字符短后缀,并只在同名项后缀碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native 使用同一版本化鉴权 wire,但不发送 presence capability,也不接收 Web roster。- 一对多观看:房间 admission 与端点下游容量分别配置,超额加入必须明确拒绝。Production 当前默认 8、显式接受 1 至 16;未来默认值和上限是独立产品决策,必须经过相应资源、质量、深度和恢复验收,不能从端点 cap 或一次短跑推导。- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算,committed selected TURN 只替换同一份 logical edge 的 transport。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。服务端在每次 `authenticated` 权威快照中返回最终 `endpointMediaCopyCapacity`;普通非 peer-assisted 模式也只授权稳定加入顺序中的至多 `C` 个 Host child,超额 Viewer 保持入房等待并在槽位释放后提升,信令不能绕过该集合。Web 与 Native 严格校验该值,Native Host 的普通 Viewer admission、peer-assisted child assignment 和实际发送槽位都使用同一值,且不得从独立的房间 `maxViewers` 推导。并行产生媒体的 candidate 必须持有唯一的 `TransitionOverlapSlot`,并在 commit 后回到稳态上限;SFU subscriber egress 与 TURN allocation 由独立 server admission 记账。该不兼容能力变化与单一 signaling wire 原子升级;缺失或非法 cap 与旧客户端都在取得房间或 route authority 前 fail closed。-- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的分支。SFU-fed Viewer 不能仅凭容量广告或 SFU ingress ready 成为 relay parent;controller 只能为它预留一个正式 sender slot,并用一条 exact provisional ordinary-child edge 验证 connected transport、live video、当前窗口正 RTP receive 与 decoded-frame progress。该 child 的端到端证明与 controller admission、精确 sender ownership 同时成立后,atomic commit 才授予 relay eligibility;失败、超时、暂停或 identity 变化都销毁 candidate 并让它保持 leaf,以后的每个 child 仍分别证明自己的 exact edge。-- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers,普通边不得预发 TURN candidate。所有恢复和候选授权必须绑定 exact room/share generation、endpoint session、route/assignment generation 与 connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的顺序是保持既有 logical edge,必要时 direct/STUN 后使用 exact selected TURN;只有 logical ingress 不可用时才使用当前 Host publication 的 SFU subscription。Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU publication,而不是逐 Viewer 建 Host-TURN peer 边。凭据不得进入应用页面 URL、日志、浏览器持久化或 SQLite;TURN 凭据和 Screener route grant 不进入任何 URL,LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target。HTTPS/WSS 继续独立使用 TLS/TCP。+- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。+- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers,普通边不得预发 TURN candidate。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的顺序是保持既有 logical edge,必要时 direct/STUN 后使用 exact selected TURN;只有 logical ingress 不可用时才使用当前 Host publication 的 SFU subscription。Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU publication,而不是逐 Viewer 建 Host-TURN peer 边。凭据不得进入应用页面 URL、日志、浏览器持久化或 SQLite;TURN 凭据和 Screener route grant 不进入任何 URL,LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target。HTTPS/WSS 继续独立使用 TLS/TCP。- 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接;视频 codec 首个可交付切换边界是在分享已显式暂停时执行有界重协商,未暂停热切换是后续复用同一事务的扩展。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。-- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把任何 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先用 pinned LiveKit 2.22.0/1.13.5 的标准两层 screen-share simulcast,在 Dynacast off 下常驻 exactly `HIGH+LOW`,让内建 per-subscriber BWE 独立降层和恢复。若该 gate 通过,Screener 不实现媒体层 selector。首 gate 使用 zero-descendant SFU leaf;root-with-children 的自动 downshift 与有界迁移是 default-on 前独立硬门。只有内建选择不满足门槛时才用标准 subscriber quality 显式限制,常驻成本不合格时再测标准 sender 手动启停。`LOW` 停编只是资源优化;active representation/layer 硬上限为二,禁止按 viewer 增长。必须实测实际接收层、硬件编码证据、游戏 FPS/p1 low、CPU/GPU、区间 encode cost、上传和分层 bytes。当前 Web P2P simulcast 缺少 receiver 选 RID 和跨 PeerConnection shared-encode 契约;当前 Web/LiveKit SVC 也缺少 direct/peer 独立选层与可移植硬件保证,且 pinned screen share 强制三层 temporal-only `L1T3`,二者按现契约静态 no-go。全部标准路径失败后才考虑 custom/native dual encode。没有合格 hardware/power-efficient 路径或额外表示破坏游戏/上传预算时 fail closed:保护健康路径并明确显示弱路径降级或不可用。-- 路径级质量状态:应用的 `HIGH`/`FALLBACK` 非对称窗口只决定拓扑资格和诊断,不命令正常的媒体层切换,也不计算综合分数。`EdgeHealth(parent, child)` 只控制该 child 的换父;`RelayEligibility(parent)` 仅适用于 relay parent,按 `eligible -> suspect -> draining -> ineligible` 控制其是否接收新 child 以及是否排空现有 children。同一 edge 的 C+B 只处理该 child。仅靠 downstream evidence 退位时,当前 authoritative children 必须不止触发 edge 一条,且每条 current child edge 都各自完成有界、当前代的 unusable 证明;任何 current child 的正进展、未知值或未完成证明都阻止 parent drain,正进展清除该 exact edge 的失效证据。只有一个 current child 时只迁走该 child,parent 不靠该 edge 退位。relay parent 自身 ingress 失败先触发本地修复并进入 `suspect`;parent/session hard failure 或修复失败可独立 drain,不等待另一条 child edge。只有服务端可验证且作用域明确为整个 endpoint 的 sender/resource failure 才能独立 drain;普通单 edge `route-failed` 不具备该作用域,在具体 producer 落地前该触发项 fail closed。Host source 走 publication repair/child migration,不走 parent reparent。退位时仍健康的 ingress 保留,失效 ingress 在同一 bounded target 中替换或移除;无目标 child 进入有界等待或失败,更长的稳定证明和 cooldown 后才恢复 `eligible`。Viewer 请求必须鉴权、限频、去重,并由 sender 的 GCC/Transport-CC、实际码率、RTT、丢包、重传、编码限制、协商 codec/profile/parameters 与 viewer 解码、丢帧、冻结证据交叉验证;不能仅凭自报生效,也不得上传 raw SDP、candidate 地址或原始设备/网络标识。-- 断线恢复:临时网络变化只触发整体路由模型授权的有限恢复动作;任一步成功即停止,失败最终进入明确等待或有界失败。`connecting`/`checking` 先显示不改变拓扑的慢连接状态,硬超时必须由真实移动网络证据确定。所有异步结果受 session、route revision、assignment/connection generation 约束,未受影响分支保持健康,Host 只看到不含 URL、地址、token 或原始错误的阶段信息。质量证据只改变 edge 或 parent eligibility,不创建第二个 route controller。+- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先使用 pinned LiveKit 的标准两层 screen-share simulcast,让内建 per-subscriber BWE 独立降层和恢复,Screener 不实现媒体层 selector。应用只诊断实际接收层、硬件编码、游戏性能、资源和上传;SFU 自动降层不改变拓扑。`LOW` 停编只是资源优化,active representation/layer 硬上限为二且不随 viewer 增长。当前 Web P2P simulcast 与 Web/LiveKit SVC 不能证明跨 direct/peer 共享编码或可移植硬件路径;全部标准路径失败后才考虑 custom/native dual encode。+- 路由失效输入:应用不推断 parent-wide 质量,也不计算综合分数。当前 authenticated child 只在 PeerConnection `failed/closed`,或非权威暂停时一个统一 deadline 内没有新解码帧时,使自己的 exact edge 失效并唤醒同一个 reconcile。低码率、低 FPS、模糊、sender/viewer stats 与 SFU layer 只用于 stock WebRTC/LiveKit adaptation 和诊断。relay 自身 ingress 失效时,它作为 child 换父并保留 subtree;disconnect 或 effective downstream capacity 降低只让 direct/overflow children 逐个走同一事务。+- 断线恢复:临时网络变化先交给 WebRTC/LiveKit 的 ICE、consent、重连和流状态。应用只在上述 exact edge 失效后运行一次有界 reconcile;任一步成功即停止,失败进入明确等待或有界失败。所有异步结果受 authenticated session、share generation、base/pending route revision 与 candidate connection identity 约束,未受影响分支保持 sticky。权威暂停 abort 未提交 candidate、保留 active graph、抑制 stall,并在 resume 后重新 reconcile。- 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、RTP 丢包率、抖动、码率、帧率、编码耗时和受限原因。候选与错误的 wire、日志和导出只使用[低服务器成本媒体路由](./research/low-server-media-routes.md)的脱敏字段和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText` 或网络标识。只有创建该 `RTCPeerConnection` 的本机可在折叠详情中显示浏览器对 selected local/remote candidate 实际暴露的地址与端口;该值不上传、不持久化、不用于地理/NAT 推断,缺失或被隐私保护时显示未知。- 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;Host 的 Viewer 卡片只把本机连接或当前接收证据称为“已连接”,其余状态保持中性的“线路分配中”或具体连接状态,不把 active assignment 当作连接成功。展开连接详情也只在当前媒体证据成立后显示媒体方式:`P2P` 使用绿色与直观图标,`SFU` 使用黄色的 `SFU fallback`;实际 relay 时另标 `TURN`,只有本地 relay protocol 可见时才附加 `/UDP` 等实际值。尚未连接时不预告 P2P、SFU 或未知 ICE,只保留中性状态。Host/Peer 上下游仍只在独立的权威拓扑视图中展示。传输协议、候选路径、RTT、视频/音频 RTP 区间丢包率、实际编解码器、音频区间码率/jitter 和视频编码耗时等技术详情由一个明确的“显示连接详情”开关展开。远端 Viewer evidence 的详情 shell 在同一 viewer/parent/connection/route identity 内保持稳定;非空字段从各自最后一次实际观测起精确保留五秒,`connecting`/`disconnected` 只降为非 fresh,`failed`/`closed`、identity/session/share/route 变化或非单调 sequence 则清空/换代。非 fresh evidence 不得继续证明“已连接”或被其他 current-state 消费者使用。音频 codec MIME、RTP clock、channels 与 fmtp 只能来自当前 RTP 对象引用的 `RTCCodecStats`,缺失即未知;`opus/48000/2` 不得写成 48 kHz 音源或实际立体声。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限或需要用户操作的告警。- 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}`、`/join` 和 public-watch 必须先持有效站点 cookie,之后才检查房间 public/private policy 和房间密码。失败统一且不得泄露房间是否存在或 policy;建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、JWT、服务端 session Map 或通用 logout。@@ -42,7 +42,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- 本地自包含一键包:提供 Windows、macOS 和 Linux 可分发的桌面包,在分享者电脑上同时运行 Host、当前 Web/信令应用服务器和本地状态,朋友继续通过普通浏览器邀请观看。安装后启动不要求源码 checkout、Node 或任何外部 Screener、STUN、SFU、TURN、隧道或 relay 服务;它尽力使用本机可达入口和 direct P2P,但必须明确报告公网入口、可信 HTTPS/WSS、网关映射或 NAT 路径缺失,不能承诺任意 CGNAT/严格防火墙必通。两种分发包都排在当前功能、路由、NAT 和真实网络 TODO 完成之后。- 私密房间双入口:private room 接受现有 `/r/{code}#v={grant}` 合法邀请直接进入,或“站点访问 + 房间号 + 该房间观看密码”。没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,通过后才显示明确标为“加入房间”的当前房间密码输入;有效 site-access cookie 直接跳过第一步,但两类密码不得复用、代填或互相替代。Host 可设置、轮换或移除房间观看密码。密码接受 1 至 64 个可见 ASCII 字符;异步 scrypt 全局最多执行 2 个、等待 16 个派生。站点口令和房间密码都不得进入 URL/query/storage/log/SQLite;不存在、错误密码、队满和正确密码后的满房都返回通用结果。-- 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,所有正常房间使用同一个服务端 route controller,并各自保存 assignment、session、route revision、assignment generation、connection identity、media-binding generation 和容量状态。controller 是 committed 与 pending media graph 的唯一 owner,只执行 allocate/distribute、child reparent 和 relay abdicate/drain;topology helper 只保存参与者 metadata 并纯函数规划候选,不能维护或回灌另一份 mutable failback graph。committed media graph 必须无环、每名 Viewer 同时至多一个 active upstream,且每个 active Viewer 必须沿 peer edges 到达 Host 或沿当前 authoritative Host publication 到达 source。加入、容量释放、节点离开、当前边失败或已接受的 path-health evidence 只开启一次有界重选;其余健康分支保持 sticky,不做常驻多源、周期评分或全房重平衡。候选先按当前身份、source reachability、无环、深度、sender slot、relay eligibility、failed-edge/cooldown 和 server admission 做硬过滤,再按最小结果深度、最多剩余稳态 sender slots、稳定加入顺序和 peer identity 确定性排序;一次只准备一个候选,以浏览器 ICE 和当前代媒体证明决定是否采用,失败才尝试下一个。初次加入或 hard failure 接受达到媒体可用门槛的首个候选;soft-quality reparent 还必须由 quality owner 证明候选达到恢复门槛并优于仍健康的旧 edge,否则回滚后试下一个。raw IP、地理位置、UA、自报 NAT 类型、未与 current-generation media 相关的单边 RTT 或跨 edge 加权分数均不得进入排序。迁移保留旧边,只有 exact current candidate 取得 live track、正 RTP 和 decoded-frame progress 后才原子 commit;失败、超时、代次变化或授权撤销销毁候选并保留或恢复旧权威。普通 peer 始终 STUN-only。SFU 与 TURN 使用各自的 typed admission/ledger,并由同一个有界 route transaction 约束 overlap、commit、drain 和 release。该能力不增加用户拓扑选择、百分比发布或第二套路由器。+- 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,每个房间使用一个服务端 route controller,独占 committed graph、一个 pending child operation 和 event-driven reconcile。topology helper 只保存 participant metadata 并纯函数生成确定性 candidate list,不维护另一份 graph。operation 持有 candidate cursor、一个 current candidate/资源预留和一个总 deadline。committed graph 必须无环、source-reachable,且每名 Viewer 同时至多一个 active upstream。加入、容量变化、节点离开、exact edge `failed/closed`,以及非暂停状态下的 decoded-frame stall 都只唤醒同一个 reconcile;其余健康分支保持 sticky。候选按当前身份、source reachability、无环、effective capacity、sender/overlap slot 和 server admission 硬过滤,再按结果深度、剩余 sender slots、稳定加入顺序和 peer identity 排序。candidate child 解码出第一帧新画面后 commit;candidate 失败推进 cursor,operation 总 deadline 或耗尽才进入 waiting/failure。relay 自身 ingress 失效时作为 child 换父并保留 subtree;relay disconnect 或 effective capacity 降低时让 direct/overflow children 逐个走同一事务,childless 后删除 disconnected relay。房间 admission 和无环天然约束最大深度,深度只观测并参与浅层优先排序,不设独立 hard cap。普通 peer 始终 STUN-only,SFU/TURN 使用独立 admission。- 观看端连接反馈:Viewer 舞台从鉴权到首帧使用一个由现有权威状态推导的稳定阶段反馈,至少区分等待分享、分配线路、建立 P2P、连接备用线路、等待首帧、浏览器阻止自动播放、恢复连接和有界失败。阶段不是进度百分比,也不产生 route authority;只有当前 video element 实际提交首帧后才显示正在播放。播放按钮只在 `play()` 因自动播放策略被拒绝时稳定出现,连接中不得忽隐忽现;明确失败后才提供一次受现有 controller 约束的重试入口。make-before-break 或仍有可见旧帧时保留画面并叠加恢复状态,不为显示反馈主动清空健康 media element。- 质量控制扩展:推荐档位仍是默认入口;“分享高级设置”只允许 720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好、`自动 | H.264 | VP8` 编码选择,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;初始值采用 `balanced`、`automatic` 与 128 kbps。视频档位和音频档位在直播中显式应用;音频变更只更新固定 Opus 路径的 sender ceiling,不是 codec 切换。所有当前及以后建立的 Web Host、Browser relay 与 SFU sender 都读取最新 desired 档位,并各自在 fresh sender parameters 上应用和读回 endpoint-local applied 值;实际码率仍由浏览器拥塞控制和 stats 决定。Peer 只在唯一明确的 active Opus audio 上做结构化、幂等的 Viewer answer `stereo=1;maxaveragebitrate=256000` 变换,使同一接收上限覆盖三档;非目标形态或 parser/writer 异常必须原样保留浏览器 answer,不得阻断可继续的 mono/video edge。不得用宽泛字符串/正则改 SDP,也不得改写浏览器协商的 FEC。SFU 将三档映射到 pinned SDK 的 music stereo preset 或显式 256 kbps ceiling,统一保留 `forceStereo = true`、`dtx = false` 与 pinned room default `red = true`。不得暴露任意码率、声道、采样率、audio codec、stereo、DTX、RED 或 FEC 控件;256 kbps 只是显式较高上限,不是无损、高保真或最低码率保证。实际质量持续低于所选上限时必须显示可解释的限制原因;在真实拥塞、编码器和接收端证据完成前,不把任一组合称为“完美平衡”。未来 microphone voice 若进入范围,必须是独立 track/处理链,不能把 AEC/降噪/DTX 套到电影或游戏音频。- SFU 质量设置生命周期:直播中修改档位时,浏览器 sender 的 applied readback、LiveKit `LocalVideoTrack` 保存的 degradation preference、track restart options 与 `LocalTrackPublication` 的 republish options 必须作为同一次串行操作更新;任一步失败恢复旧 sender 与旧 SDK 保存态,旧 publication generation 不得回写当前状态。LiveKit full reconnect/republish 不得恢复初次发布的旧偏好。该修复不改变 codec、码率上限、层数或路由,也不能单独解释即时低帧。@@ -52,7 +52,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- 原生 shared encode relay:具备原生 relay 能力的非服务器端点同样受统一服务端权威下游容量约束,并应复用兼容编码输出而不再次编码。当前普通浏览器 relay 使用逐边重编码的标准 WebRTC 路径,不伪称 shared encode。- SVC 重开条件:当前标准 Web/LiveKit SVC 已静态拒绝为 `no-go-web-svc-cross-path-hardware-contract`。sender `scalabilityMode` 没有 direct/peer receiver 对应的按层选择或跨 PeerConnection shared-encode 契约;requested/applied mode、Media Capabilities `powerEfficient` 和 RTCStats encoder 字段也不能证明没有静默软件 fallback。Pinned client 2.22.0 还会把 screen-share SVC 覆盖为三层 temporal-only `L1T3`,不满足低分辨率 base 与最多两层。只有未来 native sender 能明确选择硬件编码器、最多发布两层、将同一编码输出复用于 direct/peer/SFU、保持每条路径独立选择并通过真实游戏和亚秒延迟门槛时,才可用新的 capability decision 重开 SVC;不能把浏览器 API 支持或 UA 推断当成采用理由。- 分包/分层多树实验:把编码包、对象或可独立解码层拆到多个 peer 路径以分散上传,只能在独立 spike 中验证。必须保持亚秒级,处理多父重组、排序、丢包恢复、关键帧、同步和节点退出;未通过门槛前不进入产品路由控制器。-- SFU/TURN 中央兜底:产品部署可以提供有界 SFU 与可选 TURN 资源,但不要求用户选模式,也不得默认变成整房 always-SFU。只有 Host 拥有一个 authoritative publication;SFU-fed Viewer 具备独立出站证明时才可继续 relay,严格受限 Viewer 保持 leaf。TURN 是某条授权 logical edge 或 Host-SFU ingress 的 selected transport,不是拓扑节点。启用 LiveKit fallback 时必须使用专用且关闭 `room.auto_create` 的实例,并显式提供私有 `LIVEKIT_API_URL`、无默认值的正整数 `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;一份 Host publication 占一个 ingress,每份 SFU subscription 占一个 egress,reserved、committed 和 draining generation 都计入容量。单进程全局账本在发 token 前按 exact room/share/publication fence reserve,并先通过 RoomService 创建对应 room;commit、abort、timeout、disconnect、share rollover、room stop/delete 只把 generation 转入 draining,只有 DeleteRoom 成功和 absent readback 才释放计数。启动时必须先拒绝外来 room、清除全部遗留 Screener room 并确认 namespace 为空;Host 信令离线但 LiveKit participant 仍存在时继续保留和计费,participant 消失后有界回收。固定 root 数和普通端点 child 数都不能代替该准入;资源耗尽进入下一条有界候选、明确等待或失败。多应用进程部署必须先引入共享原子 admission/lifecycle owner,不能把各进程本地计数相加冒充全局准入。+- SFU/TURN 中央兜底:产品部署可以提供有界 SFU 与可选 TURN 资源,但不要求用户选模式,也不得默认变成整房 always-SFU。只有 Host 拥有一个 authoritative publication;SFU-fed 与 peer-fed endpoint 使用同一个 provisional-child first-frame transaction,严格受限 endpoint 在没有成功 child candidate 时自然保持 leaf。TURN 是某条授权 logical edge 或 Host-SFU ingress 的 selected transport,不是拓扑节点。启用 LiveKit fallback 时必须使用专用且关闭 `room.auto_create` 的实例,并显式提供私有 `LIVEKIT_API_URL`、无默认值的正整数 `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;一份 Host publication 占一个 ingress,每份 SFU subscription 占一个 egress,reserved、committed 和 draining generation 都计入容量。单进程全局账本在发 token 前按 exact room/share/publication fence reserve,并先通过 RoomService 创建对应 room;commit、abort、timeout、disconnect、share rollover、room stop/delete 只把 generation 转入 draining,只有 DeleteRoom 成功和 absent readback 才释放计数。启动时必须先拒绝外来 room、清除全部遗留 Screener room 并确认 namespace 为空;Host 信令离线但 LiveKit participant 仍存在时继续保留和计费,participant 消失后有界回收。固定 root 数和普通端点 child 数都不能代替该准入;资源耗尽进入下一条有界候选、明确等待或失败。多应用进程部署必须先引入共享原子 admission/lifecycle owner,不能把各进程本地计数相加冒充全局准入。- 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。- Windows 应用音频:Windows 11 Native sender 使用本地 opaque window target 绑定 HWND、PID 与进程创建时间,只捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。- 受限网络增强:短期鉴权 TURN 只有在完整、默认关闭的部署配置和当前 route controller 明确授权时可用;普通 peer PC 从创建起保持 STUN-only,不得向整个 participant、房间或所有 peer connections 预发 TURN candidates。凭据必须绑定 exact room/share/session/route/connection generation,短期有效、内存态、受配额约束且不进入 URL、日志、浏览器持久化或 SQLite。TURN 只替换授权 edge 的 transport;Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。TURN 不得被描述为更高清的传输方式。@@ -60,7 +60,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting### P2 - 可选功能-- 证据驱动的动态 relay capacity:当前只接受统一静态容量 `1`、`2` 或 `3`,默认 `2`,不按角色、设备或 UA 分类。若未来引入运行时升降,必须由独立需求、稳定的 sender/transport evidence、cooldown 和服务端 hard ceiling 共同定义;当前协议能力字段不自行授权动态策略。H.264、hardware encode 或 shared encode 可以降低编码成本或同观感码率,但每个 ordinary child 仍消耗一份网络副本。+- 运行时有效容量:部署的 steady cap `C` 仍只接受 `1`、`2` 或 `3` 且默认 `2`,不按角色、设备或 UA 分类。服务端把 authenticated endpoint 当前广告的 `0..C` 可用值 clamp 成唯一 `effectiveDownstreamCapacity`;`0` 表示当前不承担下游,不是另一套 release tier。controller 通过同一个 reconcile 迁移 deterministic overflow children。H.264、hardware encode 或 shared encode 可以降低编码成本或同观感码率,但每个 ordinary child 仍消耗一份网络副本。- 原生 Windows 捕获辅助程序:显式 `native-window-h264` 模式使用同一 bound window target 的 WGC/D3D11 画面与 WASAPI process-tree PCM,并用 adapter-bound、hardware-only Media Foundation H.264 `42c01f` 直接进入现有 Go fanout;普通 Web Host 独立采用默认 `automatic`、可显式选择 H.264/VP8 的标准协商路径,不允许运行时静默改用软件编码、显示器画面或系统混音。一名普通 Chrome Viewer 已 decoded/rendered 203 帧并收到 500 Opus packets,同一 helper PID/adapter 的 `VideoEncode` 与 LUID 匹配。- Viewer 向电视输出:系统级屏幕镜像现在可直接使用;产品只复用平台 AirPlay/Cast,不自造投屏协议。截至 2026-08-21,Chromium 的 Remote Playback URL 路径和 WebKit 明确拒绝 wireless target 的 live `MediaStream` player 均未给当前 WebRTC `srcObject` 提供可用契约,因此不显示伪可用入口。只在浏览器实现明确支持并由实体 Apple TV 或 Chromecast/Google TV 证明当前 live 画面与音频后,才按通过的平台加入 Viewer 本地图标按钮。投屏不能改变 room、TURN/SFU/peer route、Host fanout 或服务端媒体分发;Google Cast receiver 需要可获取的媒体 URL,当前 P2P `MediaStream` 不满足该输入,因此不加入 Cast SDK/receiver。- 多地区 server-assisted ingress/egress 调度,以及可选 TURN 兼容层的按地区、运营商可达率。@@ -86,7 +86,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- Production 当前八名观看者和 1 至 16 配置范围只是接入边界,不承诺任意机器、档位、网络或跨洲路径都稳定承载;任何未来 admission 变化另行决策和验收。- 浏览器规范要求每次由用户主动选择分享源,权限不能永久保存;纯网页不能保证指定游戏窗口或始终获得系统音频。- 1080p60 是能力目标,实际分辨率、帧率和硬件编码由浏览器、GPU、驱动、画面复杂度及网络共同决定。-- 旗舰 release 的正常房间都可使用同一自动 controller;部署未启用总开关的轻量实例才保持标准 WebRTC P2P。Peer relay 只复用标准 remote-track WebRTC,不加入 Encoded Transform/DataChannel/WebCodecs 媒体协议,也不自研 UDP、编解码器、拥塞控制、FEC/RTX、多树、转码、codec ladder 或综合评分器。独立 native shared encode sender 不在本实验内;跨模式迁移受 ADR-0005 的 identity、generation、media proof 和 typed resource admission 共同约束。+- 旗舰 release 的正常房间都可使用同一自动 controller;部署未启用总开关的轻量实例才保持标准 WebRTC P2P。Peer relay 只复用标准 remote-track WebRTC,不加入 Encoded Transform/DataChannel/WebCodecs 媒体协议,也不自研 UDP、编解码器、拥塞控制、FEC/RTX、多树、转码、codec ladder 或综合评分器。独立 native shared encode sender 不在本实验内;跨模式迁移受 ADR-0005 的 exact attempt、candidate-child first frame 和 typed resource admission 共同约束。- GPL/AGPL 项目在许可证策略确认前仅用于研究,不能直接复制到计划闭源的产品中。## 验收标准@@ -113,10 +113,10 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- Given 两端网络允许 UDP 打洞,When 观看者加入,Then `getStats()` 显示选中的候选对不是 `relay`,且服务器没有承载媒体流量。- Given ordinary peer edge 被创建或重建,When 检查其 ICE 配置,Then 只包含部署 STUN,不包含预发给 participant、房间或普通 peer 的 TURN candidate。-- Given route candidate、signal、recovery 或 commit 的 room/share/session/revision/assignment/connection/media-binding identity,及适用时 publication generation,任一不匹配,When 旧消息或异步结果到达,Then 该操作 fail closed 且不能替换当前媒体。-- Given 新路线正在准备,When 尚未同时证明当前代 live track、正 RTP 与 decoded-frame progress,Then 旧路线保持权威;证明后只原子提交 exact candidate,失败或超时销毁候选并保留或恢复旧路线。+- Given route candidate、signal、recovery 或 commit 的 authenticated room/endpoint session、share generation、base/pending revision 或 candidate connection identity 任一不匹配,When 旧消息或异步结果到达,Then 该操作 fail closed 且不能替换当前媒体;SFU publication generation 继续由 resource owner 单独验证。+- Given 新路线正在准备,When exact candidate child 尚未解码出第一帧新画面,Then 可用旧路线保持权威;首帧后只原子提交该 candidate,失败或统一 deadline 到期销毁候选并保留或恢复旧路线。- Given 所有已接受且已配置的媒体路径耗尽,When 有界连接窗口结束,Then 界面显示通用等待或连接失败,不静默黑屏、不长时间假连接,也不尝试未授权路径。SFU/TURN 的精确 path order 和 resource accounting 按 ADR-0005 验证。-- Given 同一 committed graph 和候选集合以不同枚举顺序输入 controller,When 新 Viewer 加入或 exact failed edge 触发换父,Then 硬过滤结果相同,选择稳定落到最浅且分配后剩余容量最多的合格 parent,并以加入顺序和 peer identity 打破平局;健康 current edge 不因出现更优候选而迁移。Given 第一候选 ICE 或媒体证明失败,Then controller 先幂等清理该候选再尝试下一候选,且不会启动 all-pairs probe;若候选创建了受管 SFU room,其 server capacity 在删除并证明 room 不存在前仍计费。+- Given 同一 committed graph 和候选集合以不同枚举顺序输入 controller,When 新 Viewer 加入或 exact failed edge 触发换父,Then 硬过滤结果相同,选择稳定落到最浅且分配后剩余容量最多的合格 parent,并以加入顺序和 peer identity 打破平局;健康 current edge 不因出现更优候选而迁移。Given 第一候选 ICE 或首帧失败,Then controller 先幂等清理该候选再尝试下一候选,且不会启动 all-pairs probe;若候选创建了受管 SFU room,其 server capacity 在删除并证明 room 不存在前仍计费。- Given owned endpoint-dependent NAT emulator 中 ordinary ICE 可重复失败,When isolated guessed-candidate harness 运行,Then 只有满足[低服务器成本媒体路由](./research/low-server-media-routes.md)的 candidate budget、双浏览器重复性、首帧 deadline、隐私和 cleanup gate 才可继续。门禁前 ordinary room 不接收 guessed candidate;门禁后也只允许一个人工批准的 operator-owned test room,在双方 endpoint 显式同意、default-off kill switch 以及 exact room/edge/ICE-generation/deadline/aggregate-budget 约束下运行 canary。任何失败都关闭该候选并保留现有 SFU/TURN fallback。### 浏览器与移动端观看@@ -139,7 +139,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- Given peer-assisted host 鉴权或直播中连续修改质量设置,When 服务端校验其分辨率、FPS、码率和偏好,Then 只有 host 的完整有界设置被接受,last-wins 地应用到当前和以后建立的 relay child sender 以及启用的 SFU publisher;越界、缺字段和多余字段被拒绝,普通 P2P 的鉴权 wire 不新增该字段且不接受同步消息。- Given 标准浏览器把收到的 remote track 直接加入下游 `RTCPeerConnection`,When 检查 relay 统计和 libwebrtc 路径,Then 明确记录新的 outbound encoder、编码耗时和 CPU/GPU 限制,不把它当作 encoded forwarding 或 shared encode 成果。- Given ADR-0004 的任一硬门槛只有在引入 Encoded Transform/DataChannel/WebCodecs 媒体、自定义拥塞控制、FEC/RTX、多树、综合评分、转码、codec ladder、浏览器 RTP 注入 hack 或放宽 endpoint capacity 后才能满足,When 结束 bounded spike,Then 放弃并删除该浏览器 relay 实验路径,保留标准 P2P 与整体路由模型已接受的 fallback;后续 native shared encode sender 仍按独立 ADR 推进,但不能据此把失败的 relay 拓扑判为通过。-- Given 新观看者会使预计总上行超过安全预算,When 其请求加入,Then 系统只选择整体路由模型已授权且满足配置容量与资源准入的路径;没有合格路线时明确等待或拒绝,而不是创建超过配置容量的 ordinary edge 或持续堆积发送队列。各 transport 的拥塞控制适应该路径,应用证据只改变拓扑资格,不能合成全房降档。+- Given 新观看者会使预计总上行超过安全预算,When 其请求加入,Then 系统只选择整体路由模型已授权且满足配置容量与资源准入的路径;没有合格路线时明确等待或拒绝,而不是创建超过配置容量的 ordinary edge 或持续堆积发送队列。各 transport 的拥塞控制适应该路径,诊断证据不改变拓扑或合成全房降档。- Given SFU 或 TURN 参与路线,When 计算准入、迁移 overlap 或失败恢复,Then 同时检查统一端点容量和独立的 server ingress/egress、SFU、TURN 资源预算;不得把普通端点 child 数当作 server cap,也不得借兜底形成无界整房 fanout。- Given 配置完整 LiveKit credential tuple,When `LIVEKIT_API_URL` 缺失或不是允许的 control-plane origin,或 `SFU_INGRESS_CAPACITY` / `SFU_EGRESS_CAPACITY` 缺失、非正整数或超出 JavaScript safe-integer 范围,Then 服务必须在启动时 fail closed。Given 配置有效,When startup listing 出现非 Screener room、遗留 room 无法删除、删除后仍存在,或 exact candidate room 无法显式创建,Then 应用不得签发 token 或接受可能重复计算的 SFU generation。Given 当前 reserved、committed 与 draining 的 ingress 或 egress 会越过任一部署容量,Then controller 必须在签发任何新 SFU token 前拒绝该 candidate,并保持旧 route 和计数不变。Given generation 被 commit、abort、timeout、stop、delete 或 Host participant 离线回收,When DeleteRoom 尚未成功或 absent readback 尚未完成,Then 它必须继续占用账本资源且旧 token 不能创建 room。- Given 配置 selected TURN,When 四项 tuple 不完整或 `SELECTED_EDGE_TURN_ALLOCATION_CAPACITY` 不是正 safe integer,Then 服务在启动时 fail closed。Given 配置有效,When exact peer-selected edge 或 Host-SFU ingress 申请 credential,Then 同一个 deployment ledger 必须先 reserve `1`,并让 reserved、committed、draining authorization 持续计费至 exact logical release;容量耗尽保持旧 route 并走现有有界候选、等待或失败。Given stale room/share/session/revision/connection identity、重复 release、停止分享、删房或 shutdown,Then 只能释放匹配 authorization,不能误扣其他 edge。@@ -149,20 +149,16 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- Given 用户选择任一推荐档位或高级质量参数,When 接收端实际分辨率、帧率或码率持续显著低于该目标,Then 诊断数据能区分采集约束、发送编码、带宽/拥塞、TURN 路径和接收端限制;产品不得只改变档位标签却继续隐藏实际降级。- Given 一个健康 SFU leaf 和一个受控弱 SFU leaf 都以 `HIGH` ceiling 订阅,When 内建 LiveKit BWE 运行,Then 弱 leaf 自动使用唯一共享 `LOW` 并在恢复后回到 `HIGH`,健康 leaf 不受影响,且 Screener 没有实现媒体层 selector;direct/peer 继续使用各自的 stock WebRTC GCC。-- Given 一个 Viewer 观察到自己当前 upstream 的接收效果差,When 当前 Viewer 的 `viewer-quality-evidence` 与 parent 对同一 edge 返回的 `parent-edge-quality-evidence` 按 exact route identity(room/share、双方 session、assignment/connection/media-binding generation、route revision,及适用时 publication generation)和 sequence 连续相关,Then 只为该 Viewer 创建 child-scoped reparent intent,排除旧 parent,按 reserve/proof/commit/rollback 换父;不得直接把 parent 全局判坏。-- Given Viewer 的 exact current ordinary peer upstream 在信令和 PeerConnection 仍存活时停止产生当前代 RTP 与 decoded-frame progress,When 有界 parent-proof deadline 到期后该停滞仍成立,Then controller 不论是否收到 matching positive non-server-parent outbound-media proof,都只把该 logical edge 作为 hard child-scoped reparent 处理,并以 exact generation、一次候选、媒体证明和有界失败约束恢复该 Viewer;parent 的正发送证明或未回应都不改变 `RelayEligibility(parent)`,也不得冒充 parent/session hard failure。-- Given relay parent 至少还有一条不同的 current authoritative sibling edge,When 每条 current child edge 都各自完成当前代 unusable 证明且没有任何 edge 为正进展、未知或未决,Then downstream-only corroboration 才能把 parent 标为 directional-ineligible 并进入 `draining`;成功换父或 current-generation 正进展清除对应 exact edge 的失效证据,只有一个 child 时只迁该 child。Given parent/session hard failure 或自身 ingress 修复失败,Then 可独立 drain;Given 只有普通单 edge `route-failed` 且没有服务端可验证的 endpoint-wide sender/resource producer,Then 不得把它提升为 parent-wide failure。drain 停止新 child、保留健康 ingress、在同一 bounded target 中替换或移除失效 ingress,并迁移可行 children;无候选 child 进入 waiting/bounded-failure,不得阻塞其他 child。Host source 走 publication repair/child migration,不进入 relay-parent reparent。-- Given exact edge 的 room/share/session/connection/media-binding identity 在新 active revision 中未变化,When unrelated sibling、join、abort 或 route broadcast 发生,Then 其未过期质量证据只更新 revision guard 而不被全房清空;身份变化只清对应 edge。Given 当前分享处于权威 paused generation,Then 停止并清空该 generation 的质量关联,resume 后从 fresh baseline 重新采样,主动暂停的无 RTP 不得触发换父或退位。-- Given 一个路径的 sender/viewer 证据跨连续窗口确认 `FALLBACK`,When 应用更新状态,Then 只改变其 edge/parent 拓扑资格和诊断;不得重复命令内建媒体层。更长稳定恢复窗口和 cooldown 后才可重新声明 relay capacity。-- Given 同一 Viewer 同时是某人的 child 和其他人的 parent,When 其自身 ingress 发生 hard/confirmed failure,Then child-scoped reparent 或 branch-preserving `replaceIngress` 优先修复它,同时将其 relay eligibility 置为 `suspect` 并停止新分配;新 ingress 恢复下游媒体时保留子树,只有修复失败或 all-of-current downstream corroboration 成立时才执行 parent drain。C+B 可同时贡献该 exact edge 的证据,但 controller 只提交一个 target revision;成功的 child reparent 只使同一旧 logical edge 的 pending evidence 失效,其他仍匹配且未过期的 sibling evidence 保留。-- Given SFU BWE 在应用确认前把一个仍有 children 的 root 瞬时降层,When 收到该观测,Then 先标记 `suspect`;随后由 ADR-0005 的 exact scope 选择 local repair、child reparent 或 parent drain。只有进入 parent-drain 分支才迁走 children 并进入 `FALLBACK`,不得稳定保留 confirmed `FALLBACK` parent。默认启用前必须在 root-with-children gate 中记录并限制这段不可避免的 descendants 短暂画质影响,不能声称 packet-level 先迁后降。+- Given 当前 Viewer 的 exact edge 进入 `failed/closed`,或在非权威暂停时超过统一 deadline 没有新 decoded frame,When 服务端确认 authenticated child、share generation、active revision 与 connection identity 仍匹配,Then 只把该 child 送入同一个 reserve/prepare/first-frame/commit-or-abort 事务;低码率、低 FPS、模糊和 SFU layer 只进入诊断。+- Given 同一 Viewer 同时是某人的 child 和其他人的 parent,When 自身 ingress 失效,Then 它作为 child 换父、在新 ingress 首帧提交前保留可用旧 edge,并保持 subtree。Given endpoint disconnect 或 `effectiveDownstreamCapacity` 降低,Then controller 只保留稳定顺序内可容纳的 children,并将 deterministic overflow children 逐个送入同一事务;childless 后删除 disconnected relay。+- Given 当前分享权威 paused,When 新 Viewer 加入、edge 失效或已有 child operation 尚未提交,Then abort 整个 pending operation 及其 current candidate/预留、保留 active graph、让新 Viewer waiting,并且不因没有 decoded frame 触发恢复;resume 后从当前 graph 重新 reconcile。- Given exactly-two publication 的实测 encoder/CPU/GPU 或上传成本超过游戏预算,或没有合格 hardware/power-efficient 路径,When 评估该候选,Then 保留健康路径并明确显示弱路径降级或不可用,不得退回全房间最低目标或静默软件编码;若 supported sender cohort 无法以常驻或按需方式提供共享 `LOW`,Then 质量验收失败,必须优化编码路径或明确标记不支持。- Given 同一时刻采集、host outbound 与 viewer inbound 证据,When 进行根因分类,Then 关联派生后的实际协商视频 codec/profile/parameters、适用时的 `scalabilityMode` 与真实解码表现,依次区分 Capture 低、Capture 高但 outbound 因 CPU 低、Capture 高但 outbound 因 bandwidth 低、outbound 正常但 inbound 低、以及 inbound 正常但肉眼模糊五类;不用 UA 或设备型号代替运行时证据,也不上传 raw SDP。- Given Viewer 发送低档请求,When 请求未鉴权、过频、重复、过期或没有匹配的 sender/viewer 统计,Then 请求不改变表示或路径状态;有效请求也只能作为交叉验证输入。- Given 受控 RTT/丢包测试条件,When 连续分享高动态游戏画面 30 分钟,Then 延迟、帧率与丢帧达到上述目标,且没有不可恢复的冻结。- Given 部署版出现游戏低帧、持续 `bandwidth` 限制或只有 Host 刷新才能恢复,When 归因该报告,Then 用同一机器、浏览器、驱动、游戏场景和单个有线 direct Viewer 对照精确 release `769de201f7cc` 与最新 `main`。每次从独立重新确认的 affected state 只执行 `observe`、重建该 `HostPeer`、替换 capture、Host reload 或本地预览 cycle 中一个动作;codec A/B 另用新的 Host/share/PeerConnection 分别请求 `automatic/H.264/VP8` 并校验实际 codec,不把 codec 变更混入生命周期动作。记录 capture A、sender B、Viewer C 的同代重叠窗口、游戏 FPS、CPU 与进程级 GPU encode;可选 encoder implementation/power-efficient 字段缺失只记 unknown,不能把部署版报告直接归为最新代码或 H.264 缺陷。- Given 分享过程中切换 Wi-Fi/有线网络,When ICE 连接失败,Then 客户端触发 ICE restart,并在成功或超时后给出明确状态。-- Given 当前路径仍可播放且控制器准备迁移 logical parent 或替换 transport,When 候选路径拥有模型授权的 overlap 资源,Then 旧路径保持权威,直到候选的 exact current generation 出现正向 RTP、解码帧进展和 live video 后才原子提交;ICE `connected` 单独不能触发切换。+- Given 当前路径仍可播放且控制器准备迁移 logical parent 或替换 transport,When 候选路径拥有模型授权的 overlap 资源,Then 旧路径保持权威,直到 exact candidate child 解码出第一帧新画面后才原子提交;ICE `connected` 单独不能触发切换。- Given 候选没有准入资源,或 provisional 路径失败、超时、代次过期、参与者变化、房间停止、权限撤销或 session 被替换,When 本次机会结束,Then 原路径和未受影响 branches 继续工作,临时资源被销毁,重试遵守模型定义的有界策略。- Given 浏览器未返回系统音轨,When 分享开始,Then 分享者在启播前看到“当前来源没有可共享音频”的提示。- Given 分享者选择标签页或窗口,When 浏览器支持对应音频捕获,Then picker 提供该来源音频而不扩大为系统混音。Given 分享者选择整个屏幕,When 浏览器支持系统音频,Then picker 提供由用户决定的系统音频开关。应用同时请求 `windowAudio: "window"` 和 `systemAudio: "include"`,不根据 track 存在性伪造来源标签。@@ -170,7 +166,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting- Given Web Host、浏览器 relay 或 selected-edge 建立或替换分享音轨,When 对实际音频 sender 应用发送参数,Then 从当次 `getParameters()` 派生所选 `encodings[0].maxBitrate = 64000 | 128000 | 256000`、调用 `setParameters()` 并立即读回,旧配置缺失时按 128000 处理;Given Web Viewer 为含唯一有效 audio/Opus payload 的 offer 生成 answer,Then 用结构化 SDP parser 只 upsert 该 payload 的 `stereo=1` 与 `maxaveragebitrate=256000`,并把同一个结果用于 `setLocalDescription()` 和 signaling。首次连接、ICE restart、同 parent rebuild 和 relay child 都适用;空 SDP、无/歧义 Opus、多个有效 audio、重复目标参数、畸形 fmtp 或 parse/write 异常必须按对象 identity 返回浏览器原 answer 并继续,不能发送部分修改或静默冒充 stereo/实际码率。只有实际 `setLocalDescription()` 失败才进入既有连接错误路径。`sprop-stereo` 与 `usedtx` 不新增,其他 fmtp/FEC/session/media 字段逐项保留。- Given 通过 SFU 发布分享音轨,When 构建 LiveKit 2.22.0 publish options,Then 64 kbps 使用 `AudioPresets.musicStereo`、128 kbps 使用 `AudioPresets.musicHighQualityStereo`、256 kbps 使用同等结构的显式 sender ceiling,三档都设置 `forceStereo = true` 与 `dtx = false`,且不覆盖 pinned room default `red = true`;验收同时核对 SDK 选项、applied ceiling、当前 RTP codec/fmtp 与 stats 实际码率,不能从 preset 名称或 `opus/48000/2` 单独推断实际声道内容。- Given 分享正在直播或暂停且 Host 选择新的 64/128/256 kbps 音频档位,When 当前 profile mutation 串行执行,Then 服务端以 last-wins 保存并广播最新 desired profile,每个当前 Host、relay 与 SFU audio sender 从 fresh `getParameters()` 派生 `setParameters()` 并立即 readback,过期 completion 不得覆盖新值;以后创建的 sender 使用最新 desired profile。单个端点应用失败时保留媒体与其旧 applied 值、显示可见告警并允许后续更新或重建重试,不得谎称全房已收敛。当前 applied readback 保持 endpoint-local;没有显式回执 wire 就不宣称跨端点原子提交。该操作不改变 Opus、route revision、media-binding generation 或 publication generation,也不创建第二个音频控制环。当前 screen-audio Host 基线是 Chrome/Edge;其他浏览器只有实际 sender readback 成功时才算支持。-- Given 分享已显式暂停且 Host 选择 `自动 | H.264 | VP8` 的不同值,When 执行首个视频 codec 切换闭环,Then 为该请求分配单调 codec-negotiation generation,并与 room route mutation 串行;事务开始时冻结 exact current route/media binding target,离开的 Viewer 从 target 移除,新加入者等待事务结束。暂停期间对 target 的 P2P/relay path 完成显式 offer/answer 重协商,并对 SFU 路径完成新的 publication generation/republish;选择 `automatic` 时以空 codec preference 恢复浏览器默认。暂停帧不能充当媒体证明:恢复 source 后,每名 still-current target 发送一个只属于 codec transaction 的 proof,精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation、codec-negotiation generation、实际 inbound codec 与 decoded-frame baseline/delta;该 proof 不进入 EdgeHealth 或 route-quality 判断。若 leave、hard failure 或任何 exact binding 变化使 target 失效,服务端把它移出本事务并标为 `route-wait`,codec 事务在 deadline 内以剩余 target settle 后释放 route lock,controller 再用最终 committed preference 为仍在线 Viewer 恢复路径。只有服务端校验全部仍在 target 内的 proof 后才提交 desired codec。失败时立即重新暂停,按旧 preference 开启有界 rollback generation;rollback 必须证明旧 preference 已重新应用(P2P 空/有序 preference 或 SFU fresh publish options),并由新协商代次报告实际 inbound codec 与 decoded-frame progress,不要求 actual codec 字面等于历史值。回滚失败则保持暂停并显示明确失败,不允许 stale generation 恢复播放。零 current Viewer 或事务中全部离开时直接提交 future-edge desired codec,无需伪造 frame proof。`pause`、`replaceTrack()` 或仅调用 `setCodecPreferences()` 均不能冒充已完成切换;本 slice 是明确的 paused bounded-gap 事务,未暂停 MBB 热切换留作后续扩展。+- Given 分享已显式暂停且 Host 选择 `自动 | H.264 | VP8` 的不同值,When 执行首个视频 codec 切换闭环,Then 为该请求分配单调 codec-negotiation generation,并与 room route mutation 串行;事务开始时冻结 exact current route/media binding target,离开的 Viewer 从 target 移除,新加入者等待事务结束。暂停期间对 target 的 P2P/relay path 完成显式 offer/answer 重协商,并对 SFU 路径完成新的 publication generation/republish;选择 `automatic` 时以空 codec preference 恢复浏览器默认。暂停帧不能充当媒体证明:恢复 source 后,每名 still-current target 发送一个只属于 codec transaction 的 proof,精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation、codec-negotiation generation、实际 inbound codec 与 decoded-frame baseline/delta;该 proof 不进入路由失效判断。若 leave、hard failure 或任何 exact binding 变化使 target 失效,服务端把它移出本事务并标为 `route-wait`,codec 事务在 deadline 内以剩余 target settle 后释放 route lock,controller 再用最终 committed preference 为仍在线 Viewer 恢复路径。只有服务端校验全部仍在 target 内的 proof 后才提交 desired codec。失败时立即重新暂停,按旧 preference 开启有界 rollback generation;rollback 必须证明旧 preference 已重新应用(P2P 空/有序 preference 或 SFU fresh publish options),并由新协商代次报告实际 inbound codec 与 decoded-frame progress,不要求 actual codec 字面等于历史值。回滚失败则保持暂停并显示明确失败,不允许 stale generation 恢复播放。零 current Viewer 或事务中全部离开时直接提交 future-edge desired codec,无需伪造 frame proof。`pause`、`replaceTrack()` 或仅调用 `setCodecPreferences()` 均不能冒充已完成切换;本 slice 是明确的 paused bounded-gap 事务,未暂停 MBB 热切换留作后续扩展。- Given 浏览器返回屏幕音轨,When 产品展示音频状态或未来连接详情,Then 只能把存在性、浏览器实际返回的 track settings、实际协商 codec/fmtp 和实际流量分别标为捕获、协商或观测事实;字段缺失必须显示为未知,且不得从 Opus 的 `48000/2` RTP 声明推断源采样率或实际 stereo。- Given Web 或后续 native sender 分享电影/视频音频,When 进行产品验收,Then 必须用独立 A/B/C 证据关联 capture audio track/settings、实际 negotiated codec/fmtp、outbound/inbound 实际码率、loss、jitter、concealment、jitter-buffer 与 A/V sync;P2P、浏览器 relay 与 SFU route switch 保持同一持久 Viewer `MediaStream`/媒体元素和 stereo 协商,不新增独立 audio element 或 Web Audio 时钟边界。native sender 必须通过该音质和同步矩阵,且不得把 audio `maxBitrate` ceiling 当作提质证明。- Given 分享者同时运行语音软件,When 选择仅分享游戏声音,Then supported Windows 11 native sender 只保留目标游戏及其子进程的渲染音频,观众、通知和其他应用声音不得进入分享;浏览器 system audio 无法满足时必须允许 video-only 或明确告知其可能包含语音/通知,不能用 AEC、降噪或来源标签伪称已隔离。