feat(quality): implement strict v13 quality shadow (#291)

docs/adr/0005-automatic-hybrid-media-routing.md

@@ -1,8 +1,8 @@
 # ADR-0005: Automatic Hybrid Media Routing
 
 - Status: Base routing is deployed on strict v12. The evidence-only quality
-  shadow and atomic strict-v13 upgrade are accepted but not yet implemented or
-  deployed. Exact current identity is owned by
+  shadow is implemented in canonical source on strict v13 but not yet deployed.
+  Exact current identity is owned by
   [status](../status.md).
 - Date: 2026-08-20
 - Last updated: 2026-08-27
@@ -361,8 +361,8 @@ current-candidate-start, first-decoded-frame, and final-outcome timing. A new
 demand overwrites that child's record; authoritative share stop/replacement,
 confirmed departure, and room deletion remove it.
 
-An authenticated Host acceptance harness may request one snapshot. The accepted
-v12 product UI exposes no diagnostic download button. The response
+An authenticated Host acceptance harness may request one snapshot. The current
+product UI exposes no diagnostic download button. The response
 reads the current graph, current operation, and latest records; the server does
 not push a periodic snapshot stream, start a timer, retain an event ring, log or
 persist the result, or create a second graph. Snapshot-local ordinals express
@@ -424,10 +424,10 @@ deployment-wide.
 
 ## Current Source And Deployment Boundary
 
-Production and canonical application/runtime source currently use strict
-`screener-v12`; the accepted quality-shadow integration atomically replaces it
-with strict `screener-v13`. Exact current source
-and deployment identity is indexed by [status](../status.md).
+Canonical application/runtime source uses the evidence-only strict
+`screener-v13` quality shadow; production remains strict `screener-v12` until
+its atomic application release. Exact current source and deployment identity is
+indexed by [status](../status.md).
 Browser SFU PCs use empty external ICE-server lists. The controlled exact-
 candidate rollback/SFU commit and active-SFU cadence gates are closed. The
 operation owner remains only `route`; broader heterogeneous-network and SFU

docs/project-memory.md

@@ -1,6 +1,6 @@
 # Project Memory
 
-Last updated: 2026-08-26
+Last updated: 2026-08-27
 
 ## Current Product Truth
 
@@ -120,13 +120,14 @@ Last updated: 2026-08-26
 
 ## Current Source And Production
 
-- Production and canonical source use the same strict `screener-v12`
-  application with adaptive H.264/VP8 selection, local Host codec override and
+- Canonical source uses the evidence-only strict `screener-v13` quality shadow;
+  production remains strict `screener-v12` until the atomic application release.
+  Both retain adaptive H.264/VP8 selection, the local Host codec override and
   optional SQLite room authority. Exact identities are indexed by
   [status](./status.md).
-- The accepted quality-shadow integration atomically replaces v12 with strict
-  `screener-v13`; old Browser pages must fail before room authority. It adds no
-  active route decision until production shadow evidence is accepted.
+- Strict v13 rejects old Browser pages before room authority. Its bounded
+  current-edge aggregate adds no active route decision until annotated
+  production shadow evidence establishes an accepted policy.
 - Production uses SQLite-backed random rooms, 20-Viewer admission, endpoint cap `2`,
   fixed 9,000-publication ingress and `9000 * 20` subscription egress admission,
   STUN UDP 3478, LiveKit media UDP 7882, and Web TCP 80/443. Node 8787 and
@@ -137,7 +138,8 @@ Last updated: 2026-08-26
 
 ## Current Priority
 
-1. Complete the evidence-only quality-route shadow on strict `screener-v13`.
+1. Deploy the evidence-only strict `screener-v13` quality shadow and collect
+   annotated production samples.
 2. Complete the mobile Viewer lifecycle matrix and representative real-network
    route/media acceptance.
 

docs/research/realtime-quality-adaptation.md

@@ -2,8 +2,8 @@
 
 - Research date: 2026-08-26
 - Scope: Browser game-screen capture, encoding, P2P forwarding, and LiveKit SFU
-- Status: current Browser policy accepted; real-game, weak-device, and
-  heterogeneous-network quality remain open
+- Status: strict-v13 evidence-only quality shadow implemented in canonical
+  source; production sampling and active policy remain open
 
 ## Current Conclusion
 
@@ -354,9 +354,8 @@ page refresh also rebinds the same stable participant and committed graph.
 Only actual recovery exhaustion enters the normal route-failure operation and
 tries other eligible P2P parents before SFU.
 
-Quality-driven relay abdication or active parent switching would require
-counterfactual alternative-path evidence, bounded probing, and a separate
-ADR-0005 decision. It is not implemented or authorized by current diagnostics.
+Quality-driven relay abdication or active parent switching requires evidence
+that current diagnostics do not yet provide. No active policy is implemented.
 
 The reopened quality-selection research retains that information boundary.
 Current-route WebRTC stats can prove user-visible degradation but cannot prove
@@ -374,7 +373,7 @@ quality ceiling as a delivered floor requires a separate product SLO. Relay
 ingress degradation reparents that relay while retaining its subtree; one
 child's degradation moves only that child.
 
-The accepted first stage is shadow evaluation only. Viewer evidence adds the
+The implemented first stage is shadow evaluation only. Viewer evidence adds the
 standard cumulative-renderer deltas `freezeCount`, `totalFreezesDuration`,
 `pauseCount` and `totalPausesDuration` and requires continuing
 `framesDecoded` progress. W3C already

docs/status.md

@@ -42,7 +42,8 @@ This is the current execution index. Git history owns completed timelines;
 
 ## Current Source
 
-- Canonical `main` contains the same application tree deployed from `267e073`.
+- Canonical `main` uses the evidence-only strict `screener-v13` quality shadow;
+  production remains the strict-v12 application tree deployed from `267e073`.
   Optional SQLite stable authority, non-expiring local preferred code, atomic
   room replacement and the Host codec selector are implemented; production
   selects stable storage. Graceful restart, crash, timeout and network loss use
@@ -57,6 +58,10 @@ This is the current execution index. Git history owns completed timelines;
   quality score, layer selector, periodic rebalancing, or quality-driven parent
   change. P2P and SFU recover their current route before actual failure enters
   normal reassignment.
+- Current Viewer freeze/pause evidence requires decoded progress and exact
+  foreground presentation authority. The controller retains one bounded,
+  fresh current-edge aggregate per child for the Host-only on-demand snapshot;
+  it does not change route facts, capacity, candidates, SFU usage or reconcile.
 - Viewer hidden/freeze/pagehide suppress decoded-stall routing authority;
   visible/resume/pageshow rebaseline and rearm current-frame proof. SFU
   pagehide no longer triggers LiveKit's automatic disconnect. Native Viewer
@@ -64,10 +69,8 @@ This is the current execution index. Git history owns completed timelines;
 
 ## Current Milestone
 
-1. Implement presentation-authoritative freeze/pause evidence with decoded
-   progress and the controller-owned shadow aggregate; collect production
-   samples without active route changes. This integration atomically replaces
-   current v12 with accepted strict `screener-v13`.
+1. Atomically deploy strict `screener-v13`, then collect annotated production
+   freeze/pause samples without active route changes.
 2. Finish the Android Chrome and iOS Safari Viewer lifecycle matrix.
 3. Finish representative public-network direct, peer-relay, SFU, recovery,
    Pause/Resume, screen-audio, real-game A/V, and all-UDP-blocked acceptance

docs/todo.md

@@ -1,22 +1,18 @@
 # Current TODO Ledger
 
-Last reviewed: 2026-08-26
+Last reviewed: 2026-08-27
 
 Only **Now** is executable. A branch, old experiment, observation, or accepted
 later topic is not implementation authority by itself.
 
 ## Now
 
-1. **Quality-route evidence and shadow calibration.** Make current Viewer
-   quality evidence presentation-authoritative with standard freeze/pause
-   deltas, continuing decoded progress, exact presentation epochs and baseline
-   fencing. Keep one bounded
-   current-epoch aggregate per exact child in the existing room controller and
-   expose it only through the Host acceptance snapshot. It must not alter facts,
-   capacity, routes or SFU usage. Collect annotated production samples before
-   accepting an active trigger, probation, restore or cooldown policy. Ship it
-   only as the atomic strict `screener-v13` Browser/server contract; v12 gets no
-   compatibility path.
+1. **Quality-route evidence and shadow calibration.** Atomically deploy the
+   implemented strict `screener-v13` Browser/server quality shadow; v12 gets no
+   compatibility path. Collect annotated production samples from its bounded
+   current-edge freeze/pause aggregates before accepting an active trigger,
+   probation, restore or cooldown policy. Shadow evidence must not alter facts,
+   capacity, routes or SFU usage.
 2. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari matrices for
    autoplay gesture, foreground/background audio, foreground video recovery,
    lock/page reclamation, rotation, Wi-Fi/cellular migration, and assigned-relay

docs/verification-status.md

@@ -64,8 +64,9 @@ may be interpreted. Git and pull requests own routine completed checks.
 
 ## Current Source Evidence
 
-- Canonical source contains the same application tree deployed from `267e073`:
-  the adaptive H.264/VP8 sender decision with `contentHint = "motion"` reapplies the
+- Canonical source uses strict `screener-v13`; production remains the strict-v12
+  application tree deployed from `267e073`. The adaptive H.264/VP8 sender
+  decision with `contentHint = "motion"` reapplies the
   selected video profile after answer negotiation, leaves SFU representation
   construction to pinned LiveKit, keeps Dynacast/send-side BWE, disables
   AdaptiveStream, and disables SFU audio RED.
@@ -76,6 +77,10 @@ may be interpreted. Git and pull requests own routine completed checks.
   authority, hidden-page stall suppression, retryable failure reporting, native
   controls, and same-route manual reconnect are current source behavior. Mobile
   physical evidence remains open.
+- The evidence-only quality shadow accepts only exact foreground presentation
+  windows with decoded progress, keeps one bounded fresh aggregate per current
+  child, and exposes it through the Host-only anonymous route snapshot. It does
+  not change route facts, capacity, candidate order, SFU admission or reconcile.
 
 ## Open Physical Gates
 

docs/方案设计.md

@@ -2,7 +2,7 @@
 
 ## 2026-08-18 14:45
 
-状态：production 与 canonical source 当前使用严格 `screener-v12`；已接受的 quality-shadow 集成会把 Browser/server 原子升级为唯一 `screener-v13`，在 authority 前拒绝旧页面，不保留 v12 parser。当前已实现每分享代次的 H.264 sender gate 与 VP8 fallback、本地 pre-share `VP8 | 自动 | H264` selector、可选 SQLite stable room authority、无期限 preferred code 和换房控制；这些不新增 codec wire、自定义 SFU layer list或应用媒体质量 controller。Video 使用 `contentHint = "motion"`，audio 使用 `music`。SFU 由 pinned LiveKit 默认 representations、Dynacast、server send-side BWE 和 disabled AdaptiveStream 拥有质量适配；screen audio 使用 64/128/192 kbps ceiling、stereo、DTX off 与 RED off。精确执行状态由 `docs/status.md` 持有。
+状态：canonical source 已实现唯一 strict `screener-v13` 的 evidence-only quality shadow，production 在原子应用发布前仍使用 strict `screener-v12`；旧页面在 authority 前拒绝，不保留 v12 parser。当前已实现每分享代次的 H.264 sender gate 与 VP8 fallback、本地 pre-share `VP8 | 自动 | H264` selector、可选 SQLite stable room authority、无期限 preferred code 和换房控制；这些不新增 codec wire、自定义 SFU layer list或应用媒体质量 controller。Video 使用 `contentHint = "motion"`，audio 使用 `music`。SFU 由 pinned LiveKit 默认 representations、Dynacast、server send-side BWE 和 disabled AdaptiveStream 拥有质量适配；screen audio 使用 64/128/192 kbps ceiling、stereo、DTX off 与 RED off。精确执行状态由 `docs/status.md` 持有。
 
 ## 目标与边界