Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs(release): record TURN removal postflight (#217)
AAA13e81c64945e
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex c5a5223d..b3ede32c 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -298,11 +298,9 @@ deployment-wide.## Current Deployment Boundary-Production release `a5b1fc6` runs the `screener-v8` Browser runtime and still-contains the superseded selected-TURN surface. Its exact configuration, rollback-artifacts, and postflight evidence are owned by the deployment document. The-direct-to-SFU contract is accepted but not deployed until the selected-TURN-source and production configuration are removed atomically; real+Production release `8f5b3f1` runs the `screener-v8` Browser runtime with only+direct/STUN peer and LiveKit SFU/UDP routes. Its exact configuration, rollback+artifacts, and postflight evidence are owned by the deployment document; realheterogeneous-network and SFU media validation remains open.## Acceptance Boundarydiff --git a/docs/deployment.md b/docs/deployment.mdindex ccd434ee..5f46a729 100644--- a/docs/deployment.md+++ b/docs/deployment.md@@ -2,7 +2,7 @@Last verified against upstream documentation: 2026-08-24.-This page records exact release `a5b1fc6` production facts and the current source+This page records exact release `8f5b3f1` production facts and the current sourcedeployment contract. Product direction and pending migrations are owned by[project memory](./project-memory.md) and [the TODO ledger](./todo.md).@@ -17,19 +17,16 @@ as the current controller's automatic final media fallback. This capacity isdormant unless the complete public URL, private API URL, key, secret, and capacitytuple is configured. It does not replace the P2P path,the peer-assisted experiment, or required STUN discovery. LiveKit remains-ICE/UDP only. Ordinary peer ICE remains STUN-only and the tracked coturn example-is STUN-only with TCP/TLS disabled. The accepted source contract configures no-TURN, ICE/TCP, media TCP, or TLS-relayed media. Production still retains the-superseded selected-edge environment tuple, authenticated-relay coturn-configuration, TCP listener, and relay firewall range until the direct-to-SFU-release removes them atomically.--Production runs exact `a5b1fc62f609b996ead54f2a5db42ddd2f374fb9`, release-`a5b1fc6`, from `/opt/screener/releases/a5b1fc6`. The immutable runtime archive+ICE/UDP only. Ordinary peer ICE remains STUN-only and production coturn uses the+tracked STUN-only configuration with TCP/TLS disabled. The source and production+configure no TURN, ICE/TCP, media TCP, or TLS-relayed media.++Production runs exact `8f5b3f192ddd010ca01c969008e512191312736a`, release+`8f5b3f1`, from `/opt/screener/releases/8f5b3f1`. The immutable runtime archiveSHA-256 is-`2c6223f13b1ae44e737f4088af3f62259581c58c20eb9583f4f4900f58387519`.-Its verified pre-cutover boundary is-`/opt/screener/backups/a5b1fc6-precutover-20260823T160319Z`. Local and public+`09c18d3604b64b627b01164b5a8d954fcbaeb567ca12dedf0b89deaac72bd767`.+Its verified rollback boundary is+`/opt/screener/backups/8f5b3f1-precutover-20260823T182438Z`. Local and publichealth return 200; Screener, LiveKit, coturn, and nginx are active with`NRestarts=0`.@@ -40,8 +37,8 @@ one-controller exact-candidate route runtime, and stale-v7 rejection beforeroom authority. The service unit has no writable room StateDirectory and theold live SQLite path is absent. LiveKit is dedicated, has `room.auto_create: false` and`max_participants: 21`, and is admitted to one global publication ingress plus-twenty subscription egress handles. The deployed selected-TURN allocation cap-of two is a superseded production fact, not accepted behavior.+twenty subscription egress handles. Coturn listens only on UDP 3478 for STUN;+LiveKit media listens on UDP 7882.These bounds are fail-safe admissions, not throughput or quality claims.The retained local 20-Viewer Browser smoke and open real-network boundaries areowned by [verification status](./verification-status.md).@@ -105,6 +102,8 @@ service. If a host lacks the `sqlite3` CLI, use the pinned Node runtime's`node:sqlite` API or stop before the first write. After a start, poll health fora short bounded window instead of treating one request during startup as afailed release; retain the last failure while still enforcing the deadline.+After starting coturn, likewise wait boundedly for its UDP 3478 socket before+asserting STUN readiness; `ActiveState=active` can precede socket readiness.Run `npm start` under a service supervisor that injects the environment, restartson failure, and applies bounded logs. For a simple untracked environment file,@@ -171,26 +170,6 @@ for the full gate and verify representative external networks and devices.Coturn provides STUN binding only and must reject allocation requests.HTTPS/WSS always remains TLS/TCP independently of the UDP-only media ladder.-The 2026-08-20 exact-room canary used source `a11a73dfa79d`, inactive release-`/opt/screener/releases/a11a73dfa79d-r4`, artifact SHA-256-`C954185869A3A15CCCE642AB72A4CF90770476C117D61182D7728280C30A036F`, and-backup `/opt/screener/backups/turn-a11-20260820T065933Z`. The candidate-switch completed at 14:59:33 +08. Local authenticated coturn allocation and-application/deployment gates passed, but the real direct Host plus Pion Viewer-did not establish its peer connection. The forced-relay test was therefore not-run. Issuance was removed first, then coturn and its firewall rules returned to-the pre-canary authenticated-relay baseline: TCP/UDP 3478 and UDP 49152-49251.-Exact `7fea60ef6f2ad14a9ac1c23a89a523d91bbb97e4` was restored and advertises no-TURN credential. The final lock-free check at 15:12:40 +08 found active-services, zero allocations, and matching health, configuration, firewall, and-SQLite state.-No canary test process, browser profile, or transient firewall rule remained.-The retained release is inactive. This is a canary no-go, not TURN deployment-or media evidence. Two earlier attempts changed no durable state: one stopped-before backup/write because `sqlite3` was absent, and one rolled back after a-single health request landed in the normal startup window. The preflight and-bounded-poll rules above are the retained fixes.-## Production application environmentKeep the real values in the process secret store or an untracked, access-restricted@@ -232,11 +211,10 @@ SFU_EGRESS_CAPACITY=<MEASURED_DEPLOYMENT_EGRESS_COPIES>```Supplying any stale `PEER_ICE_TURN_*` or `SELECTED_EDGE_TURN_*` key, even blank,-fails startup. The cutover must remove all four production selected-edge keys-before starting the new application, install the tracked STUN-only coturn-configuration, and close TCP 3478/5349 plus every relay range. Keep the old-release, its exact environment, coturn configuration, and firewall snapshot as-one rollback unit; do not restore only part of that obsolete transport.+fails startup. Production contains none of those keys, uses the tracked+STUN-only coturn configuration, and keeps TCP 3478/5349 plus every relay range+closed. A rollback restores an exact recorded release, environment, coturn+configuration, and firewall snapshot as one unit.`PEER_ASSISTED_ROOM_IDS` is retired. Supplying it, even blank, fails startup sothat a stale room-1 deployment cannot silently retain the old scope. With@@ -257,7 +235,7 @@ lifetime. An actively connected Host prevents expiry; explicit stop or Hostdisconnect starts the lease, and only the exact Host token renews it beforeexpiry. Viewer activity never renews ownership. `ROOM_DATABASE_PATH` and`ROOM_TTL_SECONDS` fail startup even when blank.-Production `a5b1fc6` accepts 1 through 20 and explicitly selects 20. This is an+Production `8f5b3f1` accepts 1 through 20 and explicitly selects 20. This is anadmission limit, not evidence that every publisher, network, or quality profilecan sustain that many streams.`ENDPOINT_MEDIA_COPY_CAPACITY` defaults to 2 and accepts only 1, 2, or 3. It is@@ -270,7 +248,7 @@ must fail or wait before a fourth endpoint copy is issued.Supplying the removed `MAX_PEER_RELAY_DOWNSTREAM_EDGES`, even blank, failsstartup.-Production release `a5b1fc6` runs the deployed server and Browser assets+Production release `8f5b3f1` runs the deployed server and Browser assetsatomically on `screener-v8`; stale v7 Browser and executable-sender wires failbefore room authority. Native senders and helpers are outside this release.Restore only an exact recorded release with its matching environment, unit,@@ -482,11 +460,9 @@ canary pass silently.## Self-hosted STUN-This subsection describes the accepted STUN-only deployment. Before the-direct-to-SFU cutover, the shared production host still retains an older-authenticated-relay configuration and TCP/UDP 3478 plus UDP 49152-49251-firewall range; the atomic cutover replaces that configuration and closes those-obsolete listeners/ranges.+This subsection describes the accepted and deployed STUN-only boundary.+Production uses the tracked configuration and keeps TCP 3478/5349 plus every+relay range closed.Copy [`deploy/coturn/turnserver.conf.example`](../deploy/coturn/turnserver.conf.example)to an untracked service-owned location and use the trackeddiff --git a/docs/maintenance.md b/docs/maintenance.mdindex 1a39c1fb..5d6f931d 100644--- a/docs/maintenance.md+++ b/docs/maintenance.md@@ -45,6 +45,8 @@内存房间决定是基准案例:先衡量删除 SQLite 的真实退让。应用重启本来就会中断全部活动媒体,额外损失只是当前房间号、邀请和休眠租约;同一浏览器还能重放本地创建偏好。对当前私用、最多 20 名 Viewer、允许重启清空的产品,这点体验回退很小。相较之下,SQLite 会持续引入 schema、迁移、路径配置、可写目录、备份、测试分支和跨重启状态语义。产品因此主动接受这份有界回退并更新合同,随后才选择进程内模型和整体删除持久层。结论不是“小项目不应使用 SQLite”,而是不要为价值很小的能力长期维护一整套机制。+应用层 TURN 是第二个基准案例:它只能覆盖 direct peer 穿透失败但 UDP 仍可到达中继的窄区间,公开 SFU/UDP 已覆盖当前产品所需的中央兜底;全部 UDP 被封时 TURN/UDP 同样无效。保留它却需要独立 URL/credential schema、短期签发、route tuple、allocation ledger、relay-only rebuild、UI、测试、coturn relay 配置和额外端口。产品接受当前 UDP-only 的明确失败边界,把未来严格防火墙传输留给有真实证据时的 LiveKit 内部能力,并整体删除应用 TURN。生产因此从 TCP/UDP 3478 加 relay range 收敛为 STUN-only UDP 3478,核心 direct/SFU 能力不变。结论不是“TURN 标准没有用途”,而是不要在已有更小通用机制覆盖主要行为时,继续维护重复的应用层路径。+## 检查点与恢复在需求或优先级被接受、设计或研究结论改变、实质阶段切换、分支/PR/agent 交接、可能 compaction 或长暂停前更新事实 owner。不要为每个函数、工具调用或未形成结论的探索建立检查点。diff --git a/docs/project-memory.md b/docs/project-memory.mdindex 196c5e71..f8c7850b 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -27,10 +27,10 @@ Last updated: 2026-08-24## Current Source And Production- Canonical source is the root `main` branch. Audit/integration boundaries require it to be clean, and new branches/worktrees start from its exact commit only after accepted truth is merged.-- Current source admits up to `20` Viewers and implements the uniform `1/2/3` endpoint cap, single Browser `screener-v8` wire, exact prepare candidate, first-decoded-frame commit, strict rollback revision, decoded-progress stall, a two-stage direct/SFU operation deadline, and one event-driven room controller. Application TURN URL/credential schema, messages, candidates, admission, relay-only clients, UI, gate, configuration, and tests are removed; stale TURN environment keys fail startup. SFU admission uses exact publication and Viewer-subscription handles with explicit no-default ingress/egress capacities and a listener-fenced dedicated LiveKit owner.+- Current source admits up to `20` Viewers and implements the uniform `1/2/3` endpoint cap, single Browser `screener-v8` wire, exact prepare candidate, first-decoded-frame commit, strict rollback revision, decoded-progress stall, a two-stage direct/SFU operation deadline, and one event-driven room controller. Ordinary peer ICE is STUN-only and the sole application fallback is SFU/UDP; stale TURN environment keys fail startup. SFU admission uses exact publication and Viewer-subscription handles with explicit no-default ingress/egress capacities and a listener-fenced dedicated LiveKit owner.- Current source and production implement the memory-resident room model: random free four-digit codes, the configurable dormant lease, exact-Host resume, restart loss, local creation-preference replay, orthogonal Viewer grants and `open | password | disabled` code entry, and direct invitation/policy controls. SQLite room persistence, `ROOM_DATABASE_PATH`, `ROOM_TTL_SECONDS`, and the writable room StateDirectory are removed from the v8 runtime; the stopped v7 SQLite snapshot exists only in the verified rollback backup.-- Production runs exact `a5b1fc62f609b996ead54f2a5db42ddd2f374fb9`, release `a5b1fc6`, wire `screener-v8`; `/opt/screener/backups/a5b1fc6-precutover-20260823T160319Z` is its verified pre-cutover boundary.-- Production implements the endpoint-cap and staged route-controller contract, admits 20 Viewers, and uses LiveKit admission of one publication ingress plus 20 subscription egress handles on a dedicated non-auto-create instance. It still has the superseded four-value selected-TURN environment tuple and authenticated coturn relay configuration; accepted truth is not deployed until both are removed atomically.+- Production runs exact `8f5b3f192ddd010ca01c969008e512191312736a`, release `8f5b3f1`, wire `screener-v8`; `/opt/screener/backups/8f5b3f1-precutover-20260823T182438Z` is its verified rollback boundary.+- Production implements the endpoint-cap and two-stage direct-to-SFU controller contract, admits 20 Viewers, and uses LiveKit admission of one publication ingress plus 20 subscription egress handles on a dedicated non-auto-create instance. Coturn provides STUN-only UDP 3478 with TCP/TLS and relay ranges disabled; LiveKit media uses UDP 7882.- Browser SFU subscribers reconcile eligible Host screen publications across connect/activate event ordering, participant/track arrival, and reconnect. Production LiveKit logs only warn/error, and the application service has a bounded same-host LiveKit readiness preflight.- Production retains access controls, self-check, diagnostic export, signaling watchdog behavior, and 64/128/256 audio choices. Real heterogeneous-network and SFU media evidence remains open.- `screener`, LiveKit, coturn, and nginx are healthy; local and public health return 200 and `screener` has `NRestarts=0`. Deployment detail is owned by [deployment](./deployment.md).@@ -39,7 +39,7 @@ Last updated: 2026-08-24## Current Priority1. Keep this truth set and [the TODO ledger](./todo.md) concise and internally consistent.-2. Remove application selected TURN from source and production first. Then resume live audio and paused video-codec switching, evidence-led H.264 diagnosis, the strict-NAT emulator gate, connection feedback, and the remaining functional roadmap. Distribution packaging starts only after those TODOs are complete. Parallel branches may finish earlier but do not change this merge/deployment order.+2. Await the owner's next selection among live audio, paused video-codec switching, evidence-led H.264 diagnosis, strict-NAT emulator, connection feedback, quality-driven local reparenting research, and the remaining functional roadmap. Distribution packaging starts only after those TODOs are complete. Parallel branches may finish earlier but do not change this merge/deployment order.## Working Rulesdiff --git a/docs/session-handoff.md b/docs/session-handoff.mdindex dbf2a122..6b732295 100644--- a/docs/session-handoff.md+++ b/docs/session-handoff.md@@ -32,10 +32,8 @@ Current high-signal boundary:- docs/status.md owns the exact source/production/hold state.- docs/todo.md is the only executable work ledger and owns ordering.- ADR-0005 owns the accepted automatic route model: direct/STUN peer followed- only by the dedicated LiveKit SFU/UDP fallback. Current source removes the- complete selected-TURN application surface; production release `a5b1fc6`- still contains its old source/configuration, so atomic deployment is the- active boundary. Real external-network+ only by the dedicated LiveKit SFU/UDP fallback. Current source and production+ release `8f5b3f1` implement that two-stage model. Real external-networkand SFU media evidence remains open. Do not rerun broad orexecutable/native test suites unless the current acceptance boundaryspecifically requires them.diff --git a/docs/status.md b/docs/status.mdindex e78030a0..c8e3a407 100644--- a/docs/status.md+++ b/docs/status.md@@ -6,10 +6,10 @@ This is the current execution index. Git history owns completed timelines; [veri## Production-- `https://share.bonfire.icu` runs exact `a5b1fc62f609b996ead54f2a5db42ddd2f374fb9`, release `a5b1fc6`, wire `screener-v8`; `/opt/screener/backups/a5b1fc6-precutover-20260823T160319Z` retains its verified pre-cutover boundary and the immutable archive SHA-256 is `2c6223f13b1ae44e737f4088af3f62259581c58c20eb9583f4f4900f58387519`.+- `https://share.bonfire.icu` runs exact `8f5b3f192ddd010ca01c969008e512191312736a`, release `8f5b3f1`, wire `screener-v8`; `/opt/screener/backups/8f5b3f1-precutover-20260823T182438Z` retains the exact previous application/environment/LiveKit/coturn/nft/unit boundary and the immutable archive SHA-256 is `09c18d3604b64b627b01164b5a8d954fcbaeb567ca12dedf0b89deaac72bd767`.- `screener`, LiveKit, coturn, and nginx are active; local/public health return 200 and all services report `NRestarts=0`. The v8 unit has no writable room `StateDirectory`, the process has no SQLite descriptor, and the old live SQLite path is absent.- Production admits one Host plus 20 Viewers, applies endpoint capacity `2`, rejects stale Browser and executable-sender wires before room authority, and runs the one-controller exact-candidate route model with one staged total deadline. Rooms use random free four-digit codes, a 24-hour dormant lease, restart loss, local Host creation preferences, independent Viewer grants, and `open | password | disabled` code entry. LiveKit remains dedicated with `room.auto_create: false`, `max_participants: 21`, and global admission `1` publication ingress / `20` subscription egress.-- Production still has the superseded four-value selected-TURN environment tuple and authenticated coturn relay configuration. Accepted truth is now direct/STUN peer followed only by LiveKit SFU/UDP; this is not implemented or deployed until source, environment, coturn relay configuration, and firewall range are removed atomically. These deployment facts do not close the real heterogeneous-network, SFU, mobile, or endurance evidence boundaries.+- Production media ports are STUN-only UDP 3478 and LiveKit UDP 7882; coturn TCP/TLS and relay ranges are disabled. The public Web ingress remains TCP 80/443; Node 8787 and LiveKit control/signaling 7880 are internal-only. These deployment facts do not close the real heterogeneous-network, SFU, mobile, or endurance evidence boundaries.- SFU subscribers reconcile Host screen publications across connect, activation, participant arrival, track publication, and reconnect. A controlled production canary forced two SFU roots; both committed `route-ready`, reached active SFU assignments, and decoded 1920x1080 video. LiveKit runs at `warn`/Pion `error`, and the Screener unit waits boundedly for the same-host LiveKit control listener before startup.## Current Source@@ -18,8 +18,8 @@ This is the current execution index. Git history owns completed timelines; [veri- 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, and no Browser/UA/visibility tier exists. One shared guard owns the accounting and transition work is bounded by `min(C + 1, 3)`.- Current source and production admission support one Host plus up to `20` Viewers. Focused controller coverage includes `C=1/2/3`, a 20-Viewer graph, and the passed local 20-Viewer Browser smoke; real external-network media and resource measurements remain open.- The single Browser `screener-v8` boundary rejects stale Browser and executable-sender wires before room authority and carries the exact deployment cap plus exact prepare candidate in the authenticated route contract.-- 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. Application TURN URL/credential schema, messages, candidates, admission, relay-only clients, UI, gate, configuration, and tests are removed; stale TURN environment keys fail startup.-- Current source implements automatic P2P-first routing with one active upstream, an acyclic source-reachable graph, exact Browser v7 prepare tuple, first-decoded-frame make-before-break, strict rollback revision, and bounded wait or failure.+- 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. Ordinary peer ICE is STUN-only and the sole application fallback is SFU/UDP; stale TURN environment keys fail startup.+- Current source implements automatic P2P-first routing with one active upstream, an acyclic source-reachable graph, an exact prepare tuple, first-decoded-frame make-before-break, strict rollback revision, and bounded wait or failure.- One event-driven controller owns the committed graph and at most one room-serial child operation. The operation owns one deterministic candidate list/cursor, one current candidate and reservations, fact version, and one total deadline split only across direct and SFU stages. Failed candidates are operation-local; exhaustion retires invalid/overflow edges but retains healthy bootstrap media. Bounded-gap preflights resources, replans the remaining suffix, and restores a healthy retired edge through one final ordinary candidate. Admission commits synchronously before graph promotion; release uses the resource-set difference and room disposal returns all resources. One Host publication serves exact Viewer subscription handles, and actual global SFU release wakes registered waiting rooms.- 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. When a departed Host root frees a Host slot, a new or reparable child prefers that shallower Host result over another root's free slot; healthy old edges remain sticky and the controller does not periodically rebalance the whole graph. 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. Quality-driven local reparenting and topology evidence are accepted research/TODO work, not current behavior.- The direct-to-SFU source passed repository typecheck, all 531 Web tests in 41 files, and client/server production builds. Focused tests cover the direct-stage wake, Host-full virtual SFU bootstrap without a premature route error, SFU reuse, and a departed-root scenario in which new demand uses the freed Host slot without moving healthy descendants. No Native/executable suite or heterogeneous-network media run was performed.@@ -29,10 +29,9 @@ This is the current execution index. Git history owns completed timelines; [veri## Current Milestone-1. Remove selected TURN from the application, wire, configuration, UI, tests, production environment, coturn relay mode, and relay firewall range while retaining STUN and SFU.-2. Release live audio-ceiling mutation and paused-share codec switching on the deployed generation/transition boundary.-3. Reproduce the H.264 startup report before any codec-specific repair, research quality-driven local reparenting, 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, then finish the remaining accepted functional and real-network work.+1. Release live audio-ceiling mutation and paused-share codec switching on the deployed generation/transition boundary.+2. Reproduce the H.264 startup report before any codec-specific repair, research quality-driven local reparenting, and build the strict-NAT emulator gate before any manually approved canary in an operator-owned test room.+3. Add first-frame-driven Viewer connection stages, then finish the remaining accepted functional and real-network work.## Active Boundaries@@ -44,7 +43,6 @@ This is the current execution index. Git history owns completed timelines; [veri## Current Hold-The Browser route, SFU subscription reconciliation, staged deadline, and memory-room slices are-deployed. The active bounded change is removal of selected TURN from source and production; do not-resume live-media, Native/executable, or broad repository cleanup until direct-to-SFU source and-production postflight are coherent.+The Browser route, SFU subscription reconciliation, two-stage deadline, direct-to-SFU transport,+and memory-room slices are deployed. There is no active P0/P1 hold; wait for the owner to select the+next TODO rather than beginning live-media, Native/executable, or broad repository cleanup.diff --git a/docs/todo.md b/docs/todo.mdindex beb6c845..ef687289 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -6,17 +6,16 @@ Only items in **Now** are executable after their stated decision gate. A branch## Now-1. **Remove selected TURN and retain direct-to-SFU routing.** Delete the application selected-TURN candidate, signaling/configuration surface, credential issuer, logical-allocation ledger, browser relay-only rebuild, labels, gate, and tests. Ordinary peer ICE remains STUN-only and the sole route suffix is the dedicated LiveKit SFU over UDP. Atomically remove the production `SELECTED_EDGE_TURN_*` tuple, restore coturn to tracked STUN-only/no-TCP/no-TLS mode, close its relay range and TCP listener, and prove direct peer, Host-full SFU bootstrap/reuse, bounded failure, configuration absence, services, health, and rollback. Do not add an application media-TCP substitute; any later strict-firewall transport requires separate evidence and belongs inside LiveKit.-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.** 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 the deployed route release 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. **Diagnose desktop Host background/minimized performance.** On the same machine, dynamic scene, direct Viewer, browser, and fresh share, compare foreground, occluded, minimized, and hidden states while separately verifying actual negotiated VP8/H.264. Correlate capture settings/FPS, frames captured/encoded/sent/decoded, bitrate, `qualityLimitationReason`, encode time, browser/game CPU and GPU, and the existing local-preview pause boundary. Treat browser scheduling/throttling and codec effects as hypotheses until measured. Do not spoof page activity, add keepalive timers, or misuse Wake Lock; if current Chrome/Edge cannot preserve the accepted Host behavior through standard Web APIs, record that capability boundary before considering the packaged/native Host.-6. **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, and every guessed candidate must remain inside the existing direct-stage share rather than extending the room operation. The capped set must pass the documented repeatability, privacy, cleanup, and total-deadline gates in stable Chrome and Firefox, while fallback remains 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/ICE-generation/deadline/aggregate-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.-7. **Make Viewer connection progress and failure recovery explicit.** Derive one stable stage from existing access, Host presence, route, peer/SFU, media, autoplay, recovery, 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. Use one Chinese user-facing vocabulary and map server restart/room loss, Host stop, Host signaling loss with healthy media, Host crash/offline, route exhaustion, SFU admission, autoplay, and stale-client refresh to distinct actionable presentations without exposing private topology identifiers. A failed mobile page must retain privacy-safe stage/revision/code buckets for diagnostic export instead of collapsing everything into `No usable media route is available`. Measure the existing token-free SFU prewarm and route stages before adding another connection mechanism.-8. **Clarify malformed and unusable room entry without enumeration.** Reject non-four-digit input locally with a direct format message. For a well-formed code that cannot be admitted, stop automatically implying that a password is required; show one neutral result covering an unknown room, disabled code entry, wrong/absent password, or bounded admission failure, and offer an optional password retry plus the invitation-link path. Keep `open` rooms direct and do not expose room existence or code-entry policy through distinct server errors.-9. **Refine recommended quality presets.** Change the default recommended profile to the middle `1080p30` option and add one fully specified 480p preset only after its exact resolution, frame rate, and bitrate ceiling are accepted. Update capture constraints, current/future peer/relay/SFU sender settings, local preference/default selection, readback, and tests together; do not add a label that leaves old sender parameters active.-10. **Finish the room-code entry UI as one responsive control.** Preserve the invitation-link controls that are already direct, but redesign the code-only policy/password area to match the compact work surface instead of a nested form panel. Keep the `Start sharing` and `Join room` action rows at stable dimensions when disclosure content opens; prove desktop/mobile wrapping, focus, password and disabled states, and no horizontal overflow before integrating the retained UI candidate.-11. **Research quality-driven local reparenting without room-wide churn.** First measure exact child-edge decoded progress, freeze ratio, RTT, jitter, loss, received bitrate, resolution, FPS, and sender/receiver limitation evidence against the desired room profile. Compare standards/framework algorithms and primary literature for hysteresis, make-before-break handoff, application-layer multicast repair, and local cost/benefit decisions. Any accepted mechanism must be event-driven, exact-edge scoped, bounded by the existing room-serial operation, and resistant to oscillation; it must not infer parent-wide quality from one child, use a weighted room score, or periodically rebalance healthy subtrees. Separately prove the current deterministic rule: after a Host root leaves, a waiting or orphaned child prefers the newly free shallower Host slot, while already healthy descendants remain sticky. Add privacy-safe route-decision snapshots before diagnosing another live room because production currently cannot reconstruct a room such as `3793` after the fact.+1. **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.+2. **Switch video codec while paused.** 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.+3. **Diagnose the production H.264/blur report.** Reproduce exact release `769de201f7cc` against the deployed route release 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.+4. **Diagnose desktop Host background/minimized performance.** On the same machine, dynamic scene, direct Viewer, browser, and fresh share, compare foreground, occluded, minimized, and hidden states while separately verifying actual negotiated VP8/H.264. Correlate capture settings/FPS, frames captured/encoded/sent/decoded, bitrate, `qualityLimitationReason`, encode time, browser/game CPU and GPU, and the existing local-preview pause boundary. Treat browser scheduling/throttling and codec effects as hypotheses until measured. Do not spoof page activity, add keepalive timers, or misuse Wake Lock; if current Chrome/Edge cannot preserve the accepted Host behavior through standard Web APIs, record that capability boundary before considering the packaged/native Host.+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, and every guessed candidate must remain inside the existing direct-stage share rather than extending the room operation. The capped set must pass the documented repeatability, privacy, cleanup, and total-deadline gates in stable Chrome and Firefox, while fallback remains 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/ICE-generation/deadline/aggregate-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 and failure recovery explicit.** Derive one stable stage from existing access, Host presence, route, peer/SFU, media, autoplay, recovery, 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. Use one Chinese user-facing vocabulary and map server restart/room loss, Host stop, Host signaling loss with healthy media, Host crash/offline, route exhaustion, SFU admission, autoplay, and stale-client refresh to distinct actionable presentations without exposing private topology identifiers. A failed mobile page must retain privacy-safe stage/revision/code buckets for diagnostic export instead of collapsing everything into `No usable media route is available`. Measure the existing token-free SFU prewarm and route stages before adding another connection mechanism.+7. **Clarify malformed and unusable room entry without enumeration.** Reject non-four-digit input locally with a direct format message. For a well-formed code that cannot be admitted, stop automatically implying that a password is required; show one neutral result covering an unknown room, disabled code entry, wrong/absent password, or bounded admission failure, and offer an optional password retry plus the invitation-link path. Keep `open` rooms direct and do not expose room existence or code-entry policy through distinct server errors.+8. **Refine recommended quality presets.** Change the default recommended profile to the middle `1080p30` option and add one fully specified 480p preset only after its exact resolution, frame rate, and bitrate ceiling are accepted. Update capture constraints, current/future peer/relay/SFU sender settings, local preference/default selection, readback, and tests together; do not add a label that leaves old sender parameters active.+9. **Finish the room-code entry UI as one responsive control.** Preserve the invitation-link controls that are already direct, but redesign the code-only policy/password area to match the compact work surface instead of a nested form panel. Keep the `Start sharing` and `Join room` action rows at stable dimensions when disclosure content opens; prove desktop/mobile wrapping, focus, password and disabled states, and no horizontal overflow before integrating the retained UI candidate.+10. **Research quality-driven local reparenting without room-wide churn.** First measure exact child-edge decoded progress, freeze ratio, RTT, jitter, loss, received bitrate, resolution, FPS, and sender/receiver limitation evidence against the desired room profile. Compare standards/framework algorithms and primary literature for hysteresis, make-before-break handoff, application-layer multicast repair, and local cost/benefit decisions. Any accepted mechanism must be event-driven, exact-edge scoped, bounded by the existing room-serial operation, and resistant to oscillation; it must not infer parent-wide quality from one child, use a weighted room score, or periodically rebalance healthy subtrees. Separately prove the current deterministic rule: after a Host root leaves, a waiting or orphaned child prefers the newly free shallower Host slot, while already healthy descendants remain sticky. Add privacy-safe route-decision snapshots before diagnosing another live room because production currently cannot reconstruct a room such as `3793` after the fact.## Accepted Later Roadmapdiff --git a/docs/verification-status.md b/docs/verification-status.mdindex 694fe08a..c41db43c 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -10,14 +10,14 @@ Capacity and routing entries below describe the exact tested source or release o## Deployment Evidence-- Production runs exact `a5b1fc62f609b996ead54f2a5db42ddd2f374fb9`, release `a5b1fc6`, wire `screener-v8`, from `/opt/screener/releases/a5b1fc6`; the immutable runtime archive SHA-256 is `2c6223f13b1ae44e737f4088af3f62259581c58c20eb9583f4f4900f58387519`, and `/opt/screener/backups/a5b1fc6-precutover-20260823T160319Z` is its verified pre-cutover boundary.-- A 2026-08-24 read-only check found `screener`, LiveKit, coturn, and nginx active with zero restarts; local and public `/healthz` returned 200.-- Production uses endpoint capacity `2`, room admission `20`, random free four-digit memory rooms, `ROOM_LEASE_SECONDS=86400`, a dedicated LiveKit instance with `room.auto_create: false` and `max_participants: 21`, and global SFU admission `1` ingress / `20` egress. The superseded selected-TURN admission remains `2` until the direct-to-SFU cutover removes its environment, coturn relay mode, and firewall range atomically. The v8 service has no StateDirectory or SQLite descriptor and the old live SQLite path is absent.+- Production runs exact `8f5b3f192ddd010ca01c969008e512191312736a`, release `8f5b3f1`, wire `screener-v8`, from `/opt/screener/releases/8f5b3f1`; the immutable runtime archive SHA-256 is `09c18d3604b64b627b01164b5a8d954fcbaeb567ca12dedf0b89deaac72bd767`, and `/opt/screener/backups/8f5b3f1-precutover-20260823T182438Z` contains the exact previous application/environment/LiveKit/coturn/nft/unit boundary.+- The 2026-08-24 postflight found `screener`, LiveKit, coturn, and nginx active with zero restarts; local/public health returned 200. The deployed browser asset `assets/index-sh8IJzwp.js` matches local SHA-256 `7fbc2f7ed67478c160e0122873116c03539084d637f3495cc588af70058364fc` and contains exactly one `screener-v8` wire literal.+- Production uses endpoint capacity `2`, room admission `20`, random free four-digit memory rooms, `ROOM_LEASE_SECONDS=86400`, a dedicated LiveKit instance with `room.auto_create: false` and `max_participants: 21`, and global SFU admission `1` ingress / `20` egress. Coturn is `stun-only`, `no-tcp`, and `no-tls`; only UDP 3478 listens, a randomized external STUN Binding request returned a matching 40-byte success response, and nft exposes only UDP 3478/7882 for Screener media. The v8 service has no StateDirectory or SQLite descriptor and the old live SQLite path is absent.- A public control-plane smoke passed site access, four-digit creation, Host v8 authentication, stale-v7 rejection before authority, independent code-only and grant Viewer admission, grant rotation that preserved the code Viewer, signaling challenge, and exact room abandonment. A separate service-restart smoke rejected the old Host token and Viewer grant, atomically created a password-policy replacement room, and abandoned it.-- The first reported SFU failure showed Host screen tracks published and the Viewer active over LiveKit UDP, but the candidate was deleted before a usable route committed. Exact `d3ff9e7` fixed missing subscription reconciliation across pending connect, participant/track arrival, activation, and reconnect; 550 Web tests passed, and a production Host plus three zero-downstream Viewer canary forced one peer and two active 1920x1080 SFU roots. Room `9403` then exposed a separate blocker: repeated cellular attempts never entered LiveKit because silent earlier route classes consumed the total deadline before `sfu:reuse`. Exact `a5b1fc6` derives semantic-stage wake boundaries from the one total timer and is deployed; an exact heterogeneous-network recheck remains open. The accepted follow-up removes the selected-TURN stage entirely, leaving only direct and SFU shares.+- The first reported SFU failure showed Host screen tracks published and the Viewer active over LiveKit UDP, but the candidate was deleted before a usable route committed. Exact `d3ff9e7` fixed missing subscription reconciliation across pending connect, participant/track arrival, activation, and reconnect; 550 Web tests passed, and a production Host plus three zero-downstream Viewer canary forced one peer and two active 1920x1080 SFU roots. Room `9403` then exposed a separate blocker: repeated cellular attempts never entered LiveKit because silent earlier route work consumed the total deadline before `sfu:reuse`. Current `8f5b3f1` leaves only direct and SFU shares, including a virtual Host-full bootstrap stage; local runtime tests pass and an exact heterogeneous-network field recheck remains open.- The first hotfix cutover start raced LiveKit ActiveState before TCP 7880 and produced one supervised Screener restart. A production-only `After/Wants` plus bounded listener-ready `ExecStartPre` was installed; a simultaneous LiveKit/Screener restart then completed with both `NRestarts=0`. Pinned LiveKit info records were confirmed to contain raw PublisherOffer SDP, so production now uses warn/Pion-error. Three archived journal files containing prior raw SDP (90,404,248 bytes total) were deleted; the active journal and the post-hardening SFU canary contain zero `PublisherOffer` record.- Rollback evidence confirms release `6b87732` and its old environment/runtime imports are readable, every precutover backup checksum passes, the backed-up database remains schema v3/integrity-ok with six rooms, and the current and rollback release regular-file sets share zero inodes.-- Share audio presets, local-only diagnostics, self-check, diagnostic export, signaling-partition recovery, and the superseded selected-edge transport remain deployed surfaces. The latter is pending atomic removal; the remaining real-route media behavior and target-browser field availability remain unverified.+- Share audio presets, local-only diagnostics, self-check, diagnostic export, and signaling-partition recovery remain deployed surfaces. Their remaining real-route media behavior and target-browser field availability remain unverified.## Retained Functional Evidence@@ -26,11 +26,10 @@ Capacity and routing entries below describe the exact tested source or release o- Exact route source `4e0a922` passed repository hygiene, TypeScript typecheck, and 84 focused controller, runtime, protocol, transition, decoded-stall, and SFU-admission tests. During the same convergence, the full 557-test Web suite and client/server builds passed before the final no-consumer cleanup. The two independent route audits' model and wire findings are incorporated, and final static review found no remaining P0/P1. No Browser, Native, Go, helper, hardware, or executable test ran in the final pass; this is source and state-machine evidence, not production or heterogeneous-network proof.- Exact source `6b87732` passed the required one-Host/20-Viewer local Browser smoke on Windows Node 24.19.0 / Chrome 151.0.7922.174, using 720p30 synthetic canvas media, endpoint cap `2`, a 30-second measurement window, and report SHA-256 `1347E036BB9AC35D51B4ED9B215290E742715128C7F3056D8FEB185CC84456D6`. All six checks passed: 20/20 Viewers had live clean upstreams and increasing decoded frames, Host and relay sender counts stayed at two, topology was coherent, and no orphan SFU publication appeared. Maximum authenticate-to-first-decoded latency was 958 ms; the final graph had two Host children and eighteen peer descendants. The application Node process consumed about 0.95 additional CPU seconds over the 54-second observation window, peaked near 284 MiB RSS, and settled near 162 MiB; isolated Chromium averaged 761% CPU over its valid 25.97-second process interval. The harness did not configure LiveKit, so its observed SFU usage was zero and this loopback is not a public-network, SFU, quality, or endurance claim.- Exact memory-room source `2ba155782bd5c4a193484c007ee69007e562ddb9` passed repository hygiene, TypeScript typecheck, all 548 Web tests, and client/server builds. The focused room/access set contributed 239 passing tests across allocation, dormant leases, grant/code orthogonality, password KDF bounds, stale generation atomicity, protocol v8, HTTP/signaling, local ownership, and creation-profile replay. A fresh Chrome access/privacy gate also passed all fixed checks: pre-DOM fragment consumption, room-scoped session grant, zero request/nginx/application-log secret hits, zero persistent room files, strong grant rotate/revoke coverage, and cleanup. This is local source, state-machine, and loopback-browser evidence; it is not production deployment, restart/rollback, heterogeneous-network, or media-quality evidence.-- The direct-to-SFU source passed repository typecheck, all 531 Web tests in 41 files, and client/server production builds. The server build now clears its fixed generated-output directory before compilation, and the resulting tree contains zero selected-TURN modules or symbols. Focused controller/runtime coverage proves direct-stage wake, Host-full virtual SFU bootstrap without a premature route error, SFU reuse, and a departed-root sequence where new demand takes the freed Host slot while healthy descendants remain sticky. This is local state-machine/build evidence; no Native/executable suite or heterogeneous-network media run was performed.+- The direct-to-SFU source passed repository typecheck, all 531 Web tests in 41 files, and client/server production builds. The server build clears its fixed generated-output directory before compilation so the artifact contains only current route modules. Focused controller/runtime coverage proves direct-stage wake, Host-full virtual SFU bootstrap without a premature route error, SFU reuse, and a departed-root sequence where new demand takes the freed Host slot while healthy descendants remain sticky. This is local state-machine/build evidence; no Native/executable suite or heterogeneous-network media run was performed.- 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).+- 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, and leaves were clean. 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, 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).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 327a9602..90a70432 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"@@ -355,7 +355,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio8. 当前发布只验收 Web Host、Viewer 和 browser relay。Native sender、capture helper 与 shared-encode executable 排在整体 roadmap 最后,不参与当前构建、路由验收或发布。9. 当前功能、NAT 与真实网络 TODO 完成后,再分别设计和交付公网服务器一键部署包与完全不依赖外部服务的本地 Host-server 包。-生产当前运行 `screener-v8` room/route release `a5b1fc6`。内部不兼容 wire/schema 原子切换,Git commit 与部署备份承担回滚,不保留兼容实现。+生产当前运行 `screener-v8` room/route release `8f5b3f1`。内部不兼容 wire/schema 原子切换,Git commit 与部署备份承担回滚,不保留兼容实现。任何一步只实现当前消费者需要的接口。不得为未来账号、第三种媒体拓扑或原生 sender 预建抽象层。