@torrent-tv/proxy 2.80.11 → 2.80.13

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 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.
+- **New**: What the swarm is ACTUALLY TOLD is said out loud, on change, per level: `the swarm is told, for "film.mkv": NEAR 1 zone(s) 42MB, AHEAD 4 zone(s) 310MB, TAIL 1 zone(s) 1900MB (7 band(s) of the map, over 1218s of film)`. `applyPriorityMap` was silent — that the map had been built was visible in the encoding's line, that the download had received it was visible nowhere, and a whole field session carried not one line about it. Per level rather than per zone, because the register has five levels against the map's however-many bands and the fit between them is the one thing there that can be wrong.
+- **Fix**: A read that ends SHORTER than the `Content-Length` already sent says so, loudly. The header is committed before the first byte and the reader's `close()` ends the iteration with no accounting, so only the `fail()` path was ever logged: a client could receive a truncated body with no way to know it, and ffmpeg's mp4 demuxer — which holds the sample table and asks for samples past what arrived — then parses at wrong offsets. That is exactly the `Invalid NAL unit size (negative)` and `missing picture in access unit` seen 2138 times in one field session on a COPIED picture, where no encoder touches a frame. A single clean read of the same file through the same route produced none, and four concurrent ones produced none; what the field session also had was a piece store whose readers wanted every piece it could hold and 100 of 1395 evictions taking a piece a reader had declared.
+- **Fix**: The reads that feed ffmpeg are failed when the torrent thread dies. Both death handlers walked the ordinary reads and left `#fragmentReaders` untouched — which is what `/stream` uses for an encoder — so an encoder's input neither ended nor errored, it went quiet. Field 2026-08-31, three times: the thread died, both ffmpeg runs stayed alive and stopped producing (167 `holding segment-00085.mp4 … encoder alive` lines), and the viewer was left on a spinner that never ended. Recorded as open since then.
+- **Chore**: `hls-session-manager.js` is 2 lines shorter: the zone walk it did by hand is one call to the map that owns ranks, and the explanation of what an empty map means moved to `SegmentDemand.rankOf`, which is the thing it is about.
+- **Chore**: Both architecture documents gain the measurement and how to read it.
+
+## 2.80.12
+
+- **Chore**: The predicate that decides whether an output is the one somebody is consuming asks each layer only for what it owns. Written first as `LiveOutputs.watchedBy(session, viewer)`, it had the output layer reading a viewer's fields — a coupling in the wrong direction, however plain the values. It is `supersededBy(session, stepOnScreen)` now, taking a plain id: which step is on somebody's screen belongs to the person, which output a step supersedes belongs to the film's shape, and the one place that legitimately holds both puts them together.
+- **New**: `docs/encode-architecture.md` — who decides where encoders go, with the shape drawn: viewers become a map and the map is the whole crossing, the four things the plan decides from, why the map is read at two scopes, and a table of what each of the eight other places used to do against what it now states. `docs/download-architecture.md` gains the priority map as a claimant, which it has been since 2026-09-05 and was never drawn as, and a section saying what each claimant knows — a read states only the piece it is stopped on, which is a fact and not a forecast.
+
 ## 2.80.11
 
 - **Fix**: ONE authority over where encoders go, and it is the plan. Eight other places placed or killed them, each by a rule of its own: the first run of a session, a viewer joining it further in, a quality step or a soundtrack being warmed, a step being switched to, a hardware encoder falling back to software, an input coming back, the cut table correcting itself, and a settled seek. The plan is arithmetic over what is made, what is being made and what is wanted; beside eight other answers it was one opinion among nine. Every one of them now states the FACT it knows — this person is here, this output is nobody's, this encoder's arguments are stale — and the plan places what follows. `this.#startEncodeRun` has exactly one caller.

package/CLAUDE.md

@@ -72,6 +72,12 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     wanted (`demand/`) against what the swarm is told (`download/`), why urgency
     is not a number given to the library, and why the speculative levels are
     withdrawn rather than lowered.
+  - `docs/encode-architecture.md` — who decides where encoders go, and the
+    answer is one authority: `EncodePlan`, from what is made, what is being
+    made, what is wanted and what the host can hold. Why no viewer reaches it,
+    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.

package/docs/download-architecture.md

@@ -37,10 +37,12 @@ flowchart TB
   end
 
   subgraph Claimants["who states needs"]
-    PR[piece-reader<br/>four bands per read]
+    PM[priority map<br/>where the viewers are, per FILE]
+    PR[piece-reader<br/>the piece it is stopped on]
     BF[torrent-pool<br/>background fill, per file]
   end
 
+  PM -->|state / withdraw| R
   PR -->|state / withdraw| R
   BF -->|state / withdraw| R
   W --> R
@@ -51,6 +53,48 @@ flowchart TB
   S -->|the only caller| WT[(WebTorrent)]
 ```
 
+## Who the claimants are, and what each of them knows
+
+**The priority map** states what should be downloaded AHEAD of the viewers, once
+per file, built in `services/priority/` from where they are and from nothing
+else. It is the same map the encoding reads — the encoding reads it per OUTPUT
+and in segment numbers, this layer reads it per FILE and in bytes, and both
+scopes are right for what asks them (`encode-architecture.md`).
+
+**A read** states only the piece it is STOPPED ON. That is not a forecast but the
+fact that somebody is waiting there, and it is what keeps working for the reads
+the viewers' map does not cover: a container header at open, the subtitle walk, a
+soundtrack being fetched whole. Until 2026-09-02 each read built four bands
+around its own head instead, so fifteen reads were fifteen forecasts on a store
+holding sixteen pieces, half of all evictions took a piece a reader had said it
+wanted, and two thirds of reads came back from disk.
+
+**The background fill** states one file at a time — a soundtrack pulled whole
+once the cushion is full, and no further.
+
+## Whether the map reaches the swarm, and in what shape
+
+Applied in silence until 2026-09-08: that the map had been BUILT was visible in
+the encoding's own line, that the download had received it was visible nowhere,
+and a whole field session carried not one line about it. Said now on change, per
+LEVEL rather than per zone — the register has five levels and the map has as many
+bands as the film needs, and the fit between the two is the one thing here that
+could be wrong:
+
+```
+torrent-pool: the swarm is told, for "film.mkv": NEAR 1 zone(s) 42MB,
+AHEAD 4 zone(s) 310MB, TAIL 1 zone(s) 1900MB (7 band(s) of the map, over 1218s of film)
+```
+
+In megabytes, because that is what a swarm delivers. `NEAR` absent while
+somebody is watching means the map is not arriving; every band landing in one
+level means the fit has collapsed.
+
+Beside it, where the waits fell: the reader records each wait against the level
+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.
+
 ## The five levels
 
 | level | what it is | stated |

package/docs/encode-architecture.md

@@ -0,0 +1,180 @@
+# Encode architecture — who decides where encoders go
+
+One question, one answer, and the answer is arithmetic.
+
+> Viewers are always independent and always reuse what can be reused. The
+> number of encoders is however many are needed; how many are needed follows
+> from which sets of output parameters are wanted and where the viewers stand
+> inside each. Segments produced by ANY encoder are available to ANY viewer, and
+> which viewer asked never enters the question.
+
+## The one authority
+
+`services/encode/EncodePlan.js` decides. Nothing else places an encoder,
+nothing else takes one away for scheduling reasons, and there is exactly one
+call to `#startEncodeRun` in the whole proxy — the one the plan asks through.
+
+It decides from four things and no others:
+
+| what | where it comes from |
+|---|---|
+| what is already made | the segment store, asked afresh before every decision |
+| what is being made | the coverage map's live claims |
+| what is wanted | the priority map of that output |
+| how many the machine can hold | `run-budget.js`, from measurements of this host |
+
+**No viewer reaches it.** `services/encode/` and
+`services/orchestrators/EncodeOrchestrator.js` do not import the viewer layer,
+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.
+
+## 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]
+    VS[Viewers<br/>the relation, indexed from both ends]
+  end
+
+  subgraph P["services/priority — one fact, two scopes"]
+    PM[PriorityMap<br/>seconds of film to a rank]
+    PO[PriorityOrchestrator<br/>merge, publish, keep]
+  end
+
+  subgraph E["services/encode — where encoders go"]
+    CM[CoverageMap<br/>ready / making / free]
+    EP[EncodePlan<br/>argmin over arrangements]
+    RB[run-budget<br/>what this host can hold]
+    ER[EncodeRun<br/>one process, one interval]
+  end
+
+  subgraph D["services/demand + download — what the swarm is told"]
+    DR[DemandRegister]
+    SS[SwarmSelection]
+  end
+
+  VW --> VS
+  VS -->|"positions, presence"| PO
+  PM --> PO
+  PO -->|"per FILE, in bytes"| DR
+  DR --> SS
+  PO -->|"per OUTPUT, in segments"| EO[EncodeOrchestrator]
+  EO --> EP
+  CM --> EP
+  RB --> EP
+  EP -->|"start / stop / move"| ER
+  ST[(SegmentStore<br/>the disk)] -->|"what is ready"| CM
+```
+
+## Two scopes of one map, and both are right
+
+The map is built from where the viewers are, once, and read at two scopes.
+
+**Per FILE, for the swarm.** The picture, a quality step and a soundtrack of one
+film read the same bytes, so every viewer of any of them wants that file's
+bytes. This is what `PriorityOrchestrator.mapFor(sourceKey, fileIndex)`
+answers, and what is published to the download layer.
+
+**Per OUTPUT, for the encoders.** A person watching 480p wants nothing of the
+1080p output at all. This is `mapForOutput(address)`.
+
+One map for both was the second authority over encoders. Handed the film's map,
+the plan wanted an encoder on every output of the film; what actually stopped
+the ones nobody was watching was the session manager killing them by its own
+judgement — and since a viewer moving between steps announces itself, the plan
+started them again on the very next pass. Two parties answering "should this
+encoder exist" by different rules, several times a second.
+
+An output nobody is on gets a map with **nothing in it**, which is a statement
+and not an absence: the walk writes one for every output a session exists for,
+including the ones everybody has left. That is how the plan is told to stop what
+is on it.
+
+## Which output a person is consuming
+
+A person holds a record on more outputs than they are consuming. The picture is
+where their record lives — the browser addresses it, their chosen soundtrack is
+written on it, their position is read from it — so they are never let go of it;
+but the moment they step down to 480p, the 1080p output is producing for nobody.
+
+That distinction is answered where the two facts meet, and neither layer is
+handed the other:
+
+- **which step is on their screen** is a fact about a PERSON, read off the
+  viewer as one field;
+- **which output a step supersedes** is a fact about the FILM'S SHAPE, answered
+  by `LiveOutputs.supersededBy(session, stepOnScreen)`, which takes a plain id
+  and has never seen a viewer.
+
+A step, a soundtrack, and a step being warmed are consumed by whoever is
+registered on them — everywhere but the picture, a person who stops watching is
+let go of, so being known to an output is consuming it. Through a warm-up both
+the step on screen and the step being made ready are genuinely produced, which
+is the price of the switch not being visible.
+
+## What each of the eight other places used to do
+
+Before 2026-09-08 the plan was one opinion among nine. Each of these placed or
+killed encoders by a rule of its own; each now states the fact it knows.
+
+| it knows | it used to do | it now says |
+|---|---|---|
+| a session was created | start a run at the viewer's position, worked out again | the viewer is placed; the plan reads that |
+| a viewer joined further in | start a run there if nothing was being made | as above |
+| a step or soundtrack is being warmed | point that session at the switch and start it | this person is at N seconds on it |
+| a step was switched to | stop the one left, point the new one | this person is on this step now |
+| a step or track was abandoned | stop its encoder | this person has left that output |
+| the hardware encoder failed | start a run at the dead one's start | what this host encodes with has changed |
+| the input came back | start a run at the last requested segment | decide again |
+| the cut table was corrected | restart the members at the measured instant | this run is producing in the wrong place; the instant is in the file's table |
+| the bitrate cap changed | restart at where the encoder had got to | this run's arguments are stale |
+
+A **seek** is not in that list because it was already reduced to one thing: it
+puts the viewer where they are. The settle timer behind it, its cooldown and its
+one-segment backoff are gone — a second debounce on a signal the browser had
+already debounced, and every millisecond of it was dead time in front of the
+viewer.
+
+## Whether the map is being served in its own order
+
+The zones say what matters most. What the viewer actually waited for is measured
+where a viewer measurably waits — the one place in the proxy that holds a
+request for a named segment — and recorded against the rank the map gave that
+segment **at the moment it was asked for**. It reaches the `encode:` state line
+as `served[...]`:
+
+```
+served[now 42 wait(s) median 180ms worst 1900ms, soon 6 wait(s) median 90ms worst 240ms, later none]
+```
+
+Read it like this:
+
+| what it says | what is wrong |
+|---|---|
+| long waits at `now` | the urgent zone is not being served first — a fault in whoever acts on the map |
+| long waits at `soon`/`later`, none at `now` | the zones are the wrong width: the urgent one too narrow, so the viewer reaches material only ranked "soon" |
+| `now none` while the viewer is watching | nothing was ever urgent — the map is not reaching this output |
+| a band reading `none` | silence, not a zero, and it is printed as `none` so it cannot be read as "no waits, all good" |
+
+Ranks are collapsed into three bands because the map's own scale is as long as
+the film needs — a hundred ranks on a long file — and a hundred-row table says
+nothing a reader can hold. The width of `soon` is a tenth of the top rank, which
+is the map's own shape (its zones widen geometrically) rather than a threshold
+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 is checked
+
+`test/one-authority.test.js` holds the shape: one caller of `#startEncodeRun`,
+no encoder stopped for being unwatched, the settle machinery absent, each output
+reading its own map, and the soundtrack's start instant read off the table
+rather than handed in.
+
+`test/priority-map-per-output.test.js` holds the two scopes, over the real
+viewer registry, the real `LiveOutputs` and the real `PriorityOrchestrator`.
+
+`test/encode-plan.test.js` holds the arithmetic, including that every encoder
+stops when nobody is watching the output.

package/package.json

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