@torrent-tv/proxy 2.81.2 → 2.83.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 2.83.0
+
+- **Fix**: THE SPILLED PIECES HAD ONE RULE AND IT NEVER BOUND. The ceiling 2.81.0 gave them is a share of free space, which on the addon host is 52 292 MB against a measured growth of 14 400 MB in one viewing — so nothing was ever removed until the torrent itself went. They have the pair the segments have now: a piece behind every read head has been read and will not be read again unless somebody seeks back, and a seek back re-downloads it, which is the bargain this tier already makes whenever it drops a piece for room. Under pressure the order is the same as the segments’ — behind the earliest reader first, furthest behind first of all — instead of by which piece happened to be touched longest ago, which says nothing about what anybody is about to read.
+- **Fix**: THREE PERIODS FOR ONE UNKNOWN, AND THEY CONTRADICTED EACH OTHER. A torrent and its downloaded bytes went at fifteen minutes, a session lived to thirty, the produced segments to six hours — so between the first two there was a session with no source: a viewer returning at the twentieth minute got a session that could not make a single new segment until the torrent was added again. All three stand for the same unmeasured thing, whether the viewer comes back, so they are ONE number in one place (`services/disk/keep.js`, one hour) and the session now dies first, which is the right order and needs no rule of its own.
+- **New**: The thing those periods stand for is being measured, and the proxy is the only place it can be. A session opened on an output whose segments are still on disk IS a return, and its age is exactly what the store recorded. `returns: 14 session(s) opened on material still held, 3 on material gone; median 12min after the last read, longest 51min — kept for 60min` — said beside the disk figures. The median and the longest are the two the period has to sit between, and a week of ordinary use replaces the hour with what viewers actually do.
+- **Fix**: The benchmark of a device-backed encoder could not have run. VAAPI and QSV take their device in the arguments before the input, and what is there for a session sets up hardware DECODING — which a benchmark fed raw frames must not have. `Encoder.benchmarkInputArgs` states the device and nothing else; without it `h264_vaapi` and `h264_qsv` fail to open and the reading would have said "this host cannot encode" about a host that encodes perfectly well. Found by reviewing 2.82.0 rather than by running it.
+- **Chore**: `docs/disk-architecture.md` — the three things that write to one disk, the two rules that remove material, the order the viewers give it, and what is still not solved. 1009 checks pass, biome clean; the new eviction order was checked by breaking it on purpose.
+- **Chore**: NOT yet seen in the field. What the next session must show: a `returns:` line once material has been reopened, `disk:` with both claimants, and the spill falling behind a viewer rather than only growing.
+
+## 2.82.0
+
+- **Fix**: THE ENCODER PING-PONGED BECAUSE NOTHING MEASURED WHAT A START COSTS. The plan compares when the wanted pieces appear under each arrangement, and for that it needs how long a fresh encoder takes to produce anything and how long killing one takes. Both were learned only from runs that had ENDED, so at a cold open both were zero — and zero does not read as “not measured”, it reads as “free”. Keeping a warming encoder then cost one piece and moving it cost `0 + 0 + one piece`: the same figure to the millisecond, so the tie fell to position and any advantage however small won. Field 2026-09-08: start at #68, a second later kill and start at #69, half a second later kill and start at #68 again, each dying having produced nothing. Over two days 153 runs were stopped that way and 68 of them made no segment at all.
+  **Both are measured at startup now, from one ffmpeg run**: spawn to the first piece the encoder itself announces closed, then SIGTERM to exit. 0.68 s and 0.02 s on the developer’s desktop. Readings from real runs replace them as they arrive. Worth stating because it is what the arithmetic already assumed: subtract keeping from moving and what is left is the killing plus the time the run has already lived — the warm-up a move throws away. That term exists in the formula and vanishes with the measurement, which is why the plan behaved as though a move were free.
+- **Fix**: The decode cost and the contention penalty were asked only where the chosen encoder was SOFTWARE, and neither is about the encoder. A host with a GPU decodes in software just the same — no hardware decoder is asked for anywhere — and what a second job costs is a property of the machine. So a GPU host had no decode model, no contention penalty and no encoder throughput at all, and the quality offer, which is arithmetic over those three, had nothing to compute from.
+- **New**: The throughput benchmark walks the CHOSEN encoder’s own speed ladder — libx264’s presets, NVENC’s `p1`…`p7`, QSV’s `veryfast`…`veryslow`, VAAPI’s quality levels. Each kind says how to measure itself (`Encoder.benchmarkArgs`), which is what the ladders declared and nothing ever ran. A kind with no ladder is measured once, which is still a reading where there was none.
+- **Chore**: 1000 checks pass, biome clean. NOT yet seen in the field. What the next session must show: `a start costs …s to a first piece and a stop …s on this host` once at startup, `firstByte=` and `kill=` non-zero in the very first `encode-plan` line, and no run stopped with “scores worse than standing at” an adjacent number.
+
 ## 2.81.2
 
 - **Fix**: `disk: 0MB free` on a host with 103 GB. The free space was read from the segments’ own directory, which is made when the first session starts and removed when the proxy stops — so at every start, and after every clean exit, the reading failed and answered zero, which means “no room” to everything downstream. It reads the nearest ancestor that exists; the disk is the same disk either way.

package/CLAUDE.md

@@ -72,6 +72,17 @@ 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.
+  - `disk/` — one owner of the disk, read by everything that takes any of it.
+    `DiskSpace` reads the free space once and divides it between claimants by
+    the rule memory already uses; `wire.js` says who the claimants are (the
+    produced segments, and the pieces the memory store spills, which live on the
+    torrent thread and are told their share over its channel); `free.js` reads
+    the nearest directory that exists, because the segments' own is made at the
+    first session and removed at a clean stop.
+  - `docs/disk-architecture.md` — the three things that write to one disk, the
+    two rules that remove material (nobody needs it, or there is no room), the
+    order the viewers give that removal, why a spilled piece is a file of its
+    own, and what is still not solved.
   - `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,

package/docs/disk-architecture.md

@@ -0,0 +1,161 @@
+# Disk architecture — one owner, and what goes first when it is short
+
+Three things on this proxy write to the same disk. Until 2026-09-10 each read
+the free space as though it were the only claimant, so there were three
+ceilings, each standing for the whole disk.
+
+| what | where | what bounded it before |
+|---|---|---|
+| segments an encoder produced | `services/encode/SegmentStore.js` | a quarter of what was free, plus a 2 GB floor — both numbers chosen by hand |
+| pieces the memory store spilled | `services/piece-store/piece-disk-store.js` | **nothing at all** |
+| diagnostics kept on purpose | `/data` — core dumps, heap snapshots, packet captures | a count of files, never a size |
+
+The middle row is what it cost: one fifty-minute viewing wrote **14 400 MB** to
+the spill file (field 2026-08-31) while the store held 312-424 MB, and free
+space on the host fell by every megabyte of it. The bottom row is 2.9 GB of one
+core dump on the addon host, inside a budget of "two dumps".
+
+## One owner
+
+`services/disk/DiskSpace.js` reads the free space once and divides it. The rule
+is the one memory already uses, on the other reading:
+
+```
+allowance = free now + what we already hold - what everything that is not us has been seen to need
+```
+
+Nothing in it is a fraction chosen by hand. The reserve is measured: between two
+readings, how much free space went away beyond what our own consumers took.
+
+`services/disk/wire.js` says who the claimants are. The segments are told their
+share by a call; the spilled pieces live on the torrent thread, so the share
+travels the channel that already carries everything else and the reply says what
+they hold — one exchange, both directions.
+
+The reading is said every pass, in the series beside the memory one:
+
+```
+disk: 104584MB free; segments 0MB of 52292MB, spilled pieces 0MB of 52292MB
+```
+
+## Two rules, answering two questions
+
+They are kept apart because they were briefly proposed as one, and that was
+wrong.
+
+**Time.** Material nobody needs should not sit on the owner's disk merely
+because there is room for it. An output nobody has read for long enough goes
+whole, whatever the free space is.
+
+**Space.** Material everyone needs must still go when there is no room.
+
+A ceiling alone would keep 5 GB on a household disk for six hours because the
+disk is large. An idle rule alone would keep everything until its clock ran out,
+however tight the disk had become.
+
+## What goes first, and it is the viewers who decide
+
+For the segments, the order is the priority map's own read from the other end:
+
+1. outputs nobody is watching at all;
+2. what lies behind the earliest viewer — furthest behind first;
+3. what lies ahead of the furthest viewer — furthest ahead first.
+
+A segment a viewer is standing on is never a victim. It used to be whole outputs
+by when their directory was last read, which says nothing about what anybody is
+about to watch.
+
+## A piece is a file
+
+`DiskTier` wrote every spilled piece into ONE sparse file at
+`index * chunkLength` and answered `forget(index)` by dropping the number from a
+set. The bytes stayed: a sparse file's blocks come back only by hole punching,
+which Node exposes no binding for, so nothing this process could do returned a
+single block before the whole file was removed.
+
+`PieceDiskStore` gives each piece its own file. Removing one returns exactly its
+blocks, needs no binding this runtime lacks, and makes the unit of eviction the
+same as the unit of storage — so the order pieces leave in is the order we
+choose. Over its allowance the least recently used goes, and a piece being read
+is never the victim. A piece thrown away is answered as absent, so the torrent
+fetches it again, which is the same bargain the memory tier makes when it
+spills.
+
+The read this replaced was chosen for its cost — 22.08 ms via `readFile` against
+**7.63 ms** into a buffer we already hold, measured on the field host — and that
+is unchanged: it is still one `read` into the caller's buffer. What it adds is
+an `open` per read, tens of microseconds against those milliseconds.
+
+## A clean exit leaves nothing of ours
+
+The segments' root was removed only when it happened to be empty — from the
+first commit of this repository, never a decision. What it protected against is
+a second proxy sharing the root; what it did was leave every directory alone,
+including this process's own orphans. A directory adopted at startup, owned by
+no session, therefore survived the exit and was adopted again at the next start.
+
+That loop is what made an orphan permanent, and it is why 5.0 GB of segments
+from sessions that had ended hours before were on the addon host on 2026-09-10.
+`SegmentStore.dropAll` now removes everything this process owns, root included,
+which also gives the startup sweep its meaning back: whatever is found then is
+from a kill.
+
+Both kinds have both rules. For the spilled pieces the time rule is the same
+statement one layer down: a piece behind every read head has been read and will
+not be read again unless somebody seeks back, and a seek back re-downloads it —
+the bargain this tier already makes whenever it drops a piece for room.
+`PieceLru.readHeads` says where the readers stand, `PieceDiskStore.forgetBehind`
+acts on it, and the eviction order under pressure is the same: behind the
+earliest reader first, furthest behind first of all. With no reader at all
+nothing is removed — a store between reads is not a store nobody wants, and the
+torrent going idle is what empties it whole.
+
+## How long material nobody is using is kept
+
+One number, in one place — `services/disk/keep.js`, one hour — because
+everything it governs stands for the same unmeasured thing: whether the viewer
+comes back.
+
+It was three, and they contradicted each other:
+
+| what | was | now |
+|---|---|---|
+| a torrent and its downloaded bytes | 15 minutes | one hour |
+| a session | 30 minutes | unchanged — a session is a record, not material |
+| the segments an encoder produced | 6 hours | one hour |
+
+The torrent went at fifteen minutes while the session it feeds lived to thirty,
+so between them there was a session with no source: a viewer returning at the
+twentieth minute got a session that could not make a single new segment. With
+one hour for both kinds of material the session dies first, which is the right
+order and needs no rule of its own to enforce.
+
+Nothing derives the hour. Everything else in the decision is measured — a piece
+comes back from the swarm in ~1430 ms, a segment in its own encode time, and the
+disk has an owner that prices holding it — and only the return is unknown.
+
+**And the return is measurable here.** A session opened on an output whose
+segments are still on disk IS a return, and its age is exactly what the store
+recorded. `services/disk/returns.js` keeps them and says so beside the disk
+figures:
+
+```
+returns: 14 session(s) opened on material still held, 3 on material gone;
+         median 12min after the last read, longest 51min — kept for 60min
+```
+
+The median and the longest are the two the period has to sit between: shorter
+than the median throws away material half the returns wanted, longer than the
+longest keeps material no return has ever reached. A week of ordinary use and
+the hour is replaced by what viewers actually do — and then the two kinds can
+have different numbers, since their costs of coming back differ.
+
+## What is NOT solved
+
+**The measurement that would replace the hour has not been taken yet.** The
+counter is in place and says nothing until a week of ordinary use has produced a
+distribution.
+
+**The diagnostics are not a claimant yet.** They are bounded by a count of files
+and never by a size, and they cannot simply be thrown away when space is short: a
+dump is the only evidence of the death it records. That needs a rule of its own.

package/docs/encode-architecture.md

@@ -252,13 +252,42 @@ a fresh encoder = spawn overhead + the piece at the rate in force
 a moved one     = the kill, and then the same
 ```
 
-With nothing measured the overhead is zero and a fresh encoder owes exactly one
-piece. **That is the floor, and it is derived rather than chosen:** a piece
-cannot appear before it is encoded, and how fast this host encodes is measured
-before any viewer exists. There was an `Infinity` here for the cost of a move,
-on the reasoning that an unmeasured price must not license an irreversible act —
-an exception in a model that needs none, and this is the same statement made by
-arithmetic.
+**Both figures are measured before any viewer exists**, and until 2026-09-10
+neither was. They were learned only from runs that had ENDED, so at a cold open
+both read zero — and zero does not mean "unknown" here, it means "free".
+
+That is not a small bias, it is the whole comparison. Subtract keeping from
+moving and what is left is exactly the killing plus the time the run has already
+lived:
+
+```
+keep a warming run  = firstByteWait - elapsed
+move it             = kill + spawn overhead + one piece
+                    = kill + firstByteWait                (spawn overhead = firstByteWait - one piece)
+move - keep         = kill + elapsed
+```
+
+`elapsed` is the warm-up a move throws away — a process started, an input
+opened, the first bytes fetched, a decoder filled — and it is the term that
+makes moving cost something. Set `firstByteWait` to zero and it cancels out of
+both sides along with the kill: keeping and moving then cost the same figure to
+the millisecond, the tie falls to position, and any advantage however small wins.
+
+Field 2026-09-08, the first fifteen seconds of a session: start at #68, a second
+later kill and start at #69, half a second later kill and start at #68 again,
+each dying having produced nothing. Over two days 153 runs were stopped by the
+plan and 68 of them made no segment at all, median life 9.6 s.
+
+`services/encode/start-stop-cost.js` measures both from **one ffmpeg run at
+startup**: spawn to the first piece the encoder itself announces closed, then
+SIGTERM to exit. 0.68 s and 0.02 s on the developer's desktop. `RunCosts` starts
+from those and replaces them with readings from real runs as they arrive.
+
+There was an `Infinity` here once for the cost of a move, on the reasoning that
+an unmeasured price must not license an irreversible act. It was removed as an
+exception in a model that needs none — correctly, but what replaced it was a
+floor of zero, which licenses the act rather than forbidding it. A measurement
+is what a model like this needs, not an exception and not a floor.
 
 And a run killed before producing anything is a measurement too — a lower bound
 on the first output, and the only reading a thrash can supply, since every run in

package/package.json

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

package/server.js

@@ -40,6 +40,7 @@ import { WorkerTorrentPool } from "./services/torrent-worker/pool-adapter.js";
 import { HlsSessionManager } from "./services/hls-session-manager.js";
 import { createPlaybackPlanner } from "./services/playback-planner.js";
 import { detectVideoEncoder, benchmarkSoftwarePresets, benchmarkDecodeCost, benchmarkContention, benchmarkCopySpeed, detectTonemapSupport } from "./services/hwaccel.js";
+import { measureStartAndStop } from "./services/encode/start-stop-cost.js";
 import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -126,23 +127,31 @@ export async function startProxyServer({
   const videoEncoder = transcodeAudio
     ? await detectVideoEncoder({ ffmpegBin, logger })
     : null;
-  // For software libx264, benchmark preset throughput once at startup so the
-  // session manager can pick the highest-quality preset that still encodes each
-  // stream faster than realtime. Hardware encoders use their own fixed preset.
-  // The decode model first, and the preset benchmark second — they are
-  // independent now (the presets are timed on raw frames), but the order costs
-  // nothing and keeps the two figures side by side in the log.
-  const decodeCostModel = videoEncoder?.kind === "software"
+  // WHAT THIS HOST DOES, measured before any viewer exists. Every one of these
+  // was gated on the chosen encoder being SOFTWARE, and two of the three are
+  // not about the encoder at all: a host with a GPU decodes in software just
+  // the same — no hardware decoder is asked for anywhere — and what a second
+  // job costs is a property of the machine. So a GPU host had no decode cost,
+  // no contention penalty and no encoder throughput, and the quality offer,
+  // which is arithmetic over those three, had nothing to compute from.
+  //
+  // The decode model first and the throughput second — they are independent
+  // (the rungs are timed on raw frames), but the order keeps the two figures
+  // side by side in the log.
+  const decodeCostModel = transcodeAudio
     ? await benchmarkDecodeCost({ ffmpegBin, logger })
     : null;
   // What a second job costs on this host. Measured because the budget adds
   // independent prices and this host says two jobs that each fit alone do not
   // fit together — 2.6× on the addon box (2026-08-18).
-  const contentionPenalties = videoEncoder?.kind === "software"
+  const contentionPenalties = transcodeAudio
     ? await benchmarkContention({ ffmpegBin, logger })
     : null;
-  const softwarePresetBenchmark = videoEncoder?.kind === "software"
-    ? await benchmarkSoftwarePresets({ ffmpegBin, logger })
+  // The chosen encoder walked over its OWN speed ladder: libx264's presets,
+  // NVENC's p1…p7, QSV's veryfast…veryslow, VAAPI's quality levels. A kind with
+  // no ladder is measured once, which is still a reading where there was none.
+  const softwarePresetBenchmark = videoEncoder
+    ? await benchmarkSoftwarePresets({ ffmpegBin, logger, encoder: videoEncoder })
     : null;
   // What this host does with a picture it does NOT re-encode. Every other
   // startup measurement prices encoding or decoding, and a copied picture does
@@ -155,6 +164,15 @@ export async function startProxyServer({
   const copySpeedX = transcodeAudio
     ? await benchmarkCopySpeed({ ffmpegBin, logger })
     : null;
+  // WHAT A START AND A STOP COST HERE, before any viewer exists. Both decide one
+  // thing — leave an encoder where it stands, or kill it and start another —
+  // and both used to be learned only from runs that had ENDED, so at a cold
+  // open they were zero. Zero does not read as "not measured": it reads as
+  // "free", and a free move is always taken. Field 2026-09-08: an encoder moved
+  // between two adjacent numbers every half second and produced nothing.
+  const startStopCost = transcodeAudio
+    ? await measureStartAndStop({ ffmpegBin, encoder: videoEncoder, logger })
+    : null;
   // Whether this ffmpeg build can tone-map HDR→SDR (zscale + tonemap filters).
   // Detected once; the session manager applies the tonemap chain only for HDR
   // sources on the software path when available.
@@ -171,6 +189,7 @@ export async function startProxyServer({
     decodeCostModel,
     contentionPenalties,
     copySpeedX,
+    startStopCost,
     tonemapSupported,
     segmentFormatId: segmentFormat,
     stateDir,
@@ -178,15 +197,15 @@ export async function startProxyServer({
     // CPU-bound transcode from a download-starved input before downscaling.
     // What every torrent here has moved, so the proxy can price its own
     // downloading, hashing and delivery against the machine (roadmap item 7).
-    // What the spilled pieces weigh on the torrent thread, and how to tell them
-    // their share of the disk. The owner of the disk is on this side, where the
-    // segments are; the pieces are on the other.
-    spillDisk: typeof torrentPool.allowSpillBytes === "function"
-      ? {
-          held: () => torrentPool.spilledBytes ?? 0,
-          allow: (bytes) => torrentPool.allowSpillBytes(bytes)
-        }
-      : null,
+    // What the spilled pieces weigh on the torrent thread, and how to tell them
+    // their share of the disk. The owner of the disk is on this side, where the
+    // segments are; the pieces are on the other.
+    spillDisk: typeof torrentPool.allowSpillBytes === "function"
+      ? {
+          held: () => torrentPool.spilledBytes ?? 0,
+          allow: (bytes) => torrentPool.allowSpillBytes(bytes)
+        }
+      : null,
     getTorrentTotals: async () => {
       if (typeof torrentPool.getTorrentTotals !== "function") {
         return null;

package/services/disk/keep.js

@@ -0,0 +1,48 @@
+/**
+ * @file How long material nobody is using is kept.
+ *
+ * ONE NUMBER, IN ONE PLACE, because everything it governs stands for the same
+ * unmeasured thing: whether the viewer comes back. Everything else in the
+ * decision is measured or measurable — re-downloading a piece from the swarm is
+ * ~1430 ms on the field host, re-making a segment is its own encode time, and
+ * the disk now has an owner that prices holding it. Only the return is unknown,
+ * and a period is what stands in for it.
+ *
+ * IT WAS THREE NUMBERS AND THEY CONTRADICTED EACH OTHER (read 2026-09-10):
+ *
+ *   torrent and its downloaded bytes   15 minutes
+ *   session                            30 minutes
+ *   produced segments                   6 hours
+ *
+ * The torrent therefore went at fifteen minutes while the session it feeds
+ * lived to thirty, so between them there was a session with no source: a viewer
+ * returning at the twentieth minute got a session that could not make a single
+ * new segment until the torrent was added again. That is not two answers to one
+ * question, it is a contradiction — and it is what two independent guesses about
+ * one unknown produce.
+ *
+ * With one hour for both kinds of material the session dies first, which is the
+ * right order and needs no rule of its own to enforce.
+ *
+ * WHY AN HOUR, honestly: nothing derives it. It is a stand-in, chosen to be
+ * long enough that an interruption — a phone call, a meal — does not cost the
+ * film, and short enough that a household disk is not held for a day by
+ * somebody who is not coming back. It is the OWNER'S disk, and holding
+ * gigabytes on it because there happens to be room is taking something that is
+ * not ours.
+ *
+ * WHAT REPLACES IT, and the proxy is already in a position to measure it: every
+ * session opened on an output whose segments are still on disk IS a return, and
+ * its age is known. `services/disk/returns.js` records them. A week of those and
+ * the distribution answers this directly — keep material for as long as returns
+ * actually happen — and then the two kinds can have different numbers, since
+ * their costs of coming back differ.
+ */
+
+/**
+ * How long material nobody has read is kept, in milliseconds.
+ *
+ * Read by the torrent pool for a torrent and its downloaded bytes, and by the
+ * session manager for the segments an encoder produced.
+ */
+export const IDLE_KEEP_MS = 60 * 60 * 1000;

package/services/disk/returns.js

@@ -0,0 +1,103 @@
+/**
+ * @file How long after material stops being read somebody asks for it again.
+ *
+ * The one term of "how long do we keep this" that nothing measures. Everything
+ * else in that decision is a measured quantity — re-downloading a piece from
+ * the swarm is ~1430 ms on the field host, re-making a segment is its own
+ * encode time, and the disk has an owner that prices holding it. Only the
+ * return is unknown, and `IDLE_KEEP_MS` is a guess standing in for it.
+ *
+ * IT IS MEASURABLE HERE AND NOWHERE ELSE. A session opened on an output whose
+ * segments are still on disk IS a return, and its age is known exactly: the
+ * store records when each output was last read. Nothing needs to be inferred.
+ *
+ * This changes no behaviour. It records, and says what it has seen once in a
+ * while, so that after a week of ordinary use the period can be derived from
+ * what viewers actually do instead of from what a period felt like.
+ */
+
+/** How many returns are kept. Enough to see a shape, few enough to say in a line. */
+const KEPT = 200;
+
+export class Returns {
+  /** Ages in milliseconds, newest last. @type {number[]} */
+  #ages = [];
+
+  /** Sessions opened on material this proxy no longer had. */
+  #cold = 0;
+
+  /** Sessions opened on material that was still there. */
+  #warm = 0;
+
+  /**
+   * Note a session being opened on an output.
+   *
+   * @param {object} params
+   * @param {number | null} params.lastReadAt - When that output was last read,
+   *   or null where this proxy has never held it.
+   * @param {number} params.now
+   * @returns {void}
+   */
+  note({ lastReadAt, now }) {
+    if (!Number.isFinite(lastReadAt) || lastReadAt === null || lastReadAt <= 0) {
+      this.#cold += 1;
+      return;
+    }
+    this.#warm += 1;
+    this.#ages.push(Math.max(0, now - /** @type {number} */ (lastReadAt)));
+    while (this.#ages.length > KEPT) {
+      this.#ages.shift();
+    }
+  }
+
+  /**
+   * What the returns look like, or null while there have been none.
+   *
+   * The MEDIAN and the LONGEST, because those are the two the period has to sit
+   * between: shorter than the median throws away material half the returns
+   * wanted, and longer than the longest keeps material no return has ever
+   * reached.
+   *
+   * @returns {{ warm: number, cold: number, medianMs: number, longestMs: number } | null}
+   */
+  shape() {
+    if (this.#ages.length === 0) {
+      return null;
+    }
+    const sorted = [...this.#ages].sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return {
+      warm: this.#warm,
+      cold: this.#cold,
+      medianMs: sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle],
+      longestMs: sorted[sorted.length - 1]
+    };
+  }
+
+  /**
+   * One line, for the log, or null while there is nothing to say.
+   *
+   * @param {number} keepMs - What is being kept for now, so the reading and the
+   *   guess it will replace stand side by side.
+   * @returns {string | null}
+   */
+  describe(keepMs) {
+    const shape = this.shape();
+    if (shape === null) {
+      return null;
+    }
+    return (
+      `returns: ${shape.warm} session(s) opened on material still held, ` +
+      `${shape.cold} on material gone; median ${minutes(shape.medianMs)} after the last read, ` +
+      `longest ${minutes(shape.longestMs)} — kept for ${minutes(keepMs)}`
+    );
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function minutes(ms) {
+  return `${Math.round(ms / 60000)}min`;
+}

package/services/encode/Encoder.js

@@ -81,4 +81,46 @@ export class Encoder {
   buildVideoArgs(_options) {
     throw new Error(`${this.name} does not say how to build its video arguments.`);
   }
+
+  /**
+   * What this kind needs BEFORE the input when it is being benchmarked.
+   *
+   * Not `inputArgs`: those set up hardware DECODING, and a benchmark is fed raw
+   * frames — there is nothing to decode. What a device-backed encoder still
+   * needs is the device itself, and without it `h264_vaapi` and `h264_qsv` fail
+   * to open at all, so the benchmark would answer "this host cannot encode"
+   * about a host that encodes perfectly well.
+   *
+   * @returns {string[]}
+   */
+  benchmarkInputArgs() {
+    return [];
+  }
+
+  /**
+   * How to encode raw frames at one rung of this kind's speed ladder, for the
+   * startup benchmark and nothing else.
+   *
+   * SEPARATE FROM `buildVideoArgs` on purpose. That one produces a picture from
+   * a film: it scales, it tone-maps, it forces keyframes onto a grid, it caps a
+   * bitrate. The benchmark is fed raw frames of a known size and wants the
+   * encoder and the rung with nothing else in the way — otherwise the reading
+   * prices a scaler as though it were the encoder.
+   *
+   * WHY EVERY KIND MUST ANSWER IT. Until now the throughput benchmark existed
+   * only for libx264 and was gated on the chosen encoder being software, so a
+   * host with NVENC, QSV, VAAPI or V4L2M2M measured its encoder not at all —
+   * and the quality offer, which is arithmetic over pixels per second, had no
+   * pixels per second to work with. NVENC's own ladder is `p1`…`p7` and QSV's
+   * is `veryfast`…`veryslow`; both are declared here and neither was ever run.
+   *
+   * @param {string | null} rung - One value of {@link speedLadder}, or null
+   *   where the kind has no ladder and there is one thing to measure.
+   * @returns {string[]}
+   */
+  benchmarkArgs(rung = null) {
+    const ladder = this.speedLadder;
+    const setting = ladder?.flag && rung ? [ladder.flag, rung] : [];
+    return ["-c:v", this.name, ...setting];
+  }
 }

package/services/encode/QsvEncoder.js

@@ -35,6 +35,17 @@ export class QsvEncoder extends Encoder {
     };
   }
 
+  /** @returns {string[]} */
+  benchmarkInputArgs() {
+    return this.device ? ["-qsv_device", this.device] : [];
+  }
+
+  /** @param {string | null} rung @returns {string[]} */
+  benchmarkArgs(rung = null) {
+    const preset = rung ? ["-preset", rung] : [];
+    return ["-c:v", "h264_qsv", "-global_quality", "24", ...preset];
+  }
+
   buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
     const { w, h } = safeDimensions(targetWidth, targetHeight);
     return [

package/services/encode/SegmentStore.js

@@ -481,6 +481,20 @@ export class SegmentStore {
     this.#logger.info(`segment-store dropped ${directoryNameFor(key)} (${because})`);
   }
 
+  /**
+   * When this output was last asked for, or null where it has never been.
+   *
+   * The one reading that makes the keeping period measurable rather than
+   * guessed: a session opened on an output this answers for IS a return, and
+   * this is its age.
+   *
+   * @param {string} key
+   * @returns {number | null}
+   */
+  lastReadAt(key) {
+    return this.#touched.get(key) ?? null;
+  }
+
   /**
    * Throw away everything this store owns, and the root with it.
    *

package/services/encode/SoftwareEncoder.js

@@ -42,6 +42,11 @@ export class SoftwareEncoder extends Encoder {
     };
   }
 
+  /** @param {string | null} rung @returns {string[]} */
+  benchmarkArgs(rung = null) {
+    return ["-c:v", "libx264", "-preset", rung ?? SOFTWARE_PRESET, "-crf", SOFTWARE_CRF, "-pix_fmt", "yuv420p"];
+  }
+
   buildVideoArgs({
     targetWidth,
     targetHeight,

package/services/encode/VaapiEncoder.js

@@ -40,6 +40,19 @@ export class VaapiEncoder extends Encoder {
 
   // No fps filter: VAAPI inherits the source rate and keeps keyframes on the
   // grid via time-based -force_key_frames, so it already honours source fps.
+  /** @returns {string[]} */
+  benchmarkInputArgs() {
+    return this.device ? ["-vaapi_device", this.device] : [];
+  }
+
+  /** @param {string | null} rung @returns {string[]} */
+  benchmarkArgs(rung = null) {
+    // Raw frames live in this process; VAAPI encodes what is in the device, so
+    // the upload is part of what this kind costs and belongs in the reading.
+    const quality = rung ? ["-quality", rung] : [];
+    return ["-vf", "format=nv12,hwupload", "-c:v", "h264_vaapi", "-qp", "24", ...quality];
+  }
+
   buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
     const { w, h } = safeDimensions(targetWidth, targetHeight);
     return [