Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

docs(quality): record lower representation postflight (#256)

AAA8adc2b82e1be
diff --git a/docs/adr/0007-path-isolated-representation-quality.md b/docs/adr/0007-path-isolated-representation-quality.md
index f84c67c9..340b87a2 100644
--- a/docs/adr/0007-path-isolated-representation-quality.md
+++ b/docs/adr/0007-path-isolated-representation-quality.md
@@ -1,6 +1,6 @@
# ADR-0007: LiveKit-Owned SFU Representation Adaptation
-- Status: Lightweight lower representation implemented in current source; not deployed
+- Status: Accepted, implemented, and deployed
- Date: 2026-08-19
- Last reviewed: 2026-08-25
@@ -52,7 +52,7 @@ removing the representation required by constrained Viewers.
6. ADR-0005 remains the only route owner. Layer choice does not change topology,
endpoint capacity, SFU admission, or decoded-stall recovery authority.
-Production release `e14eb0e` leaves the screen-share layer list unset, so pinned
+Production release `e14eb0e` left the screen-share layer list unset, so pinned
client `2.22.0` supplies a same-FPS half-resolution representation beside the
original. A live mixed P2P/SFU observation confirmed that the 60 fps lower
representation can consume enough Host-to-SFU budget to starve the highest
@@ -62,7 +62,7 @@ supplies one half-resolution lower preset with
The two encodings remain RIDs `q,h`; LiveKit's protocol labels them `LOW,MEDIUM`,
while a subscriber's default `HIGH` ceiling still selects the highest available
encoding. Dynacast, server send-side BWE, and disabled AdaptiveStream remain
-unchanged.
+unchanged. Production release `be53c4d` deploys that correction.
Current source derives the lower preset from the actual capture dimensions and
passes it through LiveKit's public publication options. Retained publication
diff --git a/docs/deployment.md b/docs/deployment.md
index 53a428ae..9efe5aac 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -3,7 +3,7 @@
Last verified against upstream documentation: 2026-08-24.
This page records production running exact deployed application/runtime revision
-`1d8761528d0dba43fb6d818df3934483ba2f5340`, release `1d87615`, and the single
+`be53c4d5794d38d5d406c876309958d7117ee601`, release `be53c4d`, and the single
Browser `screener-v12` contract. Product direction and pending work are owned by
[project memory](./project-memory.md) and [the TODO ledger](./todo.md).
@@ -11,10 +11,11 @@ This section documents the accepted UDP-only deployment contract: one Node.js
process provides the built Web client, room API, and WebSocket signaling behind
Caddy or nginx; ordinary peer ICE advertises only STUN, while Browser LiveKit
PCs configure no external ICE server and retain LiveKit-signaled UDP candidates.
-LiveKit supplies bounded SFU fallback capacity. Normal media remains distributed
+LiveKit supplies bounded SFU capacity. Normal media remains distributed
through direct or peer edges whenever those paths work. Production includes
-implementation `ae09c760adec76fd26da611d4928486d105c6d3b`. Chrome 151 physically
-verified its exact single-representation SFU publisher and subscriber.
+the Browser SFU ICE isolation and two-representation model. Chrome 151 physically
+verified UDP publication/subscription and native full/lower selection; the
+deployed lower-representation cost correction still needs mixed-route media evidence.
A deployment may additionally provide one dedicated single-node LiveKit process
as the current controller's automatic final media fallback. This capacity is
@@ -25,20 +26,21 @@ 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 `1d8761528d0dba43fb6d818df3934483ba2f5340`, release
-`1d87615`, from `/opt/screener/releases/1d87615`. The immutable runtime ZIP
+Production runs exact `be53c4d5794d38d5d406c876309958d7117ee601`, release
+`be53c4d`, from `/opt/screener/releases/be53c4d`. The immutable runtime tar
SHA-256 is
-`715480487059bf83516a34e0d1083b52437619838c46bdc26ca5967529a1cf05`.
-Its 38-file path/size/hash manifest SHA-256 is
-`96845789560394ca20b16c37a8e7ddadc7b488876e32241709d0f7a577fdca26`.
+`5c174c30ffacd98738a364b825b915b84432823c261272684937361be2451144`.
+Its 39-file path/size/hash manifest SHA-256 is
+`c34dba43a25c6b8447e1153a5be3191bf82cff94117ed31edc325d3f7cf8541f`.
Local and public `/healthz` return 200; Screener, LiveKit, coturn, and nginx are
active with `NRestarts=0`. The public main Browser asset is
-`assets/index-DfMqhOXY.js` with SHA-256
-`cf6dd1c46cc9414a87331a9312eec315ddce8fce565741284998aa0141b18d47`.
+`assets/index-BKEVI7Ux.js` with SHA-256
+`22114fc8a26b3f03f37973555433d1e73d52d1c7b76fa3c7cc597500823bd62d`.
The release deploys the single Browser `screener-v12` wire, fixed VP8 for Browser
-direct, browser-relay, and SFU video, one SFU `HIGH` encoding without simulcast
-or a subscriber layer selector, disabled Dynacast, no video `contentHint`, no
+direct, browser-relay, and SFU video, one original plus one half-actual-resolution
+SFU encoding capped at 30 fps with proportional bitrate, Dynacast and server
+send-side BWE without an application layer selector, no video `contentHint`, no
codec UI/state/wire, random four-digit memory rooms with a 24-hour dormant lease,
a room-lived 22-character grant,
orthogonal `open | private` grant/code admission,
@@ -282,7 +284,7 @@ lifetime. An actively connected Host prevents expiry; explicit stop or Host
disconnect starts the lease, and only the exact Host token renews it before
expiry. Viewer activity never renews ownership. `ROOM_DATABASE_PATH` and
`ROOM_TTL_SECONDS` fail startup even when blank.
-Production `1d87615` accepts 1 through 20 and explicitly selects 20. This is an
+Production `be53c4d` accepts 1 through 20 and explicitly selects 20. This is an
admission limit, not evidence that every publisher, network, or quality profile
can sustain that many streams.
`ENDPOINT_MEDIA_COPY_CAPACITY` defaults to 2 and accepts only 1, 2, or 3. It is
@@ -295,7 +297,7 @@ must fail or wait before a fourth endpoint copy is issued.
Supplying the removed `MAX_PEER_RELAY_DOWNSTREAM_EDGES`, even blank, fails
startup.
-Production release `1d87615` runs the deployed server and Browser assets
+Production release `be53c4d` runs the deployed server and Browser assets
atomically on `screener-v12`; every stale Browser or executable-sender wire fails
before room authority. Native senders and helpers are outside this release.
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 3976d06c..0f8488a0 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -17,7 +17,7 @@ Last updated: 2026-08-25
- One Host publication may serve all SFU subscriptions. Its exact generation owns one ingress handle and exact Viewer subscription handles own egress; later SFU children reuse the publication, while reserved, committed, and draining handles remain charged until the managed room is deleted and proven absent. Actual SFU usage release wakes only rooms that previously lost a candidate to global admission, and SFU-fed and peer-fed endpoints use the same provisional-child transaction. Parent choice hard-filters authority, reachability, cycles, effective capacity, and producer transition, then orders by shallowest result, remaining steady sender capacity, stable join order, and peer identity; server admission is checked at the current cursor. Acyclicity and room admission bound maximum depth; depth is observed but has no separate hard cap. Healthy committed edges remain sticky: the controller repairs waiting, invalid, departed-parent, and overflow children but does not periodically rebalance the graph. 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. Browser LiveKit publisher and subscriber PCs use no external ICE server, retain LiveKit-signaled UDP candidates, and let standard ICE nominate a non-relay pair; deployment STUN remains available to ordinary peers and LiveKit server-side public-IP discovery. This Browser SFU ICE-server isolation avoids the reproduced external-STUN/SFU association conflict without constraining candidate type or count and without adding TURN, another route, a port, or a timeout. Credentials, room secrets, candidate details, and diagnostic data remain private and narrowly scoped. A future strict-firewall transport requires separate evidence and must remain inside LiveKit rather than becoming another Screener route candidate.
- Browser peers use existing periodic WebRTC/LiveKit sampling to maintain one exact-route decoded-progress timestamp. New frames or route/connection changes reset it; a non-paused deadline reports once. An active SFU cadence treats an absent track/report or stats failure as no progress without fabricating metrics and stops only on deactivation/teardown. Other current-path stats remain diagnostic and cannot prove another parent better.
-- ADR-0007's two VP8 SFU representations, Dynacast, server send-side BWE, and disabled AdaptiveStream for potential relays are the deployed framework model. Production still gives the half-resolution representation the highest representation's FPS; the accepted correction caps that lower representation at 30 fps with proportionally derived bitrate. Screener adds no media-layer selector.
+- ADR-0007's two VP8 SFU representations, Dynacast, server send-side BWE, and disabled AdaptiveStream for potential relays are deployed. The lower representation is half the actual capture dimensions, capped at 30 fps, and uses proportionally derived bitrate. Screener adds no media-layer selector.
- Browser capture requests available share audio by default on initial capture and source switch, with an explicit video-only warning when no audio track is returned. Its screen-audio control offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The 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.
- Browser display video leaves `contentHint` unset so Chromium retains its screen-capture classification; returned audio tracks keep `contentHint = "music"`. Browser video is fixed to VP8 across direct, browser-relay, and SFU paths; codec selection, fallback to another media codec, quality-state/wire fields, and share-lifetime codec branches are not product features. Actual codec/profile/encoder stats remain diagnostic only.
- Recommended quality remains exactly `1080p60`, `1080p30`, and `720p30`, with the middle `1080p30` as the accepted default. `480p` means only an advanced `854x480` resolution choice whose FPS and bitrate remain independently selected; it is not a fourth recommended profile.
@@ -29,18 +29,18 @@ Last updated: 2026-08-25
## Current Source And Production
-- Production runs exact application/runtime revision `e14eb0e3e62731a43dca8ff92fa6d5165c8267a3`, release `e14eb0e`, on strict `screener-v12`; canonical `main` contains that deployed application tree plus current truth.
+- Production runs exact application/runtime revision `be53c4d5794d38d5d406c876309958d7117ee601`, release `be53c4d`, on strict `screener-v12`; canonical `main` contains that deployed application tree plus current truth.
- Current source and production admit up to `20` Viewers and implement the uniform `1/2/3` endpoint cap, exact prepare candidate, first-decoded-frame commit, strict rollback revision, decoded-progress stall, one direct/SFU operation deadline, and one event-driven controller. Active-SFU sampling remains live through an absent track/report or stats failure. Ordinary peer ICE is STUN-only and the sole application fallback is SFU/UDP. Exact SFU admission and empty Browser SFU ICE-server options remain unchanged.
- Source and production use random four-digit memory rooms, dormant leases, exact-Host resume, restart loss, local preference replay, orthogonal grants/code entry, and no SQLite runtime. V12 uses a 22-character room-incarnation grant, `ROOM_NOT_FOUND`, no diagnostic-file export, and a compact UI showing the complete shorter URL.
- Exact production artifacts, services, ports, and any change-scoped infrastructure recovery boundary are owned by [deployment](./deployment.md) and indexed by [status](./status.md).
-- Source and production require v12, fixed VP8, and no video hint. Current source derives a half-actual-resolution SFU lower preset capped at 30 fps with proportional bitrate; production still uses pinned-default same-FPS lower plus original-resolution simulcast. Both retain Dynacast, server send-side BWE, and disabled AdaptiveStream. Other current media and UI behavior matches the truths above.
+- Source and production require v12, fixed VP8, and no video hint, and derive a half-actual-resolution SFU lower preset capped at 30 fps with proportional bitrate. Both retain Dynacast, server send-side BWE, and disabled AdaptiveStream. Other current media and UI behavior matches the truths above.
- 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.
-- The deployed application tree passed TypeScript, 611 Web tests, both builds, hygiene, immutable artifact verification, and production postflight. Earlier exact-production gates closed direct/browser-relay VP8 cadence, active-audio ceilings, a single-representation SFU baseline, and one controlled exact-candidate SFU commit; the pinned-stack gate proved native representation selection. Controlled recovery on this release, representative networks, all-UDP-blocked failure, public SFU 60 fps, and real-game synchronization remain unproven. Exact metrics live in [verification status](./verification-status.md).
+- The deployed application tree passed TypeScript, 613 Web tests, both builds, hygiene, two independent reviews, immutable artifact verification, and production postflight. Earlier exact-production gates closed direct/browser-relay VP8 cadence, active-audio ceilings, a single-representation SFU baseline, and one controlled exact-candidate SFU commit; the pinned-stack gate proved native representation selection. The lighter representation's mixed-route quality effect, controlled recovery on this release, representative networks, all-UDP-blocked failure, public SFU 60 fps, and real-game synchronization remain unproven. Exact metrics live in [verification status](./verification-status.md).
- Chrome loopback, cap2/cap3, short resource, recovery, MBB, and A/V fixtures are bounded evidence only. They do not establish quality, resource limits, or product policy.
## Current Priority
-1. Correct the SFU lower-representation cost without removing constrained-Viewer support, then repeat controlled active-SFU recovery and finish real-network route, screen-audio, and real-game A/V acceptance. VP8 acceleration, mobile lifecycle, Native, distribution, and repository simplification remain later.
+1. Verify the deployed lower-representation quality effect on a mixed P2P/SFU room, then repeat controlled active-SFU recovery and finish real-network route, screen-audio, and real-game A/V acceptance. VP8 acceleration, mobile lifecycle, Native, distribution, and repository simplification remain later.
The desktop Host background/minimized report is deferred until it reproduces on current production with a real game and synchronized media plus CPU/GPU evidence. The bounded current-Chrome screening found no immediate Host-page lifecycle drop, and removal of the old harmful `contentHint = "motion"` remains a plausible confound rather than a proven background fix. Mobile Viewer playback and assigned-relay survival remain a separate lifecycle gate.
diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.md
index ec0ec954..efc80ed8 100644
--- a/docs/research/realtime-quality-adaptation.md
+++ b/docs/research/realtime-quality-adaptation.md
@@ -12,7 +12,7 @@ game UI, maps, subtitles, and text become unreadable; `maintain-resolution`
may instead lower frame rate. Neither preference overrides congestion control.
Production runs exact deployed application/runtime revision
-`e14eb0e3e62731a43dca8ff92fa6d5165c8267a3`, release `e14eb0e`. Current Browser source and production use
+`be53c4d5794d38d5d406c876309958d7117ee601`, release `be53c4d`. Current Browser source and production use
strict `screener-v12`, fixed VP8, no video `contentHint`, and no codec UI,
quality state, or wire field. They use `balanced` as the recommended profile
and advanced default;
@@ -340,8 +340,7 @@ SFU publication explicitly uses VP8 with no backup codec. The UI and quality
wire expose no codec choice. Codec/profile/encoder stats remain diagnostic and
do not authorize automatic switching, route changes, or another controller.
Production runs exact deployed application/runtime revision
-`1d8761528d0dba43fb6d818df3934483ba2f5340`, release `1d87615`; canonical
-`main` contains newer SFU source pending deployment. Current source and production implement
+`be53c4d5794d38d5d406c876309958d7117ee601`, release `be53c4d`. Current source and production implement
this strict `screener-v12` contract.
Chromium maps video `contentHint = "motion"` to libwebrtc `kFluid`, and
diff --git a/docs/status.md b/docs/status.md
index fc86f85a..ebf342f9 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -6,14 +6,14 @@ This is the current execution index. Git history owns completed timelines; [veri
## Production
-- `https://share.bonfire.icu` runs exact deployed application/runtime revision `e14eb0e3e62731a43dca8ff92fa6d5165c8267a3`, release `e14eb0e`, wire `screener-v12`, from `/opt/screener/releases/e14eb0e`; that revision is integrated in canonical `main`. Its immutable runtime tar SHA-256 is `59368004dce38a8497aef46fa27c052884208ae90fa1a9fad6981084f8d408d5`, and its 39-file manifest SHA-256 is `36c5d7594ec9c8e96e98dab25c652de5ee69bf0419c2df4b26a20d5d1c887773`.
-- `screener`, LiveKit, coturn, and nginx are active/running; local/public `/healthz` and the served Browser asset match the immutable release, and all four services report `NRestarts=0`. The main Browser asset is `assets/index-Bjcb0_oa.js` with SHA-256 `87405412b926b7b6227801b706fd5eee61b8b907bba8629813315876a526c055`; predecessor asset `assets/index-DfMqhOXY.js` returns 404.
-- The service process resolves its working directory to exact release `e14eb0e`; it has no writable room `StateDirectory` or SQLite runtime.
+- `https://share.bonfire.icu` runs exact deployed application/runtime revision `be53c4d5794d38d5d406c876309958d7117ee601`, release `be53c4d`, wire `screener-v12`, from `/opt/screener/releases/be53c4d`; that revision is integrated in canonical `main`. Its immutable runtime tar SHA-256 is `5c174c30ffacd98738a364b825b915b84432823c261272684937361be2451144`, and its 39-file manifest SHA-256 is `c34dba43a25c6b8447e1153a5be3191bf82cff94117ed31edc325d3f7cf8541f`.
+- `screener`, LiveKit, coturn, and nginx are active/running; local/public `/healthz` and the served Browser asset match the immutable release, and all four services report `NRestarts=0`. The main Browser asset is `assets/index-BKEVI7Ux.js` with SHA-256 `22114fc8a26b3f03f37973555433d1e73d52d1c7b76fa3c7cc597500823bd62d`; predecessor asset `assets/index-Bjcb0_oa.js` returns 404.
+- The service process resolves its working directory to exact release `be53c4d`; it has no writable room `StateDirectory` or SQLite runtime.
- 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, a room-lived 22-character Viewer grant, and exactly `open | private` code entry. Private rooms without a password are invitation-only; configuring one additionally permits matching code-and-password entry. LiveKit remains dedicated with `room.auto_create: false`, `max_participants: 21`, and global admission `1` publication ingress / `20` subscription egress.
- Production media ports remain STUN-only UDP 3478 and LiveKit UDP 7882; coturn TCP/TLS, port 5349, media TCP, and relay ranges are disabled. The public Web ingress remains TCP 80/443; Node 8787 and LiveKit control/signaling 7880 are internal-only. The stable `inet bonfire_filter` table SHA-256 is `afaf9d066e9f292d8bd19032b38c0978ccf60dd01c2fe7f210968ff751f90534`; the dynamic fail2ban table is excluded from that identity.
- SFU subscribers reconcile Host screen publications across connect, activation, participant arrival, track publication, and reconnect. LiveKit runs at `warn`/Pion `error`, and the Screener unit waits boundedly for the same-host LiveKit control listener before startup. The decoded-progress cadence correction is deployed; the earlier subscriber-PC closure remains only the reproduction, so a controlled recovery transaction and physical network-loss evidence remain open.
- Production Browser SFU publisher and subscriber PCs explicitly use empty external ICE-server lists while retaining LiveKit-signaled UDP candidates. The owner verified that the deployed isolation fixes the reported SFU connection failure; the prior P1 core-route hold is closed.
-- Production leaves video `contentHint` unset, keeps audio `contentHint = "music"`, and fixes Browser direct, browser-relay, and SFU video to VP8 without codec UI, quality state, wire fields, or fallback media codecs. Its SFU publisher leaves screen-share layers to pinned LiveKit's half-resolution plus original-resolution defaults, enables Dynacast and server send-side BWE, keeps AdaptiveStream disabled, and adds no Screener layer selector.
+- Production leaves video `contentHint` unset, keeps audio `contentHint = "music"`, and fixes Browser direct, browser-relay, and SFU video to VP8 without codec UI, quality state, wire fields, or fallback media codecs. Its SFU publisher supplies LiveKit one half-actual-resolution lower preset capped at 30 fps with proportional bitrate beside the original representation, enables Dynacast and server send-side BWE, keeps AdaptiveStream disabled, and adds no Screener layer selector.
## Current Source
@@ -25,11 +25,11 @@ This is the current execution index. Git history owns completed timelines; [veri
- Current source leaves video `contentHint` unset and keeps audio `contentHint = "music"`. Browser direct and browser-relay offers contain VP8 as their only media codec. SFU publication fixes VP8 with no backup codec and supplies LiveKit one half-actual-resolution lower preset capped at 30 fps with proportional bitrate beside the original representation; Dynacast, the default maximum subscriber ceiling, server send-side BWE, and disabled AdaptiveStream remain unchanged. Codec UI, quality state, wire fields, fallback media codecs, and share-lifetime codec branches are absent. Live 64/128/256 kbps audio-ceiling mutation remains unchanged; ordinary Host and SFU publisher metrics select the exact current sender, relays reconcile audio-track additions and removals on the persistent stream, and an SFU reconnect reacquires the exact current publication/sender, avoids unchanged parameter/stat resets, or fails the route closed.
- Current source implements typed first-frame Viewer presentation and recovery, Chinese user-facing route/access failures, local connection details without a diagnostic-file export, authenticated Host-only on-demand route snapshots for automatic acceptance, explicit missing-room presentation, and responsive entry controls. Host invitation controls remain independent from two-state room-code entry.
- Recommended quality remains exactly `1080p60`, `1080p30`, and `720p30`; current source defaults to `1080p30`. Advanced resolution adds `480p` as `854x480` without adding a fourth preset, and advanced FPS and bitrate remain independent.
-- The deployed application tree passed repository hygiene, TypeScript, all 611 Web tests in 44 files, both production builds, and immutable artifact/postflight checks. Earlier exact-production gates exercised direct, browser-relay, SFU audio continuity and all three audio ceilings, and sustained about 59.5 fps on direct and browser-relay paths; the pinned-stack gate proved native two-representation selection before deployment. Exact applicability remains in [verification status](./verification-status.md).
+- The deployed application tree passed repository hygiene, TypeScript, all 613 Web tests in 44 files, both production builds, two independent reviews, and immutable artifact/postflight checks. Earlier exact-production gates exercised direct, browser-relay, SFU audio continuity and all three audio ceilings, and sustained about 59.5 fps on direct and browser-relay paths; the pinned-stack gate proved native two-representation selection. The new lower representation's mixed-route quality effect still needs production media evidence. Exact applicability remains in [verification status](./verification-status.md).
## Current Milestone
-1. Deploy and verify ADR-0007's implemented lightweight half-resolution representation, then repeat the controlled active-SFU recovery transaction on exact production and finish representative ICE/STUN/SFU acceptance including screen-audio continuity and real-game A/V sync on mobile and heterogeneous networks. Browser port prediction, NAT classification, TCP probing, fake page keepalive, and quality-driven reparenting remain outside the accepted model.
+1. Verify ADR-0007's deployed lightweight half-resolution representation in a mixed P2P/SFU room, then repeat the controlled active-SFU recovery transaction on exact production and finish representative ICE/STUN/SFU acceptance including screen-audio continuity and real-game A/V sync on mobile and heterogeneous networks. Browser port prediction, NAT classification, TCP probing, fake page keepalive, and quality-driven reparenting remain outside the accepted model.
## Active Boundaries
diff --git a/docs/todo.md b/docs/todo.md
index 54075721..014c0ffd 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -6,7 +6,7 @@ Only items in **Now** are executable after their stated decision gate. A branch
## Now
-1. **Deploy and verify constrained SFU publication quality.** Current source keeps the two LiveKit-owned VP8 spatial representations, Dynacast, send-side BWE, and no AdaptiveStream. It derives the half-actual-resolution lower publication preset at no more than 30 fps with proportional bitrate and retains that option for LiveKit-owned source replacement or republish; it does not mutate LOW behind the SDK's Dynacast lock. In the same mixed P2P/SFU dynamic-source gate, verify that HIGH recovers materially, P2P does not regress, and a constrained SFU downlink still selects and decodes LOW before deployment. Do not restore global `motion`, add more simulcast encodings, return to single HIGH, or add a Screener layer selector.
+1. **Verify deployed constrained SFU publication quality.** Production keeps the two LiveKit-owned VP8 spatial representations, Dynacast, send-side BWE, and no AdaptiveStream. It derives the half-actual-resolution lower publication preset at no more than 30 fps with proportional bitrate and retains that option for LiveKit-owned source replacement or republish; it does not mutate LOW behind the SDK's Dynacast lock. In the same mixed P2P/SFU dynamic-source gate, verify that HIGH recovers materially, P2P does not regress, and a constrained SFU downlink still selects and decodes LOW. Do not restore global `motion`, add more simulcast encodings, return to single HIGH, or add a Screener layer selector.
2. **Finish real-network route acceptance.** Repeat the controlled active-SFU recovery transaction on exact production. Then measure standard ICE/STUN direct paths, peer relay, SFU ingress/subscription, relay-ingress repair with subtree retention, disconnect/capacity drain, Pause/Resume, screen-audio continuity and real-game A/V sync across representative IPv4/IPv6 NATs and mobile networks. Include Host and Viewer TUN/VPN cases and an all-UDP-blocked case to distinguish an application ICE-option defect from operating-system interception and establish bounded explicit failure. Do not add another watchdog, port prediction, NAT classification, TCP probes, guessed candidates, route scores, or quality-driven reparenting.
## Accepted Later Roadmap
diff --git a/docs/verification-status.md b/docs/verification-status.md
index 51bc4a7d..9a7d4f88 100644
--- a/docs/verification-status.md
+++ b/docs/verification-status.md
@@ -10,15 +10,15 @@ Capacity and routing entries below describe the exact tested source or release o
## Deployment Evidence
-- Production runs exact deployed application/runtime revision `1d8761528d0dba43fb6d818df3934483ba2f5340`, release `1d87615`, wire `screener-v12`, from `/opt/screener/releases/1d87615`; that revision is integrated in canonical `main`. The immutable runtime ZIP SHA-256 is `715480487059bf83516a34e0d1083b52437619838c46bdc26ca5967529a1cf05`; its 38-file manifest SHA-256 is `96845789560394ca20b16c37a8e7ddadc7b488876e32241709d0f7a577fdca26`.
-- Postflight found `screener`, LiveKit, coturn, and nginx active with zero restarts and no warning-level Screener journal entries. Local/public health and the served main Browser asset matched the release; `assets/index-DfMqhOXY.js` has SHA-256 `cf6dd1c46cc9414a87331a9312eec315ddce8fce565741284998aa0141b18d47`, while the prior main asset returns 404.
+- Production runs exact deployed application/runtime revision `be53c4d5794d38d5d406c876309958d7117ee601`, release `be53c4d`, wire `screener-v12`, from `/opt/screener/releases/be53c4d`; that revision is integrated in canonical `main`. The immutable runtime tar SHA-256 is `5c174c30ffacd98738a364b825b915b84432823c261272684937361be2451144`; its 39-file manifest SHA-256 is `c34dba43a25c6b8447e1153a5be3191bf82cff94117ed31edc325d3f7cf8541f`.
+- Postflight found `screener`, LiveKit, coturn, and nginx active with zero restarts and no warning-level Screener/LiveKit journal entries. Local/public health and the served main Browser asset matched the release; `assets/index-BKEVI7Ux.js` has SHA-256 `22114fc8a26b3f03f37973555433d1e73d52d1c7b76fa3c7cc597500823bd62d`, while the prior main asset returns 404.
- 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. Room authority is process-memory-only. Coturn is `stun-only`, `no-tcp`, and `no-tls`; only UDP 3478 listens, and nft exposes only UDP 3478/7882 for Screener media.
- The production service orders Screener after LiveKit and boundedly waits for its control listener. Media listeners remain STUN-only UDP 3478 and LiveKit UDP 7882 with no 5349, coturn TCP/TLS, relay range, ICE/TCP, or media TCP listener. The stable `inet bonfire_filter` table stayed unchanged through cutover at SHA-256 `afaf9d066e9f292d8bd19032b38c0978ccf60dd01c2fe7f210968ff751f90534`; the whole ruleset is not used as an identity because fail2ban owns a dynamic address set.
- This application-only postflight proves archive identity, atomic application/assets, process health, and listener/firewall continuity. It did not re-exercise access, stale-wire rejection, direct, browser-relay, SFU, audio, codec, mobile, quality, or endurance behavior; those retained results remain revision-bounded below. Routine application-only releases do not maintain a full rollback/configuration backup; any future infrastructure or irreversible-state change requires recovery scoped to what it changes.
## Retained Functional Evidence
-- Exact deployed source `1d87615` passed repository hygiene, TypeScript typecheck, all 607 Web tests in 44 files, client and server production builds, three independent reviews, and production artifact/service postflight. Exact predecessor `b68c471` separately passed the 261-test SFU admission gate and explicit-Chrome access/privacy gate. Retained Chrome 20-Viewer and responsive visual checks apply only to their recorded predecessor revisions.
+- Exact deployed source `be53c4d` passed repository hygiene, TypeScript typecheck, all 613 Web tests in 44 files, client and server production builds, two independent reviews, pinned LiveKit encoding calculation, and production artifact/service postflight. Exact predecessor `b68c471` separately passed the 261-test SFU admission gate and explicit-Chrome access/privacy gate. Retained Chrome 20-Viewer and responsive visual checks apply only to their recorded predecessor revisions.
- Chrome 151 on exact production `1d87615` used real dynamic-tab `getDisplayMedia()` at 1822x1080 and made only the ordinary STUN peer attempt unusable so the existing route operation reached its SFU suffix. Publisher and subscriber LiveKit PCs retained empty external ICE-server lists and selected UDP. The publisher exposed one video sender encoding and one outbound video stats object, both without RID; over six seconds it encoded 180 frames while the subscriber decoded and rendered 182 frames, with bytes advancing at both ends. This closes the single-representation implementation/deployment gate without claiming public SFU 60 fps, real-game quality, heterogeneous-network behavior, or endurance.
- Chrome 151 on exact production `1d87615` used one continuously changing synthetic Browser stream while test-side policy made only ordinary STUN peer PCs unusable and left LiveKit unchanged. The Viewer observed direct prepare revision `1`, explicit rollback active revision `2`, SFU prepare revision `3`, exact-revision first-frame ready, then SFU active revision `3`; no ready was sent for the failed direct candidate. The final Host snapshot had no operation, parent/final route `sfu`, rejection `none`, and first-frame/final timing `10703/10703` ms within the unchanged 20-second total deadline. Host and Viewer LiveKit PCs had zero external ICE URLs, selected UDP, and advanced `58/57` frames plus bytes over the next two seconds. This closes the exact deployed controlled candidate rollback/SFU commit transaction, not physical capture, heterogeneous-network reachability, all-UDP-blocked failure, quality, or endurance.
- Chrome 151 on exact production `1d87615` formed `Host -> SFU -> relay -> child` plus a separate direct Viewer, passed Pause/Resume, and then locally closed the relay's subscriber PC. After 45,234 ms the relay remained assigned to SFU and sent no `route-media-unavailable`, `refresh-sfu`, or `route-failed`; its downstream child independently reported its own decoded stall and recovered through the other Viewer. Receiver-stats calls had stopped about 28.9 seconds before the final sample. Source inspection confirms that no video track stops SFU sampling while an empty merged report or failed stats read produces no deadline sample. This bounded fault injection exposes an active-cadence implementation gap; local `RTCPeerConnection.close()` does not reproduce physical UDP loss or prove LiveKit's real reconnect path, so relay-ingress recovery remains open.
@@ -38,11 +38,11 @@ Capacity and routing entries below describe the exact tested source or release o
## Open Proof Boundaries
- Routing: exact v10 local direct loopback remains historical evidence for admission-20 initial ingress. Exact v12 production closes one controlled ordinary-direct exhaustion, explicit rollback, and exact SFU first-frame commit transaction; the later subscriber-PC closure injection found the active-SFU cadence gap without proving physical loss recovery. Current source corrects that cadence while physical recovery remains open. Representative real-network direct/peer/SFU behavior, relay-ingress reparent with subtree retention, disconnect/effective-capacity drain, pause/resume, and bounded all-UDP-blocked failure remain open. 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: exact-production direct and Browser-relay VP8/no-hint cadence plus the deployed single-encoding SFU baseline are closed. ADR-0007's pinned gate separately proved LiveKit-owned selection between full- and half-resolution representations with server send-side BWE, and current source implements that combination; deployment, public SFU 60 fps, real-game quality, heterogeneous devices, and endurance remain open. Startup ramp is stock BWE behavior and does not authorize an SDP or application bitrate workaround.
+- Quality: exact-production direct and Browser-relay VP8/no-hint cadence plus the historical single-encoding SFU baseline are closed. ADR-0007's pinned gate separately proved LiveKit-owned selection between full- and half-resolution representations with server send-side BWE, and production now caps the half-actual-resolution lower representation at 30 fps with proportional bitrate. Its mixed-route HIGH recovery, constrained LOW delivery on this release, public SFU 60 fps, real-game quality, heterogeneous devices, and endurance remain open. Startup ramp is stock BWE behavior and does not authorize an SDP or application bitrate workaround.
- Host background: deferred until the report reproduces on exact production with a continuously changing real game or replay, a separate direct wired Viewer, synchronized capture/outbound/inbound plus CPU/GPU evidence, and repeated focused/unfocused/hidden/minimized windows. The current-Chrome Browser `getDisplayMedia()` WPF-window screening did not observe an immediate Host-page media drop, and the old harmful `contentHint = "motion"` release remains a plausible confound rather than a proven background cause. Current evidence authorizes no keepalive, Wake Lock, timer, codec switch, route change, or Native fallback.
- Relay resources: current source and production expose the authenticated `1/2/3` endpoint-cap boundary, and retained v10 local loopback evidence covers 20 Viewers at cap `2` only for that source. CPU/GPU/upload and heterogeneous-network measurements remain diagnostics, not authority to change the contract.
- Room scale: current source and production admit 20 Viewers plus one Host, and the retained v10 local Browser convergence gate covers that bound on direct loopback. A real public-network 1:20 session, quality, and sustained resource matrix remain open.
-- SFU: current source uses pinned-default half-resolution plus original-resolution simulcast, Dynacast, and the tracked server send-side-BWE setting without an application layer selector; production remains one Host encoding. Both use exact Viewer subscriptions and no fixed root-count or room-wide lease rule. Chrome 151 physically closed the empty-external-ICE-server connection hold and exact-production single-representation gate, while the separate pinned-stack gate proved native representation selection. Real LiveKit lifecycle/JWT replay, resource use, SFU-fed first-child behavior, and broader heterogeneous-network acceptance remain open.
+- SFU: current source and production use one half-actual-resolution lower representation capped at 30 fps plus the original representation, Dynacast, and the tracked server send-side-BWE setting without an application layer selector. Both use exact Viewer subscriptions and no fixed root-count or room-wide lease rule. Chrome 151 physically closed the empty-external-ICE-server connection hold and historical single-representation gate, while the separate pinned-stack gate proved native representation selection. The lighter lower representation's production quality effect, real LiveKit lifecycle/JWT replay, resource use, SFU-fed first-child behavior, and broader heterogeneous-network acceptance remain open.
- Audio: current v12 source and production select the exact active ordinary Host or SFU publisher audio sender, reset samples across track changes or absence, keep relay children synchronized with persistent-stream audio changes, and reacquire exact SFU publications/senders after reconnect. Chrome 151 on exact production `bf32859` physically closed the reported active-source `1 kbps` observation and all three live ceilings across direct, browser-relay and SFU. Audible game quality, heterogeneous-network changes and real-game A/V synchronization remain part of route acceptance; a muted/idle Opus track may still legitimately remain near 1 kbps.
- Observability: current v12 source and production keep local connection details but no Host/Viewer diagnostic downloads or Browser file-export plumbing. The Host-only bounded snapshot stays for automatic acceptance. Chrome 151 supplied selected candidate endpoints and ordinary-route A/V playout timestamps in the current gate, but omitted the SFU A/V timestamp. Target-browser availability and actual values remain open for codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, and broader jitter/concealment cases. All retained 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.