@torrent-tv/proxy 2.32.0 → 2.34.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.34.0
+
+- **New**: The proxy tells the browser the smallest buffer at which no interruption reaches the viewer, measured on the file being watched. It is one whole segment — the one being played — plus the worst wait its own reader met before the buffer could refill, from that file's recent interruptions on that swarm. On the field torrent of 2026-08-17 that is 7-9 s, where the browser has been waiting for a hand-chosen 25: sixteen seconds of spinner that nothing had shown to be necessary. Null until the reader has seen two interruptions — one wait shows no interval, and an interval invented from one point is what this work exists to remove — and the browser keeps its own figure until then. The reader measures it, the session manager states it with its own segment length, and the progress reply carries it.
+- **Chore**: Removed `services/torrent-worker/supply-interruptions.js`, a second copy of the same arithmetic that was wired to nothing.
+
+## 2.33.0
+
+- **New**: A quality step is judged on the machine it will actually run on. The encoder benchmark measures a QUIET host — one ffmpeg and nothing else — while the addon host was measured 99 % busy, and a step predicted at 1.83x ran at 1.01-1.12x (2026-08-17). The offer now multiplies each prediction by the share of the machine that is free, taken from the same `host-load` reading that is already printed every five seconds. What is subtracted is ONLY the work nobody has been charged for — the kernel, the container, whatever else the owner runs — because our own encoders are already priced by the concurrency arithmetic and the proxy's own work per megabyte moved. Charging those here as well is what shipped in 2.21.0 and emptied the quality menu down to a single copied height. On the field reading the correction is about 0.77, and the "not offering" line now says what the machine had to spare when it decided.
+- **New**: Each step reports what its prediction was worth. When a step runs with the machine to itself, the log states the speed it was predicted at, the speed it measured, and the ratio — so the error that REMAINS after the availability correction is a number in the field rather than an argument. It is written when it moves by more than a tenth, so a steady step says it once. On the field case that correction takes 1.83x to 1.41x against 1.01-1.12x measured: part of the gap, not all of it, and this line is how the rest gets found.
+
 ## 2.32.0
 
 - **New**: The decode cost is fitted from a clip set that can be checked, and a term the measurements do not determine is refused instead of published as a zero. The set that shipped until now was three clips for three unknowns — an EXACT system, with two of the clips at the same pixel rate — and such a system cannot fail visibly: it returns whatever satisfies its equations. On 2026-08-17 it returned `0.007542 × Mpx/s + 0.000000 × Mbit/s + 0.0000 s/s`, so a film's own bitrate never entered its price, and the prediction built on it was 1.8-2.2x optimistic against the same file measured while playing. The new set is six clips — three sizes × two bitrates, the axes varied INDEPENDENTLY — cut from the same Netflix Open Content "Meridian" footage (CC BY 4.0, `assets/calibration/NOTICE.md`), 7.7 MB against 8.8 MB before. Three spare measurements give the fit a residual, and with it two questions it could not ask before: whether a term's whole effect across the measured range exceeds the scatter, and whether the coefficient exceeds its own standard error. A term that fails either is dropped, the rest are fitted again, and the log names it — a zero now means "not measured" only when it says so. A NEGATIVE coefficient is dropped too rather than clamped to zero: more pixels cannot cost less work, so a negative fit is noise beating an effect, not a discovery about the host. Measured on the developer's machine, the new set determines all three terms (`0.000520 × Mpx/s + 0.002086 × Mbit/s + 0.0033 s/s`, typical disagreement 0.0012 s/s), and the bitrate term it recovers matches the difference between the two 1080p clips to 15 %. The arithmetic is a pure module with the degenerate case as a test (`services/decode-cost-fit.js`).

package/package.json

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

package/services/available-share.js

@@ -0,0 +1,89 @@
+/**
+ * @file How much of the machine a new encoder can actually have.
+ *
+ * The encoder benchmark measures a QUIET host: one ffmpeg, nothing else. A real
+ * encode runs on a machine that is also downloading, hashing and serving, and
+ * on the addon host that machine was measured 99 % busy — `ffmpeg=52-60%
+ * proxy=17-24% system=99%` — while a step predicted at 1.83x ran at 1.01-1.12x
+ * (2026-08-17).
+ *
+ * What this corrects is ONLY the part nobody has been charged for. That
+ * distinction is the whole of the file, because the alternative has already
+ * shipped once and broke the product: in 2.21.0 the budget ADDED what else was
+ * running while the per-file costs were being LEARNED from runs that already
+ * contained that other work, so every cost was counted twice, every re-encoded
+ * step was refused, and the quality menu emptied itself down to the one copied
+ * height (fixed in 2.21.1).
+ *
+ * So: our own encoders are priced by the concurrency arithmetic, and the
+ * proxy's own work — the torrent, the hashing, the delivery — is priced per
+ * megabyte moved. Both are already in the budget. What is NOT in it is
+ * everything else the machine does: the kernel, the container runtime, whatever
+ * else the owner runs on their box. That is what is subtracted here, and
+ * nothing more.
+ */
+
+/**
+ * The share of the machine available to a new encoder.
+ *
+ * @param {object} reading - Fractions of the WHOLE machine (all cores), as
+ *   `shareOfMachine` reports them.
+ * @param {number | null} reading.systemBusy - Everything the machine is doing.
+ * @param {number | null} reading.encoderShare - Our own ffmpeg processes.
+ * @param {number | null} reading.proxyShare - The proxy process itself.
+ * @returns {{ share: number, unattributed: number, known: boolean }}
+ *   `known` is false when the host does not report its own load — then the
+ *   share is 1 and the caller must say it is uncorrected rather than pretend.
+ */
+export function availableShareFrom(reading = {}) {
+  const systemBusy = finite(reading.systemBusy);
+  if (systemBusy === null) {
+    // No reading at all: not every host has /proc. An uncorrected prediction is
+    // the honest answer, and the caller says so.
+    return { share: 1, unattributed: 0, known: false };
+  }
+  const ours = (finite(reading.encoderShare) ?? 0) + (finite(reading.proxyShare) ?? 0);
+  // Rounding, and the two readings being taken microseconds apart, can put our
+  // own share fractionally above the system total. Below zero is not a
+  // measurement of anything.
+  const unattributed = clamp(systemBusy - ours, 0, 1);
+  return { share: clamp(1 - unattributed, 0, 1), unattributed, known: true };
+}
+
+/**
+ * Apply the correction to a predicted speed.
+ *
+ * A speed is work per unit time, so a machine that can give a new encoder only
+ * `share` of itself produces `share ×` the speed the benchmark measured alone.
+ *
+ * @param {number} predictedSpeed - From the quiet-host benchmark.
+ * @param {{ share: number, known: boolean }} availability
+ * @returns {number}
+ */
+export function correctForAvailability(predictedSpeed, availability) {
+  if (!Number.isFinite(predictedSpeed) || predictedSpeed <= 0) {
+    return predictedSpeed;
+  }
+  if (!availability?.known) {
+    return predictedSpeed;
+  }
+  return predictedSpeed * availability.share;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+function finite(value) {
+  return Number.isFinite(value) ? Number(value) : null;
+}
+
+/**
+ * @param {number} value
+ * @param {number} low
+ * @param {number} high
+ * @returns {number}
+ */
+function clamp(value, low, high) {
+  return Math.min(high, Math.max(low, value));
+}

package/services/hls-session-manager.js

@@ -20,6 +20,8 @@ import { logger } from "../utils/logger.js";
 import { readKeyframeIndex } from "./container-index/index.js";
 import { readMachineState, readProcessCpuSeconds, readProxyCpuSeconds, readSystemCpu, shareOfMachine } from "./host-load.js";
 import { speedFromReadings } from "./encoder-readings.js";
+import { availableShareFrom, correctForAvailability } from "./available-share.js";
+import { minimumBufferFrom } from "./supply-margin.js";
 import {
   ENCODE_RUN_EVENT,
   ENCODE_RUN_STATE,
@@ -1902,6 +1904,12 @@ export class HlsSessionManager {
       // software hosts, else the client target). 0 = keep source.
       encodeWidth,
       encodeHeight,
+      // What the offer predicted this height would do on this machine, so the
+      // field can say what the prediction was worth once the step runs. Null
+      // when the step was never judged — a copied stream needs no encoder and
+      // is never predicted.
+      predictedSpeedWhenOffered: this.lastPredictedByHeight?.get(encodeHeight) ?? null,
+      lastPredictionRatio: null,
       // The NAME of this rung, fixed at the height that was asked for. It is
       // deliberately not the height being encoded: a viewer who picked 480p on
       // a host that then starts them at 360p, or steps down to it later, goes
@@ -3217,13 +3225,25 @@ export class HlsSessionManager {
     const proxyShare = Number.isFinite(previous.proxyCpuSeconds)
       ? (sample.proxyCpuSeconds - previous.proxyCpuSeconds) / (share.elapsedSec * cores)
       : null;
+    // Kept for the quality offer, which predicts from a benchmark taken on a
+    // QUIET host: the same reading that is printed here says how much of the
+    // machine a new encoder could actually have. Only what nobody has been
+    // charged for is subtracted — see `available-share.js`.
+    this.hostAvailability = availableShareFrom({
+      systemBusy: share.systemShare,
+      encoderShare: share.processShare,
+      proxyShare
+    });
     logger.info(
       `host-load: ffmpeg=${asPercent(share.processShare)} proxy=${asPercent(proxyShare)} ` +
       `system=${asPercent(share.systemShare)} ` +
       `iowait=${asPercent(share.iowaitShare)} cpu=${machine.megahertz === null ? "n/a" : `${machine.megahertz}MHz`} ` +
       `temp=${machine.celsius === null ? "n/a" : `${machine.celsius}C`} ` +
       `encoders=${running} running` + (suspended > 0 ? ` +${suspended} suspended` : "") +
-      ` over=${share.elapsedSec.toFixed(1)}s`
+      ` over=${share.elapsedSec.toFixed(1)}s` +
+      // What the offer will multiply a prediction by, in the same line as the
+      // readings it comes from.
+      ` available=${asPercent(this.hostAvailability.share)}`
     );
   }
 
@@ -3349,6 +3369,12 @@ export class HlsSessionManager {
     if (!stats) {
       return "unknown";
     }
+    // What this file's own interruptions demand, measured by the reader. Kept
+    // on the session because the browser is told the buffer that follows from
+    // it, and because the quality offer will be held to the speed it names.
+    if (stats.supply) {
+      session.supplyFigures = stats.supply;
+    }
     // A fully (or almost fully) downloaded file cannot be download-bound.
     if (typeof stats.fileProgress === "number" && stats.fileProgress >= 0.999) {
       return "cpu";
@@ -3391,6 +3417,10 @@ export class HlsSessionManager {
     // although nothing is producing that step any more. The next reading of the
     // new encode replaces it.
     session.lastAloneSpeed = null;
+    // And so is the prediction it was compared against: it described the step
+    // this session has just left.
+    session.predictedSpeedWhenOffered = this.lastPredictedByHeight?.get(rung.height) ?? null;
+    session.lastPredictionRatio = null;
     // Priced the same way the offer and the starting rung are. Choosing the
     // preset on the encoder alone treats decoding as free, which is how the
     // check and the encode came to disagree in the first place — and here it
@@ -5444,6 +5474,25 @@ export class HlsSessionManager {
     // 0.3x reads as 3.33 s of work per second of video, more than the machine
     // has — and every other quality step was refused on the download's account.
     session.lastAloneSpeed = speed;
+    // What the offer predicted for this very step, against what it then did
+    // with the machine to itself. The prediction is corrected for the share of
+    // the machine that was free at the time, so this ratio is the error that
+    // remains AFTER that correction — which is the only way to tell whether a
+    // stage of roadmap item 3 moved anything. Written when it changes by more
+    // than a tenth, so a steady step says it once rather than every five
+    // seconds.
+    if (Number.isFinite(session.predictedSpeedWhenOffered) && session.predictedSpeedWhenOffered > 0) {
+      const ratio = speed / session.predictedSpeedWhenOffered;
+      const lastSaid = session.lastPredictionRatio;
+      if (!Number.isFinite(lastSaid) || Math.abs(ratio - lastSaid) > 0.1) {
+        session.lastPredictionRatio = ratio;
+        logger.info(
+          `prediction ${session.id.slice(0, 8)} ${session.encodeHeight || "source"}p: ` +
+          `predicted ${session.predictedSpeedWhenOffered.toFixed(2)}x, measured ${speed.toFixed(2)}x ` +
+          `(ratio ${ratio.toFixed(2)}; 1.00 would mean the arithmetic describes this machine)`
+        );
+      }
+    }
     if (kind === "audio") {
       // What is left after the work that was already accounted for. `null` when
       // the subtraction leaves nothing positive, which means the reading says
@@ -5962,6 +6011,12 @@ export class HlsSessionManager {
     const kept = [];
     /** @type {string[]} */
     const dropped = [];
+    // What each height was predicted to do on THIS machine, kept so a session
+    // started at that height can be compared against it once it runs. The
+    // manager holds the last answer, because the offer is computed on the path
+    // that serves every request while a session is created elsewhere.
+    /** @type {Map<number, number | null>} */
+    const predictedByHeight = new Map();
     for (const height of heights) {
       // The height an encoder is ALREADY producing, and the source's own height
       // when the FAMILY serves it by copy — neither has to be predicted,
@@ -6004,7 +6059,7 @@ export class HlsSessionManager {
         0,
         concurrentCostSec - (runningCostByHeight?.get(height) ?? 0)
       );
-      const { speed, sustainable } = canSustainOutput({
+      const { speed } = canSustainOutput({
         benchmark,
         decodeModel: this.decodeCostModel,
         source,
@@ -6012,11 +6067,24 @@ export class HlsSessionManager {
         observedDecodeCostSec,
         concurrentCostSec: concurrentBesideThis
       });
-      if (sustainable) {
+      // The benchmark behind that figure was taken on a QUIET host — one
+      // ffmpeg and nothing else. The machine a step will actually run on is
+      // also running the kernel, the container and whatever else its owner
+      // does, and on the addon host that was measured at 99 % busy with a
+      // quarter of it unattributed. Only the unattributed part is charged
+      // here: our own encoders are already in `concurrentBesideThis` and the
+      // proxy's own work is already priced per megabyte moved.
+      const onThisMachine = correctForAvailability(speed, this.hostAvailability);
+      // Kept against the step's own session, so that when it runs the field
+      // says what the prediction was worth. Without this the only comparison
+      // available is between two figures written minutes apart in different
+      // lines of the log.
+      predictedByHeight.set(height, onThisMachine);
+      if (onThisMachine !== null && onThisMachine >= REALTIME_SPEED_MARGIN) {
         kept.push(height);
         continue;
       }
-      dropped.push(`${height}p=${speed === null ? "n/a" : `${speed.toFixed(2)}x`}`);
+      dropped.push(`${height}p=${onThisMachine === null ? "n/a" : `${onThisMachine.toFixed(2)}x`}`);
     }
     // Written when the ANSWER changes, not when the answer is recomputed. This
     // is asked on the path that serves every playlist, init and segment, and
@@ -6026,12 +6094,19 @@ export class HlsSessionManager {
     if (dropped.length > 0) {
       const line =
         `transcode: not offering ${dropped.join(" ")} — below realtime × ${REALTIME_SPEED_MARGIN} ` +
+        // Said with the figures, because a step refused on a busy machine and
+        // one refused on an idle machine are different facts about the host.
+        (this.hostAvailability?.known
+          ? `on a machine with ${Math.round(this.hostAvailability.share * 100)}% to spare `
+          : "") +
         `(offering ${kept.map((height) => `${height}p`).join(" ")})`;
       if (line !== this.#lastOfferLine) {
         this.#lastOfferLine = line;
         logger.info(line);
       }
+      this.lastPredictedByHeight = predictedByHeight;
     } else {
+      this.lastPredictedByHeight = predictedByHeight;
       this.#lastOfferLine = "";
     }
     return kept;
@@ -7521,6 +7596,17 @@ export class HlsSessionManager {
       // the browser tracks its sessions by the id it was given.
       sessionId: named.id,
       state: wireState(session.runState),
+      // The smallest buffer at which no interruption reaches the viewer, from
+      // THIS file's own recent interruptions: one whole segment — the one being
+      // played — plus the worst wait that can arrive before the buffer refills.
+      // On the field torrent that is 7-9 s where the browser waits for a
+      // hand-chosen 25, which is sixteen seconds of staring at a spinner that
+      // nothing had shown to be necessary. Null until the reader has seen two
+      // interruptions; the browser keeps its own figure until then.
+      minimumBufferSeconds: minimumBufferFrom({
+        segmentSeconds: this.segmentDurationSec,
+        worstSupplyWaitSec: session.supplyFigures?.worstWaitSec
+      })?.seconds ?? null,
       processedSeconds: session.progress.processedSeconds,
       startPositionSeconds: session.progress.startPositionSeconds ?? 0,
       totalSeconds: session.progress.totalSeconds,

package/services/torrent-worker/piece-reader.js

@@ -340,6 +340,39 @@ const supplyReportedAt = new Map();
  * @param {number} waitedMs
  * @returns {void}
  */
+/**
+ * What this file's recent interruptions demand, for a caller that has to decide
+ * something with them.
+ *
+ * Exported because the figures are measured HERE — the reader is the only place
+ * that knows how long it waited — while the decisions they feed are made
+ * elsewhere: the smallest buffer that hides an interruption goes to the browser,
+ * and the speed a step must sustain goes to the quality offer.
+ *
+ * @param {string} infoHash
+ * @param {string} fileName
+ * @param {number} segmentSeconds - The session's own segment duration.
+ * @returns {{ requiredSpeed: number, worstWaitSec: number, medianIntervalSec: number, samples: number, minimumBufferSec: number } | null}
+ */
+export function supplyFiguresFor(infoHash, fileName, segmentSeconds) {
+  const history = supplyWaits.get(`${infoHash ?? "?"}/${fileName ?? "?"}`);
+  const demand = requiredSpeedFrom(history ?? []);
+  if (!demand) {
+    return null;
+  }
+  const buffer = minimumBufferFrom({
+    segmentSeconds,
+    worstSupplyWaitSec: demand.worstWaitSec
+  });
+  return {
+    requiredSpeed: demand.requiredSpeed,
+    worstWaitSec: demand.worstWaitSec,
+    medianIntervalSec: demand.medianIntervalSec,
+    samples: demand.samples,
+    minimumBufferSec: buffer ? buffer.seconds : null
+  };
+}
+
 function noteSupplyWait(key, label, waitedMs) {
   const history = supplyWaits.get(key) ?? [];
   history.push({ waitedMs, at: Date.now() });

package/services/torrent-worker/worker.js

@@ -26,7 +26,7 @@ import "./install-webrtc-shim.js";
 import { parentPort, workerData } from "node:worker_threads";
 import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
-import { readFragments } from "./piece-reader.js";
+import { readFragments, supplyFiguresFor } from "./piece-reader.js";
 import { Command, Event } from "./protocol.js";
 
 // Imported dynamically, and that is load-bearing: static imports are RESOLVED
@@ -358,9 +358,20 @@ async function runCommand(command, params, id) {
 
     case Command.FILE_STATS: {
       const torrent = await requireTorrent(params.sourceKey);
-      return pool.getFileStats(torrent, params.fileIndex, {
+      const stats = pool.getFileStats(torrent, params.fileIndex, {
         resumeAnchorByteStart: params.resumeAnchorByteStart ?? null
       });
+      // What this file's own interruptions demand, measured by the reader in
+      // this thread. It travels with the stats because the caller asking for
+      // them is the one that has to decide with them — the browser's smallest
+      // safe buffer, and the speed a quality step must sustain. Null until a
+      // second interruption has been seen: one wait shows no interval, and an
+      // interval invented from one point is exactly what this work removes.
+      const file = Array.isArray(torrent?.files) ? torrent.files[params.fileIndex] : null;
+      return {
+        ...stats,
+        supply: supplyFiguresFor(torrent?.infoHash, file?.name, params.segmentSeconds ?? 4)
+      };
     }
 
     case Command.PRIORITIZE: {

package/test/available-share.test.js

@@ -0,0 +1,76 @@
+/**
+ * @file What the machine can spare for a new encoder — and what must not be
+ * charged twice.
+ *
+ * The numbers are the addon host's own, measured 2026-08-17 while a 240p step
+ * ran at 1.01-1.12x against a prediction of 1.83x.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { availableShareFrom, correctForAvailability } from "../services/available-share.js";
+
+test("only the work nobody has been charged for is subtracted", () => {
+  // The field reading: the box is saturated, our encoder has more than half of
+  // it, and the proxy's own work a fifth.
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
+
+  assert.equal(availability.known, true);
+  // 0.99 − 0.76 = 0.23 belongs to the kernel, the container and whatever else
+  // the owner runs. Our own encoders are priced by the concurrency arithmetic
+  // and the proxy's work per megabyte moved; charging them here as well is the
+  // double counting that emptied the quality menu in 2.21.0.
+  assert.ok(Math.abs(availability.unattributed - 0.23) < 1e-9, `${availability.unattributed}`);
+  assert.ok(Math.abs(availability.share - 0.77) < 1e-9, `${availability.share}`);
+});
+
+test("a quiet machine is not corrected at all", () => {
+  const availability = availableShareFrom({ systemBusy: 0.05, encoderShare: 0.04, proxyShare: 0.01 });
+  assert.equal(availability.unattributed, 0);
+  assert.equal(availability.share, 1);
+  assert.equal(correctForAvailability(4, availability), 4);
+});
+
+test("a host that cannot say says so, and nothing is corrected", () => {
+  // Not every host has /proc. An uncorrected figure is honest; a figure
+  // corrected by an invented share is not.
+  const availability = availableShareFrom({ systemBusy: null, encoderShare: null, proxyShare: null });
+  assert.equal(availability.known, false);
+  assert.equal(availability.share, 1);
+  assert.equal(correctForAvailability(2.5, availability), 2.5, "an unknown machine leaves the prediction alone");
+  assert.equal(availableShareFrom().known, false);
+});
+
+test("readings that overlap by a rounding do not produce a negative machine", () => {
+  // The two samples are taken microseconds apart, so our own share can come out
+  // fractionally above the system total.
+  const availability = availableShareFrom({ systemBusy: 0.60, encoderShare: 0.58, proxyShare: 0.05 });
+  assert.equal(availability.unattributed, 0);
+  assert.equal(availability.share, 1);
+});
+
+test("a machine given over entirely to other work leaves nothing", () => {
+  const availability = availableShareFrom({ systemBusy: 1, encoderShare: 0, proxyShare: 0 });
+  assert.equal(availability.share, 0);
+  assert.equal(correctForAvailability(4, availability), 0, "a step cannot be offered on a machine with nothing left");
+});
+
+test("the correction is proportional, and only ever downwards", () => {
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
+  // The field case: a step predicted at 1.83x on a quiet box.
+  const corrected = correctForAvailability(1.83, availability);
+  assert.ok(Math.abs(corrected - 1.4091) < 0.001, `${corrected}`);
+  // And the honest note this test exists to record: 1.41x is still above the
+  // 1.01-1.12x that step actually ran at. This correction closes part of the
+  // gap, not all of it — which is why the per-step field comparison ships with
+  // it rather than after it.
+  assert.ok(corrected > 1.12, "the remaining difference is what the field check is for");
+});
+
+test("nothing is corrected without a prediction to correct", () => {
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.5, proxyShare: 0.2 });
+  assert.equal(correctForAvailability(0, availability), 0);
+  assert.equal(correctForAvailability(Number.NaN, availability), Number.NaN);
+  assert.equal(correctForAvailability(-1, availability), -1);
+});

package/services/torrent-worker/supply-interruptions.js

@@ -1,155 +0,0 @@
-/**
- * @file What the supply's own interruptions require of a quality step, and of
- * the buffer in front of the viewer.
- *
- * Both figures are chosen by hand today — a speed margin of 1.5 and a 25-second
- * prebuffer — and both stand for a quantity that is measured every few seconds
- * anyway: how long a read waits for a piece, and how often that happens.
- *
- * The arithmetic, from the measurements of 2026-08-17:
- *
- *   A step producing at speed `v` gains `v - 1` seconds of cushion per second
- *   of playback. An interruption of `W` seconds costs `W`. So a step survives
- *   its own supply exactly when it can rebuild what one interruption takes
- *   before the next one arrives:
- *
- *       (v - 1) × T > W   ⇔   v > 1 + W / T
- *
- *   On the field torrent that day: waits of 1.49 s median, 3.16 s worst, one
- *   every 2.22 s → a required speed of 1.67 against the 1.5 chosen by hand, and
- *   against 1.05 actually measured, which is why it stalled. A copy running at
- *   8x gains 15.5 s between interruptions against 1.5-4.8 s lost, which is the
- *   same formula explaining why a copy never stalls.
- *
- *   The buffer follows from the same numbers: it must hold the segment being
- *   played, whole, plus the worst interruption that can arrive before it can be
- *   refilled — whichever source that interruption comes from.
- *
- *       B_min = segment duration + max(W_supply, D_production, T_transfer)
- *
- *   7-9 s on that torrent, against the 25 s in the browser today.
- *
- * Every term is measured, none is chosen, and the figures rise by themselves
- * when a session's interruptions grow — which is what makes lowering the buffer
- * safe. Pure: no torrent, no clock of its own, no state beyond the samples it
- * is given.
- */
-
-/**
- * How many recent interruptions are kept per file. Enough for a median to mean
- * something, short enough that a swarm which has recovered is not judged by how
- * it behaved ten minutes ago.
- */
-const SAMPLE_LIMIT = 24;
-
-/**
- * A reading of one interruption: how long the reader waited, and when.
- *
- * @typedef {object} Interruption
- * @property {number} waitedMs
- * @property {number} at - Epoch milliseconds when the wait ENDED.
- */
-
-/**
- * Add one interruption to a record, keeping only the recent ones.
- *
- * @param {Interruption[]} samples - Existing readings, oldest first.
- * @param {Interruption} interruption
- * @returns {Interruption[]} A new array; the input is not modified.
- */
-export function withInterruption(samples, interruption) {
-  const kept = Array.isArray(samples) ? samples : [];
-  if (!Number.isFinite(interruption?.waitedMs) || !Number.isFinite(interruption?.at)) {
-    return kept;
-  }
-  const next = [...kept, { waitedMs: Math.max(0, interruption.waitedMs), at: interruption.at }];
-  return next.length > SAMPLE_LIMIT ? next.slice(next.length - SAMPLE_LIMIT) : next;
-}
-
-/**
- * @param {number[]} values
- * @returns {number}
- */
-function median(values) {
-  if (values.length === 0) {
-    return 0;
-  }
-  const sorted = [...values].sort((left, right) => left - right);
-  return sorted[Math.floor(sorted.length / 2)];
-}
-
-/**
- * What the recent interruptions amount to.
- *
- * The interval between interruptions is measured between the readings
- * themselves, so a file that is read steadily and rarely blocked reports a long
- * interval and asks little of the step.
- *
- * @param {Interruption[]} samples
- * @returns {{ samples: number, medianWaitSeconds: number, worstWaitSeconds: number, medianGapSeconds: number }}
- */
-export function summariseInterruptions(samples) {
-  const readings = Array.isArray(samples) ? samples : [];
-  if (readings.length === 0) {
-    return { samples: 0, medianWaitSeconds: 0, worstWaitSeconds: 0, medianGapSeconds: 0 };
-  }
-  const waits = readings.map((entry) => entry.waitedMs / 1000);
-  const gaps = [];
-  for (let index = 1; index < readings.length; index += 1) {
-    const gap = (readings[index].at - readings[index - 1].at) / 1000;
-    if (gap > 0) {
-      gaps.push(gap);
-    }
-  }
-  return {
-    samples: readings.length,
-    medianWaitSeconds: median(waits),
-    worstWaitSeconds: Math.max(...waits),
-    medianGapSeconds: median(gaps)
-  };
-}
-
-/**
- * The speed a step must run at to survive this supply, or null when the supply
- * has not interrupted often enough to say.
- *
- * Null is a real answer and must not be replaced by a number: with one reading
- * there is no interval at all, and inventing one is how a margin comes to be
- * chosen by hand again. A caller with no figure keeps whatever it used before
- * and says so.
- *
- * The worst wait is used rather than the median, because a step that only
- * survives the typical interruption stalls on the others — and a stall is what
- * the viewer sees, not an average.
- *
- * @param {{ samples: number, worstWaitSeconds: number, medianGapSeconds: number }} summary
- * @returns {number | null}
- */
-export function requiredSpeedFrom(summary) {
-  if (!summary || summary.samples < 2 || !(summary.medianGapSeconds > 0)) {
-    return null;
-  }
-  return 1 + summary.worstWaitSeconds / summary.medianGapSeconds;
-}
-
-/**
- * The smallest buffer at which no spinner appears: the segment being played,
- * whole, plus the worst interruption that can arrive before it can be refilled.
- *
- * Each term is the worst OBSERVED over a recent window, and a term nobody has
- * measured contributes nothing rather than a guess.
- *
- * @param {{ segmentSeconds: number, supplySeconds?: number, productionSeconds?: number, transferSeconds?: number }} terms
- * @returns {number}
- */
-export function minimumBufferSeconds(terms) {
-  const segment = Number.isFinite(terms?.segmentSeconds) && terms.segmentSeconds > 0
-    ? terms.segmentSeconds
-    : 0;
-  const worst = Math.max(
-    Number.isFinite(terms?.supplySeconds) ? terms.supplySeconds : 0,
-    Number.isFinite(terms?.productionSeconds) ? terms.productionSeconds : 0,
-    Number.isFinite(terms?.transferSeconds) ? terms.transferSeconds : 0
-  );
-  return segment + Math.max(0, worst);
-}

package/test/supply-interruptions.test.js

@@ -1,125 +0,0 @@
-/**
- * @file The speed a step needs, and the buffer a viewer needs, from what the
- * supply actually did.
- *
- * The field numbers these are checked against (2026-08-17, one torrent, one
- * session): waits of 1.49 s median and 3.16 s worst, one every 2.22 s. The
- * margin chosen by hand was 1.5; the arithmetic says 1.67; the step measured
- * 1.05 and stalled.
- */
-
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import {
-  minimumBufferSeconds,
-  requiredSpeedFrom,
-  summariseInterruptions,
-  withInterruption
-} from "../services/torrent-worker/supply-interruptions.js";
-
-/**
- * Interruptions of `waitMs`, one every `gapMs`.
- *
- * @param {number[]} waitsMs
- * @param {number} gapMs
- * @returns {Array<{ waitedMs: number, at: number }>}
- */
-function series(waitsMs, gapMs) {
-  let samples = [];
-  let at = 1_000_000;
-  for (const waitedMs of waitsMs) {
-    samples = withInterruption(samples, { waitedMs, at });
-    at += gapMs;
-  }
-  return samples;
-}
-
-test("the field session's numbers produce the field session's answer", () => {
-  // Waits around 1.49 s with a worst of 3.16 s, one every 2.22 s.
-  const samples = series([1490, 1490, 3160, 1490, 1490], 2220);
-  const summary = summariseInterruptions(samples);
-
-  assert.equal(summary.worstWaitSeconds, 3.16);
-  assert.equal(summary.medianGapSeconds, 2.22);
-
-  const required = requiredSpeedFrom(summary);
-  assert.ok(required !== null);
-  assert.ok(
-    Math.abs(required - 2.42) < 0.01,
-    `1 + 3.16/2.22 = ${required?.toFixed(2)} — the supply asks for it, nobody chose it`
-  );
-});
-
-test("a supply that rarely interrupts asks for almost nothing", () => {
-  // One short wait every couple of minutes: a step barely faster than realtime
-  // rebuilds the cushion long before the next one.
-  const summary = summariseInterruptions(series([200, 200, 200], 120_000));
-  const required = requiredSpeedFrom(summary);
-  assert.ok(required !== null && required < 1.01, `asked ${required}`);
-});
-
-test("a supply that interrupts constantly asks for a great deal", () => {
-  const summary = summariseInterruptions(series([4000, 4000, 4000], 1000));
-  assert.equal(requiredSpeedFrom(summary), 5);
-});
-
-test("too little evidence is answered with nothing, never with a number", () => {
-  // The whole point of deriving the margin is that it stops being invented. One
-  // reading has no interval at all, and a caller must keep what it had.
-  assert.equal(requiredSpeedFrom(summariseInterruptions([])), null);
-  assert.equal(requiredSpeedFrom(summariseInterruptions(series([1000], 0))), null);
-  assert.equal(requiredSpeedFrom(null), null);
-  assert.equal(requiredSpeedFrom({ samples: 9, worstWaitSeconds: 3, medianGapSeconds: 0 }), null);
-});
-
-test("the worst wait decides, not the typical one", () => {
-  // A step that survives the median interruption still stalls on the others,
-  // and a stall is what the viewer sees.
-  const summary = summariseInterruptions(series([100, 100, 5000, 100], 1000));
-  assert.equal(summary.medianWaitSeconds, 0.1);
-  assert.equal(summary.worstWaitSeconds, 5);
-  assert.equal(requiredSpeedFrom(summary), 6);
-});
-
-test("only the recent interruptions are judged", () => {
-  // A swarm that has recovered must not be sentenced by how it behaved ten
-  // minutes ago, so the record is bounded.
-  let samples = series(Array.from({ length: 40 }, () => 9000), 1000);
-  samples = withInterruption(samples, { waitedMs: 10, at: 2_000_000 });
-  assert.ok(samples.length <= 24, `kept ${samples.length}`);
-  assert.equal(samples[samples.length - 1].waitedMs, 10);
-});
-
-test("a reading without a time or a duration is not a reading", () => {
-  const samples = withInterruption([], { waitedMs: Number.NaN, at: 1 });
-  assert.deepEqual(samples, []);
-  assert.deepEqual(withInterruption([], { waitedMs: 100 }), []);
-});
-
-test("the minimum buffer is one segment plus the worst interruption", () => {
-  // The field torrent: 4 s segments, a worst supply wait of 3.16 s, production
-  // gaps within the segment length, transfer measured in milliseconds.
-  const seconds = minimumBufferSeconds({
-    segmentSeconds: 4,
-    supplySeconds: 3.16,
-    productionSeconds: 1.2,
-    transferSeconds: 0.066
-  });
-  assert.ok(Math.abs(seconds - 7.16) < 0.001, `${seconds}s against the 25 s chosen by hand`);
-});
-
-test("whichever source is worst is the one that sizes the buffer", () => {
-  // A step at 1.0x makes production the binding term even on a swarm that never
-  // stalls, which is exactly the case a supply-only figure would miss.
-  assert.equal(
-    minimumBufferSeconds({ segmentSeconds: 4, supplySeconds: 0.2, productionSeconds: 6 }),
-    10
-  );
-});
-
-test("a term nobody measured contributes nothing, not a guess", () => {
-  assert.equal(minimumBufferSeconds({ segmentSeconds: 4 }), 4);
-  assert.equal(minimumBufferSeconds({ segmentSeconds: 4, supplySeconds: Number.NaN }), 4);
-  assert.equal(minimumBufferSeconds({}), 0);
-});