@torrent-tv/proxy 2.83.8 → 2.85.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 2.85.0
+
+- **Fix**: A VIEWER WHO HAS SAID NOTHING IS NOT ASSUMED TO BE WATCHING. `playing` started true on a viewer this proxy had never heard from, and the position is carried forward by the clock at that rate — so a page whose tab was hidden for 145 seconds, while it deliberately held start-up until it was shown, was placed **145.979 s** into a film it had not begun. Field 2026-09-14: that is the exact `-ss` the soundtrack's encoder was given, the browser was asking for segment #0, the map ranked #0 last of a hundred (`p1:#0..#13`), and the request was held 60 145 ms and answered 503. The moment the viewer left and the invented clock stopped, the plan asked for exactly the segment they had been asking for all along. A statement about somebody else's machine is theirs to make: until they make it the rate is zero.
+- **Fix**: THE POSITION IS BOUNDED BY WHAT THE VIEWER SAID THEY HELD — `position(now) = stated + rate × min(now − statedAt, held)`. Nobody can play past the end of what they have; a viewer who said "thirty seconds" and has said nothing for two minutes has played at most thirty of them. The bound binds only where the clock has outrun the cushion (a report lost, or a viewer starving) and there it under-states, which is the direction that costs an encoder rather than a viewer. In the field session above the cushion was 0.0 s throughout, so this alone would have held that viewer at zero whatever the rate said.
+- **Fix**: THREE STATES, NOT TWO. A picture that is not advancing was stopped either by the viewer — who then consumes nothing and can wait — or by us having delivered nothing, and that viewer is the most urgent there is. One boolean held two of the three and read the second as the first, so a viewer frozen for want of a segment counted as somebody who had chosen to stop and nothing of theirs fell due. `waiting` is stated beside `playing`, a viewer arrives waiting, and the priority map's upper band is for those watching OR waiting. A page one release behind states only `playing`, and its two states are told apart by the quantity it does state: stopped while holding film is a pause, stopped holding nothing is starvation.
+- **Fix**: A LINK MEASUREMENT IS NO LONGER THE TICKET FOR A VIEWER'S OWN REPORT. The same condition stood in three places — the page, this route, and the session manager — and a page measures its link from completed transfers, so a page that has not been delivered a segment has no figure at all. Field 2026-09-14: one transfer completed in the whole session, the median needs two, and every report the page tried to send — the pauses, the starvation, the tab going hidden — was dropped. The link figure is one field now, kept only when it is a measurement.
+- **Fix**: The second presence detector threw instead of working. `makeSendQueueWatcher` called `connectionGone`, a function of the factory that is not in its scope, so the watch that exists because `onClosed` does not always come raised a `ReferenceError` inside its own timer and left the viewer registered for the life of the process.
+- **New**: `GET /api/link-probe?bytes=N` — bytes a browser can time its link with before any film has been chosen. Bounded at 2 MiB, which is 336 Mbit/s inside the browser's minimum measurable transfer and twenty-eight times the top rung this product offers. Not `delivery-sink`, which is the load stand's and answers any size asked for.
+- **New**: A refusal says WHY, in the viewer's terms and not only in this proxy's log: the 503 for a segment that is not ready carries a `reason`, and where the priority map is working further along the film it says so. The reason existed sixty seconds before the failure of 2026-09-14 and travelled nowhere.
+- **New**: `peerWaiting=` on the delivery-probe line — how many requests the far end says it is still waiting for. The browser has sent it twice a second since the probe echo was built and nothing read it. Evidence, not a verdict: the receiver declares its own transport lost, because it knows first — on 2026-09-06 it said so sixteen minutes before this end did.
+- **Chore**: Taking in a viewer's report leaves the session manager for `services/viewer/report-intake.js`, and `Viewer.deadlineAt` is deleted — nothing consumed it, and when a second of film falls due is the priority map's answer. The manager is 18 lines shorter.
+- **New**: `test/viewer-states.test.js` — twelve checks over the three states, the bound, the cold open of 2026-09-14 with its own 146 seconds, and a report carrying no link measurement. `test/link-probe.test.js` covers this end of the probe; how big an ask has to be is checked where that function lives, in the page's own repository.
+
+## 2.84.0
+
+- **Fix**: WHERE A VIEWER IS HAS ONE WRITER AND IS A FUNCTION OF TIME. It had two: a seek wrote `position.seeked`, a segment request overwrote `position.seconds`, and the reading preferred whichever was set — so the two took turns and the priority map jumped backwards and forwards several times a second. Field 2026-09-13, one output over one second: `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, with the second viewer stopped dead at 1673.6 s throughout. Encoder placement follows the map, as it must, so the machine spent six minutes on **77 starts and 141 stops against one normal end**, produced almost nothing, and both browsers sat frozen with empty buffers while the swarm delivered 3 MB/s from 129 peers. A segment request now says only that the viewer is still here; where they are is what they state, and between statements it is carried forward by the clock at the rate the film moves — `position(now) = stated + (playing ? 1 : 0) × (now − statedAt)`. Continuous and monotone by construction, so nothing derived from it can dither.
+- **Fix**: A picture starved of data is no longer reported as moving. `paused` is false while an element waits for bytes, so a frozen player told the proxy it was playing and the position walked away from where the viewer actually stood — the exact case a frozen player is in. It is `readyState >= HAVE_FUTURE_DATA` as well now, and `waiting` joins `pause`/`playing`/`ended` in the events that report at once rather than waiting out the ten-second interval.
+- **Fix**: PRESENCE IS THE CONNECTION AND ONLY THE CONNECTION. Silence longer than "any silence a watching viewer can produce" used to end it, and there is no such interval: a paused viewer, a hidden tab whose timers the browser has throttled, and one holding two minutes of cushion all say nothing and are all still watching. A viewer is here until something says otherwise — the browser releasing the session, or the connection closing. `presenceStaleAfterMs` and every threshold it fed are gone.
+- **Fix**: A soundtrack begins where the earliest viewer of the picture stands, with nothing subtracted. What that replaced was an apparatus for turning a request edge back into a playhead: three position sources ranked by priority, a second function naming which had answered, a subtraction of the deepest reported buffer, and a special case for a session nobody had asked anything of yet. Each repaired a quantity that meant two things. Field 2026-08-31, what it cost: a page opened at 588 s started its sound at 460 s — 131 seconds of film nobody would hear, and the segment the viewer needed took 38.8 s against the picture's 8.4 s.
+- **Chore**: `resolveViewerPosition`, `viewerPositionSource`, `#viewerPositionSourceOf`, `#consumerPositionOf`, `#noteConsumerHead`, `session.lastRequestedSegment`, `session.furthestViewerSeconds` and `headsOf` are deleted. Where a viewer is now lives in the viewer's own layer (`viewer/positions.js`), and the session manager is 250 lines shorter for it.
+- **Chore**: The flag that pins a rung's size is `exactSize`, not `manualQuality`, and the key it writes reads `enc:1280x720:exact` rather than `:manual`. It says nothing about who asked — every rung of a master sets it, whether the viewer picked that rung or the player moved itself onto one — and the old name was read as "the viewer did this" four times in a few weeks, in field logs where the viewer had touched nothing. The log line says `size=exact` for the same reason. Requires server 0.27.14 or newer in the page.
+- **New**: `test/plan-is-steady.test.js` — five checks that the placement does not move while the facts do not, over the whole chain from what a viewer states to what the plan answers, with the field's own two positions. Confirmed to go red on the reading this release replaced.
+
 ## 2.83.8
 
 - **New**: THE BROWSER'S OWN LOG IS KEPT BESIDE THE PROXY'S, ON A DISK THAT SURVIVES. Explaining any failure here needs both halves — what the proxy did and what the page saw — and the second half went to the registry server's standard output on the droplet, which every release of it destroys. On 2026-09-13 a viewer reported a desync and a frozen picture and the analysis ran on half the evidence for exactly that reason. `POST /api/client-logs` on the proxy writes them into the same directory as its own log (`/data` on the addon host), one file per viewing session: `client-<start>-<session>-<film>-<infohash>.log`. The start time and the session id are what join the two halves without guessing, and the film says which one it is without opening the file. Seven checks over the writer, one confirmed to go red.

package/CLAUDE.md

@@ -89,9 +89,11 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     why the priority map is read at two scopes (per FILE for the swarm, per
     OUTPUT for the encoders), and what each of the eight other places that used
     to place or kill an encoder now states instead.
-  - `docs/logs.md` — where to find logs (HA `docker logs` + `/data/proxy.log`, DO
-    `infra-server-1` with forwarded frontend `POST /api/client-logs`). Browser
-    console not needed.
+  - `docs/logs.md` — where to find logs, and the fact that the BROWSER's own log
+    is in TWO places split by phase: on the droplet while a transport is being
+    acquired and at unload, on THIS proxy for the whole of a viewing
+    (`/data/client-<start>-<session>-<torrent>.log`, one file per session).
+    Read both before concluding anything from a half-session.
   - `playback-planner.js` — single ffmpeg probe returns audioCodec, videoCodec,
     container, durationSeconds. `mode` is advisory; the browser decides.
   - `hls-session-manager.js` — one ffmpeg per (source, file, settings). Serves a

package/docs/encode-architecture.md

@@ -28,12 +28,37 @@ It decides from four things and no others:
 name a consumer id, or hold a person. What crosses is a priority map: zones of
 segment numbers with a rank and a real time, and nobody's name on it.
 
+## Where a viewer is, and how it reaches the encoders
+
+A viewer's position has ONE writer — the viewer — and is a function of time:
+
+```
+position(now) = stated + (playing ? 1 : 0) × (now − statedAt)
+```
+
+A viewer whose picture moves covers a second of film every second, so between
+the moments they speak their position is known exactly; one whose picture is
+stopped covers nothing. Nothing else writes it, and in particular a request for
+a segment does not: a request says the viewer is still here, and the segment
+either exists and is served or does not and is waited for.
+
+Held as a stored number instead it was a staircase, flat for the ten seconds
+between reports and then a jump — and with two writers filling it in turn the
+steps went backwards as often as forwards. Field 2026-09-13, one output over one
+second: `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, while
+the second viewer sat frozen at 1673.6 s. The placement follows the map, so the
+machine spent six minutes on 77 encoder starts and 141 stops.
+
+PRESENCE IS A SEPARATE FACT and it is the connection: a viewer is here until
+something says otherwise. Silence never says it — a pause, a hidden tab whose
+timers are throttled, and a full cushion are all silent and all still watching.
+
 ## Viewers become a map, and that is the whole crossing
 
 ```mermaid
 flowchart TB
   subgraph V["services/viewer — where people are"]
-    VW[Viewer<br/>position, playing, buffered, chosen track]
+    VW[Viewer<br/>position as a function of time, playing, buffered, chosen track]
     VS[Viewers<br/>the relation, indexed from both ends]
   end
 

package/docs/logs.md

@@ -1,51 +1,97 @@
-# Logs — where to look
-
-All logs are visible via container `docker logs`, no browser console copy-paste needed.
-
-## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
-
-Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
-
-- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
-- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
-  A worker thread loads its own instance of every module, so the logger's file
-  handle — set once, on the main thread — was null in the worker for the life of
-  the process. Measured over a whole 49 938-line file: zero lines from the piece
-  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
-  torrent pool, against 52 and 36 of them in `docker logs`, which every release
-  destroys. The worker now sends its lines to the main thread, which is the only
-  writer; a line from there reads `torrent-worker: …`.
-- Via container:
-  ```bash
-  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
-  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
-  ```
-- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
-- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
-
-SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
-
-## DO server (webauth.courses, `infra-server-1`)
-
-- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
-- Frontend logs are forwarded: browser batches `{sessionId, tag, signalSessionId, lines: [{level,ts,msg}]}` and `POST`s to `https://webauth.courses/api/client-logs` (`server/routes/api/client-logs/post.js:56`), server does `console.log` with prefix `[client <tag> <id> sig=<webrtcSessionId>]`. They appear together with backend logs in the same container.
-- Via container:
-  ```bash
-  ssh do "docker logs infra-server-1 --tail 200 | cat"
-  # filter a single viewing:
-  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
-  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
-  ```
-- No need to open eruda or copy browser console on phone — it is already in `infra-server-1` logs.
-
-## Quick triage
-
-- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
-- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
-- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
-
-## Related
-
-- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
-- `docs/container-architecture.md` — what container/track classes log and where.
-- `server/routes/api/client-logs/post.js:1` — sanitization (control chars → space, `MAX_LINES 50`, `MAX_MSG_LEN 2000`).
+# Logs — where to look
+
+No browser console copy-paste is needed: the page forwards its own log. But it
+lands in TWO places depending on the phase of the session, and `docker logs` is
+only one of them — see "Browser logs are in TWO places" below before concluding
+anything from a half-session.
+
+## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
+
+Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
+
+- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
+- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
+  A worker thread loads its own instance of every module, so the logger's file
+  handle — set once, on the main thread — was null in the worker for the life of
+  the process. Measured over a whole 49 938-line file: zero lines from the piece
+  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
+  torrent pool, against 52 and 36 of them in `docker logs`, which every release
+  destroys. The worker now sends its lines to the main thread, which is the only
+  writer; a line from there reads `torrent-worker: …`.
+- Via container:
+  ```bash
+  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
+  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
+  ```
+- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
+- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
+
+SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
+
+## DO server (webauth.courses, `infra-server-1`)
+
+- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
+- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
+- Via container:
+  ```bash
+  ssh do "docker logs infra-server-1 --tail 200 | cat"
+  # filter a single viewing:
+  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
+  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
+  ```
+- No need to open eruda or copy the browser console on a phone — it is forwarded.
+
+## Browser logs are in TWO places, split by phase — read both
+
+Until 2026-09-13 the page's whole log went to the droplet's standard output,
+which every release of the server destroys. A viewer reported a desync and a
+frozen picture that day and the analysis ran on half the evidence, so the log
+moved to the proxy — beside the proxy's own, on the same durable directory.
+
+The split is by PHASE, and neither half is the whole session:
+
+1. **Before a transport exists** — the page opening, the proxy being chosen, a
+   connection failing — there is nowhere else to send it, so it goes to the
+   SERVER (`infra-server-1`);
+2. **From the moment the data channel is up**, the page's logger is given a
+   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
+   over that channel. This is the bulk of a viewing;
+3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
+   thing a page that is going away can use, and a data channel is not;
+4. **A batch that cannot reach the proxy** falls back to the server.
+
+So a session that failed while connecting is on the droplet, a session that
+failed while playing is on the addon host, and a complete reading of a long
+failure needs both.
+
+### The files on the proxy
+
+One file per viewing session, in the proxy log's own directory (`/data` on the
+addon host), named so the two halves join without guessing:
+
+```
+client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
+```
+
+A session that has not chosen a torrent yet writes `no-torrent-yet` in that
+last part — the file is keyed by the session id, not by the name, so choosing a
+torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
+
+```bash
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
+```
+
+Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
+
+## Quick triage
+
+- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
+- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
+- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
+
+## Related
+
+- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
+- `docs/container-architecture.md` — what container/track classes log and where.
+- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.83.8",
+  "version": "2.85.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/link-probe/get.js

@@ -0,0 +1,51 @@
+/**
+ * @file `GET /api/link-probe?bytes=N` — bytes to measure the link with.
+ *
+ * WHY THIS EXISTS. A viewer's link is measured from completed transfers, and
+ * the only transfers that counted were segments of the film. So the figure came
+ * into being after playback had begun — after the quality offer had been made,
+ * and after the start-up decisions that want it. Worse, the page's report of
+ * its OWN facts was skipped when there was no figure, so at a cold open — the
+ * moment where where-the-viewer-is matters most — the page said nothing at all
+ * (2026-09-14).
+ *
+ * There is nothing to wait for: a proxy can send bytes the moment its channel
+ * is up, which is when the page opens rather than when a film is chosen.
+ *
+ * NOT `delivery-sink`, which is the load stand's and answers any size asked
+ * for. This is part of the product, always on, and bounded — the browser's own
+ * sizing stops at 2 MiB and this refuses more, so a caller cannot turn it into
+ * a way of drawing a proxy owner's uplink.
+ *
+ * The body is zeros. What is being measured is the wire, and zeros cross it at
+ * the same speed as anything else; producing them costs one allocation.
+ */
+
+/**
+ * The most this route will send for one ask.
+ *
+ * The figure is only ever used to decide what a link can carry, and the most
+ * anything this product offers is a 1080p rung at around 12 Mbit/s. Two
+ * mebibytes inside the browser's minimum measurable transfer (50 ms) is
+ * 336 Mbit/s, twenty-eight times that rung: a link too fast to time at this
+ * size is beyond anything a decision here distinguishes.
+ */
+export const MAX_LINK_PROBE_BYTES = 2 * 1024 * 1024;
+
+/**
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @returns {Promise<void>}
+ */
+export async function handleApiLinkProbeGet(req, reply) {
+  const asked = Number(/** @type {{ bytes?: string }} */ (req.query)?.bytes);
+  if (!Number.isFinite(asked) || asked <= 0) {
+    return reply.code(400).send({ error: "bytes (>0) is required." });
+  }
+  const bytes = Math.min(Math.floor(asked), MAX_LINK_PROBE_BYTES);
+  return reply
+    .code(200)
+    .header("Content-Type", "application/octet-stream")
+    .header("Cache-Control", "no-store")
+    .send(Buffer.alloc(bytes));
+}

package/routes/api/transcode-sessions/net-report/post.js

@@ -1,64 +1,84 @@
-/**
- * Accept a viewer link report for a transcode session (adaptive bitrate).
- * The browser measures its own data-channel throughput per segment fetch and
- * posts a rolling median + its buffered seconds; the session manager's budget
- * loop uses the latest report as the link-deficit downshift trigger.
- *
- * POST /api/transcode-sessions/:sessionId/net-report
- * Body: { linkMbps: number, bufferedAheadSec: number,
- *         consumerId?: string, positionSeconds?: number }
- *
- * `consumerId` and `positionSeconds` say WHO is reporting and WHERE they are.
- * A copied picture is one session shared by every viewer of it, so without them
- * the proxy could only act on whichever viewer reported last. Both are
- * optional: a browser that sends neither is treated exactly as before.
- *
- * Best-effort telemetry: invalid body → 400, unknown session → 404, ok → 204.
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
- * @returns {Promise<void>}
- */
-export async function handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager }) {
-  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
-  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
-  const linkMbps = Number(body.linkMbps);
-  const bufferedAheadSec = Number(body.bufferedAheadSec);
-  if (!sessionId || !Number.isFinite(linkMbps) || linkMbps <= 0 || !Number.isFinite(bufferedAheadSec) || bufferedAheadSec < 0) {
-    return reply.code(400).send({ error: "linkMbps (>0) and bufferedAheadSec (>=0) are required." });
-  }
-
-  // Neither is required, and neither can make a report invalid: they are what
-  // the proxy uses to tell the viewers of one session apart, and a report
-  // without them is still a truthful reading of somebody's link.
-  const consumerId = typeof body.consumerId === "string" ? body.consumerId.trim() : "";
-  // Whether the picture is moving. Absent from a page that does not say, and
-  // then the viewer counts as playing, which is what every page meant before it
-  // could say otherwise.
-  const playing = typeof body.playing === "boolean" ? body.playing : undefined;
-  // Whether the page is on screen, and whether the picture was pulled out of
-  // it. A hidden tab has its timers throttled, so it asks for nothing and looks
-  // exactly like a viewer holding a full cushion; picture-in-picture is the case
-  // that makes the distinction necessary, because there the tab is hidden and
-  // the viewer is watching. Absent from a page that does not say, and then the
-  // viewer is on screen, as every page meant before it could say otherwise.
-  const onScreen = typeof body.onScreen === "boolean" ? body.onScreen : undefined;
-  const inPictureInPicture =
-    typeof body.inPictureInPicture === "boolean" ? body.inPictureInPicture : undefined;
-  const positionSeconds = Number(body.positionSeconds);
-  const recorded = hlsSessionManager.recordNetReport(sessionId, {
-    linkMbps,
-    bufferedAheadSec,
-    consumerId,
-    playing,
-    onScreen,
-    inPictureInPicture,
-    positionSeconds:
-      Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
-  });
-  if (!recorded) {
-    return reply.code(404).send({ error: "Transcode session was not found." });
-  }
-  return reply.code(204).send();
-}
+/**
+ * Accept a viewer link report for a transcode session (adaptive bitrate).
+ * The browser measures its own data-channel throughput per segment fetch and
+ * posts a rolling median + its buffered seconds; the session manager's budget
+ * loop uses the latest report as the link-deficit downshift trigger.
+ *
+ * POST /api/transcode-sessions/:sessionId/net-report
+ * Body: { linkMbps: number, bufferedAheadSec: number,
+ *         consumerId?: string, positionSeconds?: number }
+ *
+ * `consumerId` and `positionSeconds` say WHO is reporting and WHERE they are.
+ * A copied picture is one session shared by every viewer of it, so without them
+ * the proxy could only act on whichever viewer reported last. Both are
+ * optional: a browser that sends neither is treated exactly as before.
+ *
+ * Best-effort telemetry: invalid body → 400, unknown session → 404, ok → 204.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  // WHAT THIS REPORT IS. A statement by one viewer about itself: where the
+  // picture is, how much film it holds, whether it is moving, whether it is
+  // blocked on us, whether the page is on screen — and, when there has been
+  // anything to measure, how fast the link carried it.
+  //
+  // THE LINK FIGURE IS NOT REQUIRED, and requiring it is the fault of
+  // 2026-09-14. A page measures its link from completed transfers, so a page
+  // that has not yet been delivered a segment has no figure; at a cold open
+  // that is every page. Rejected here with 400, the page's own account of
+  // itself never arrived, this proxy filled the silence by assuming the film
+  // was running, and a viewer who had not seen a frame was placed 146 seconds
+  // into it — the soundtrack's encoder went there, and the segment the browser
+  // was actually asking for was ranked last of a hundred and answered 503.
+  const linkMbps = Number(body.linkMbps);
+  const bufferedAheadSec = Number(body.bufferedAheadSec);
+  if (!sessionId || !Number.isFinite(bufferedAheadSec) || bufferedAheadSec < 0) {
+    return reply.code(400).send({ error: "bufferedAheadSec (>=0) is required." });
+  }
+
+  // Neither is required, and neither can make a report invalid: they are what
+  // the proxy uses to tell the viewers of one session apart, and a report
+  // without them is still a truthful reading of somebody's link.
+  const consumerId = typeof body.consumerId === "string" ? body.consumerId.trim() : "";
+  // Whether the picture is moving. Absent from a page that does not say, and
+  // then nothing is assumed: a statement about somebody else's machine is
+  // theirs to make, and assuming it walked a viewer 146 seconds into a film
+  // they had not begun (2026-09-14).
+  const playing = typeof body.playing === "boolean" ? body.playing : undefined;
+  // Whether this viewer is BLOCKED on material we owe them, which is a
+  // different state from having stopped the picture: the first is the most
+  // urgent viewer there is, the second consumes nothing and can wait. One
+  // boolean could not hold three states and read the first as the second.
+  const waiting = typeof body.waiting === "boolean" ? body.waiting : undefined;
+  // Whether the page is on screen, and whether the picture was pulled out of
+  // it. A hidden tab has its timers throttled, so it asks for nothing and looks
+  // exactly like a viewer holding a full cushion; picture-in-picture is the case
+  // that makes the distinction necessary, because there the tab is hidden and
+  // the viewer is watching. Absent from a page that does not say, and then the
+  // viewer is on screen, as every page meant before it could say otherwise.
+  const onScreen = typeof body.onScreen === "boolean" ? body.onScreen : undefined;
+  const inPictureInPicture =
+    typeof body.inPictureInPicture === "boolean" ? body.inPictureInPicture : undefined;
+  const positionSeconds = Number(body.positionSeconds);
+  const recorded = hlsSessionManager.recordNetReport(sessionId, {
+    linkMbps: Number.isFinite(linkMbps) && linkMbps > 0 ? linkMbps : undefined,
+    waiting,
+    bufferedAheadSec,
+    consumerId,
+    playing,
+    onScreen,
+    inPictureInPicture,
+    positionSeconds:
+      Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
+  });
+  if (!recorded) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+  return reply.code(204).send();
+}