@torrent-tv/proxy 2.80.13 → 2.80.15

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 2.80.15
+
+- **Fix**: THE SPINNER CARAVAN, and its cause was one coercion. The priority map states `withinSeconds: null` for the film BEHIND the viewers — nobody is waiting there — and `deadlineReaderFor` read it through `Number()`, where `null` is 0. So the film a viewer had already passed was due IMMEDIATELY and was the most urgent material in the file. It bought encoders, and it took the run standing in front of the viewer because that run was the nearest body to it, and it did so again on every pass. Field 2026-09-08: 39 moves in one session, 24 of them between three adjacent numbers about 0.8 s apart, one viewer on a host affording three runs got three, and the picture stood still for 116.7 s in three interruptions, the worst 91.8 s. The map has said it plainly in every session's log; this line turned it into its opposite. Fourth time in this repository that the input to a calculation was not what the calculation assumed.
+- **Fix**: The objective is the map's OWN rank order, as a vector compared position by position — one pair per rank the map states, most urgent first: how long anybody waits at that rank, then when the last number of it is made. It was three seconds-valued terms with the ten ranks collapsed into two buckets, and "never" for the film behind is the film's own length — 2024 s on a 48-minute file — which outvotes everything above it. No weights, and none possible: a weight would let seconds at one rank buy seconds at another and would be a number nobody measured. The map is the source of truth about what matters and it already says so.
+- **Fix**: Residual work takes only spare capacity. A zone stating no deadline has nobody waiting in it, so a live run already standing in front of a viewer is never taken for it — taking it there means killing it, and the viewer waits out a cold start for film nobody asked for.
+- **Fix**: An act must pay for itself. Where an arrangement is only reachable by killing a running encoder, a gain smaller than what that killing costs is not a gain. The field numbers are that close: driving from #58 to #59 means making two pieces, 1.89 s at 4.45x on a 4.2 s grid, against a cold start and one piece, 1.88 s — the move was faster by ten milliseconds, and every one of the 39 was individually correct. The margin is the measured cost of the act, never a chosen figure.
+- **Fix**: The plan remembers what it is already carrying out. A staying run was priced as producing instantly however recently it had started; it is now priced at what it still has to go — the measured time to a first piece less the time it has been alive. A run 0.8 s old has 0.14 s left against 0.94 s to move it. One measured figure minus elapsed time, no state to keep.
+- **Fix**: What a move costs is `Infinity` until something has been measured, because a move is irreversible and leaving the encoder alone is always available; placing one where there is none takes the unknown the other way, since the film gets made or it does not. And a run killed before producing anything is a measurement too — a lower bound on the first output — which is the only reading a thrash can supply, since every run in one is killed before it finishes anything.
+- **Fix**: The average bitrate declared in the master came from a field that does not exist on a source file, so every variant was declared at the 400 kbit/s floor in 2.80.14 — nine times worse than the rule of thumb it replaced. It is read from where it is known: the torrent's own report of the file's length, with the probe's reading of the video stream covering the gap before that arrives.
+- **New**: The piece store's own line names its holders, and `AHEAD` no longer reaches memory.
+- **Chore**: `hls-session-manager.js` grew by four lines of wiring in its constructor, which the rule for that file does not allow. Stated rather than shuffled: the thing itself moved to `output/`, and what is left is two accessors handed over where wiring belongs.
+
+## 2.80.14
+
+- **Fix**: What the master playlist declares a variant carries is MEASURED. It was `height * height * 3.2` — for 1080 exactly the 3 732 480 the field declared for a file carrying 18.4 Mbit/s, five times more — and the comment justifying it said no measurement existed before encoding starts. Both do: the average is the file's own length over its duration, exact at session creation, and the peak is the biggest piece produced over the span it covers, equal to the average until one exists. A re-encoded height is declared at the cap we impose; a smaller height at the pixel share of the source's rate. `BANDWIDTH` and `AVERAGE-BANDWIDTH` are both emitted, as the specification names them. This is not cosmetic: the browser sizes its cushion in BYTES from `BANDWIDTH`, so 120 s asked bought 56 MB — 26 s of that film — and the deepest it ever held was 17.1 s. One expression, no case analysis: absent measurements and absent caps are written as the identity of the operation that consumes them (`services/output/rates.js`, eight checks).
+- **Fix**: How much faster than realtime a step must run is computed from the share of the reading's time that was lost, over whole cycles. The model is unchanged and was always right; the two quantities fed into it were not — the WORST single interruption over the MEDIAN gap between interruptions, a maximum over a median, from populations that need not be the same events. Field 2026-09-08: 0.79 s over 0.01 s gave **158.60x** on a file already downloaded whole, and the quality budget refused every step against it forty times in one session. The same measurements as a share of time lost give 1.00x. The field case the old formula was written for is still caught: 3.50x refuses the 1.5 step that ran at 1.05x and stalled.
+- **Fix**: Only what a read is stopped on reaches MEMORY. `AHEAD` used to, and it is exactly the speculative lead the swarm is told about: the priority map states one claimant per zone, so a film with seven zones arrived at the piece store as five holders — one `NEAR` and four `AHEAD` — on a session with two reads. Field: `5 reader(s) want 24 piece(s) of 25 the store may hold`, so every admission had to evict a piece somebody had declared and 100 of 1395 did, beside 6565 spills and 7575 revivals in 44 minutes at a median 0.0 s on disk. Raising the allowance does not touch it — a lead stated over the rest of the film grows to fill whatever it is given.
+- **New**: The piece store NAMES its holders instead of counting them. Five read as five encoders on a session that had two, and choosing between narrowing the windows and raising the allowance was guesswork without the names.
+- **New**: Whether the page is on screen, and whether the picture was pulled out of it into picture-in-picture, travel with every viewer report and live on the viewer beside where it stands. A hidden tab has its timers throttled — 800 ms of event-loop lag measured — so it asks for nothing and looked exactly like a viewer holding a full cushion; delivery stood still for the last six minutes of the field session and nothing said the tab had gone. Two facts and not one, because picture-in-picture is watching WITH the tab hidden. A viewer who is not on screen consumes nothing, which is what a paused one already meant: no deadline, and their place in the priority map kept.
+- **Chore**: `hls-session-manager.js` is 5 lines shorter: the shape of the film the master declares — which heights splice, how big the source is, how it is packaged, what it carries — moved to `LiveOutputs.masterFactsOf`, which is the layer that holds it.
+- **Chore**: Both architecture documents carry the new arithmetic and how to read it.
+
 ## 2.80.13
 
 - **New**: Whether the priority map is being served IN ITS OWN ORDER is measured, for both things that read it. Until now the map's ranks were built, published, and then thrown away by everyone who acted on them — a map read backwards would have looked identical in every line this proxy writes. The measure is one wait recorded against the rank the map gave the thing waited for at the moment it was asked for, on one scale for both layers (`services/priority/WaitLedger.js`, `SegmentDemand.rankOf`, eight checks). The encoding's own state line carries `served[now N wait(s) median Xms worst Yms, soon …, later …]` and each `[hold]` line names the band it belonged to; a band that never waited prints `none` rather than a zero, because silence is not a good result. Read: long waits at `now` mean the urgent zone is not being served first, long waits lower down with none at `now` mean the zones are the wrong width.

package/docs/download-architecture.md

@@ -95,6 +95,48 @@ the map put its piece in, and the `supply` line carries the table. Long waits at
 `blocked` mean the urgent zone is too narrow; long waits further out mean the
 lead is.
 
+## What reaches MEMORY is not what reaches the swarm
+
+`BLOCKED` and `NEAR` only. Memory holds what will be READ soon; the swarm is
+told what will be DOWNLOADED soon, and the map states the second over the whole
+rest of the film.
+
+`AHEAD` used to reach memory too, and it is exactly the speculative lead. The
+map states one claimant per zone, so a film with seven zones arrived at the piece
+store as five separate holders — one `NEAR` and four `AHEAD` — each covering tens
+of megabytes. Field 2026-09-08: `5 reader(s) want 24 piece(s) of 25 the store may
+hold (widest window 17)`, on a session with exactly two reads. The union of what
+was declared equalled the whole capacity, so every admission had to evict a piece
+somebody had declared, and 100 of 1395 evictions did; beside that, 6565 spills
+and 7575 revivals in 44 minutes with a median 0.0 s on disk.
+
+Raising the allowance does not touch it: a lead stated over the rest of the film
+grows to fill whatever memory it is given, and the ratio is unchanged.
+
+The store's own line now NAMES its holders (`[priority-map:22:0 read:…]`) rather
+than counting them, because the count read as five encoders on a session that
+had two, and choosing between "narrow the windows" and "raise the allowance" was
+guesswork without the names.
+
+## How much faster than realtime a step must run
+
+`1 / (1 - the share of the reading's time that was lost to waiting)`, over whole
+cycles: from the first interruption's start to the last one's, which holds
+exactly one running stretch per interruption in it.
+
+The model is unchanged and was always right — if a fraction `f` of the time
+delivers nothing, producing one second of film takes `1/(1 - f)` seconds. What
+was wrong were the two quantities fed into it: the WORST single interruption
+divided by the MEDIAN gap between interruptions, a maximum over a median, from
+populations that need not be the same events. It asks what would happen if the
+worst interruption recurred at the typical rate — a compound case that never
+occurs — and it divides by a gap that goes to zero whenever interruptions arrive
+in a burst.
+
+Field 2026-09-08: 0.79 s over 0.01 s gave **158.60x** on a file already
+downloaded whole, and the quality budget refused every step against it forty
+times in one session. The same measurements as a share of time lost give 1.00x.
+
 ## The five levels
 
 | level | what it is | stated |

package/docs/encode-architecture.md

@@ -166,6 +166,93 @@ chosen for the table.
 The download half is measured the same way and on the same scale, so the two are
 comparable: `download-architecture.md`.
 
+## What the master playlist declares, and why it is not cosmetic
+
+`BANDWIDTH` and `AVERAGE-BANDWIDTH` per variant, both measured
+(`services/output/rates.js`):
+
+- the average is the file's own length over its duration, exact and known when
+  the session is created;
+- the peak is the biggest piece produced over the span it covers, and equals the
+  average until a piece exists — a ratio invented meanwhile would be the
+  fabrication this replaced;
+- a re-encoded height is declared at the cap we impose, which is exact;
+- a smaller height at the pixel share of the source's rate, which errs high, and
+  high is the safe direction.
+
+It used to be `height * height * 3.2`. **The browser sizes its cushion in BYTES
+from `BANDWIDTH`**, so a figure five times low makes the cushion five times
+shallow: field 2026-09-08, 3.73 Mbit/s declared for a file carrying 18.4, 120 s
+asked bought 56 MB — 26 s of that film — and the deepest the browser ever held
+was 17.1 s. Inflating it is not the answer either: hls.js compares it against
+its own estimate of the link to decide a level is unplayable, and its recovery
+then moves level by itself, which does not honour our pinning.
+
+## The objective is the map's own rank order
+
+Not three terms in seconds. One pair per rank the map states, most urgent rank
+first, compared position by position:
+
+```
+[ late(100), done(100), late(99), done(99), … late(1), done(1) ], bodies, wasted
+```
+
+`late(r)` is how long anybody waits past a deadline at rank `r`; `done(r)` is
+when the last number of that rank is made. A difference at a higher rank settles
+it and nothing lower can reopen it — which is the stated order: nobody stares at
+a spinner; then the film in front is encoded as fast as it can be, band by band
+as the map ranks them; then, with what is left over and only then, the film
+behind, in case somebody seeks back.
+
+**No weights, and none possible.** A weight would let seconds at one rank buy
+seconds at another, and it would be a figure nobody measured. The map is the
+source of truth about what matters and it already says so — ten ranks on a film,
+p100 at the number a viewer is stopped on, doubling zones down to p91 for the far
+tail, p1 for what lies behind them.
+
+`bodies` ranks below every rank of the map, so spare capacity cannot buy an
+encoder where the map is indifferent. `wasted` is the swarm's bill for anything
+fetched twice.
+
+## Three rules that stop an encoder being moved for nothing
+
+**A zone with no deadline never takes a live run.** Residual work — the film
+behind the viewers, kept in case somebody seeks back — is done with capacity
+that is left over, and a run already standing in front of a viewer is not left
+over.
+
+**An act must pay for itself.** Where an arrangement is only reachable by killing
+a running encoder, a gain smaller than what the killing costs is not a gain. The
+margin is the measured cost of the act.
+
+**The plan remembers what it is already carrying out.** A staying run is priced
+at what it still has to go — the measured time to a first piece less the time it
+has been alive — not at zero. A run 0.8 s old has 0.14 s left against 0.94 s to
+move it; one working half a minute has nothing left, and a move then happens
+exactly when the film it would reach sooner is worth the restart.
+
+And what a move costs is `Infinity` until something has been measured: a move is
+irreversible and leaving the encoder alone is always available. Placing one where
+there is none takes the unknown the other way, because the film gets made or it
+does not.
+
+### What all three were for
+
+Field 2026-09-08. The map states `withinSeconds: null` for the film behind the
+viewers; `deadlineReaderFor` read it through `Number()`, where `null` is 0, so
+that film was due IMMEDIATELY and was the most urgent material in the file. It
+bought encoders and it took the run standing in front of the viewer, because
+that run was the nearest body to it — 39 moves in one session, 24 of them between
+three adjacent numbers about 0.8 s apart. One viewer on a host affording three
+runs got three. The picture stood still for 116.7 s in three interruptions, the
+worst of them 91.8 s.
+
+The numbers are worth keeping because they are so close: driving from #58 to #59
+means making TWO pieces, 1.89 s at 4.45x on a 4.2 s grid, against a cold start
+and ONE piece, 0.94 + 0.94 = 1.88 s. Every one of those 39 moves was
+individually the cheapest arrangement it was offered. That is the signature of an
+optimiser with no memory, and the three rules above are what give it one.
+
 ## What is checked
 
 `test/one-authority.test.js` holds the shape: one caller of `#startEncodeRun`,

package/package.json

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

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

@@ -1,53 +1,64 @@
-/**
- * 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;
-  const positionSeconds = Number(body.positionSeconds);
-  const recorded = hlsSessionManager.recordNetReport(sessionId, {
-    linkMbps,
-    bufferedAheadSec,
-    consumerId,
-    playing,
-    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 : {};
+  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();
+}

package/services/download/SwarmSelection.js

@@ -206,9 +206,25 @@ export class SwarmSelection {
    * rebuild the second. Now there is one statement and two views of it, both
    * computed here.
    *
-   * Only the urgent levels. Memory holds what will be READ soon; the tail and
-   * the gap behind the playhead are fetched speculatively and must not push a
-   * piece the decoder is about to want out of memory.
+   * WHAT WILL BE READ SOON, WHICH IS NOT WHAT WILL BE DOWNLOADED SOON. Memory
+   * holds the first; the swarm is told the second; and the priority map states
+   * the second, over the whole rest of the film.
+   *
+   * `AHEAD` used to reach memory, and it is exactly the speculative lead: the
+   * map states one claimant per zone, so on a film with seven zones one `NEAR`
+   * and four `AHEAD` arrived here as five separate holders, each covering tens
+   * of megabytes. Field 2026-09-08: the store reported `5 reader(s) want 24
+   * piece(s) of 25 the store may hold (widest window 17)` — the union of what
+   * was declared equalled the whole capacity, so every admission had to evict a
+   * piece somebody had declared, and 100 of 1395 evictions did. Beside that,
+   * 6565 spills and 7575 revivals in 44 minutes with a median 0.0 s on disk, and
+   * 2138 h264 parse errors on a picture that was being COPIED.
+   *
+   * Raising the allowance does not touch it: a lead stated over the rest of the
+   * film grows to fill whatever memory it is given, and the ratio is unchanged.
+   * What belongs in memory is what a READ is stopped on and the little in front
+   * of it — the levels a read itself states — and those are `BLOCKED` and
+   * `NEAR`.
    *
    * @returns {void}
    */
@@ -218,7 +234,7 @@ export class SwarmSelection {
       return;
     }
     const holding = new Set();
-    for (const urgency of [Urgency.BLOCKED, Urgency.NEAR, Urgency.AHEAD]) {
+    for (const urgency of [Urgency.BLOCKED, Urgency.NEAR]) {
       for (const window of this.#register.at(urgency)) {
         const range = this.#piecesFor(window);
         if (!range) {