@torrent-tv/proxy 2.33.0 → 2.35.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.35.0
+
+- **New**: A second job's cost is measured on the host instead of being added as though jobs were independent. Measured on the addon host 2026-08-18, decoding the same clip: **2.10-2.25x alone, 0.79-0.90x with one encoder beside it, 0.56-0.64x with two** — the same work costs 2.6× more for having company, and 3.7× for having two. Heat is not the cause: the hot idle machine (68 °C, a lower reported clock) was the fastest reading of all, which settles what roadmap item 6 was opened for. Four cores sharing one path to memory is the cause, and it contradicts the SHAPE of the budget rather than its constants — everything in the quality offer adds seconds of work per second of content, and these readings say two jobs that each fit alone do not fit together. So the penalty is now measured at startup the way everything else is (the cheapest clip decoded alone, then again while an encoder of it runs), and the offer multiplies a step's cost by it when anything else is encoding. Beyond the readings it holds the largest rather than extrapolating: two points say nothing about a fourth job, and a budget that guesses at a memory bottleneck will be wrong in whichever direction it guesses. With nothing measured, nothing is corrected. This is separate from the availability share of 2.33.0, which removes work nobody has been charged for; this is our own work colliding with itself.
+
+## 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.

package/package.json

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

package/server.js

@@ -37,7 +37,7 @@ import { createSourceRegistry } from "./store/source-registry.js";
 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, detectTonemapSupport } from "./services/hwaccel.js";
+import { detectVideoEncoder, benchmarkSoftwarePresets, benchmarkDecodeCost, benchmarkContention, detectTonemapSupport } from "./services/hwaccel.js";
 import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -130,6 +130,12 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   const decodeCostModel = videoEncoder?.kind === "software"
     ? 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"
+    ? await benchmarkContention({ ffmpegBin, logger })
+    : null;
   const softwarePresetBenchmark = videoEncoder?.kind === "software"
     ? await benchmarkSoftwarePresets({ ffmpegBin, logger })
     : null;
@@ -147,6 +153,7 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     videoEncoder,
     softwarePresetBenchmark,
     decodeCostModel,
+    contentionPenalties,
     tonemapSupported,
     segmentFormatId: segmentFormat,
     stateDir,

package/services/contention.js

@@ -0,0 +1,128 @@
+/**
+ * @file What a second job costs on this machine — measured, because it is not
+ * the sum of two prices.
+ *
+ * Measured on the addon host 2026-08-18, decoding the same clip:
+ *
+ * | what else was running | decode speed | cost |
+ * |---|---|---|
+ * | nothing (cold) | 2.10-2.25x | 0.46 s/s |
+ * | nothing (hot, 68 °C) | 2.30-2.33x | 0.43 s/s |
+ * | one encoder | 0.79-0.90x | 1.18 s/s |
+ * | two encoders | 0.56-0.64x | 1.67 s/s |
+ *
+ * The same work costs **2.6× more** with one encoder beside it and 3.7× with
+ * two. Heat is not the cause — the hot idle machine was the fastest of all.
+ * Four cores share one narrow path to memory, and decoding and encoding both
+ * saturate it.
+ *
+ * That contradicts the shape of the budget, not just its constants. Everything
+ * in the quality offer adds seconds of work per second of content — this
+ * encode, plus that decode, plus what is already committed — and these readings
+ * say two jobs that each fit alone do not fit together. The availability
+ * correction in `available-share.js` does not cover it either: that subtracts
+ * the share of the machine taken by work nobody has been charged for, while
+ * this is our own work colliding with itself.
+ *
+ * So the penalty is measured rather than derived, at startup, on the host it
+ * describes — and beyond the range that was measured it does not extrapolate:
+ * it holds the largest reading and says so, because nothing here knows what a
+ * fourth job would do.
+ */
+
+/**
+ * Penalties measured on this host, keyed by how many OTHER jobs were running.
+ *
+ * @typedef {Map<number, number>} ContentionPenalties
+ */
+
+/**
+ * The multiplier for a job's cost when `othersRunning` other jobs share the
+ * machine.
+ *
+ * @param {number} othersRunning
+ * @param {ContentionPenalties | null} measured
+ * @returns {{ penalty: number, measured: boolean, from: number }}
+ *   `from` is the reading it came from — equal to `othersRunning` when one was
+ *   measured for exactly that many, and the largest available otherwise.
+ */
+export function contentionPenalty(othersRunning, measured) {
+  const others = Number.isFinite(othersRunning) ? Math.max(0, Math.round(othersRunning)) : 0;
+  if (others === 0) {
+    // Alone on the machine is what every benchmark measures, so there is
+    // nothing to correct.
+    return { penalty: 1, measured: true, from: 0 };
+  }
+  if (!(measured instanceof Map) || measured.size === 0) {
+    // Nothing measured: the honest multiplier is 1, and the caller's own log
+    // says the prediction is uncorrected. Inventing a penalty would be the
+    // same mistake as inventing a fill rate.
+    return { penalty: 1, measured: false, from: 0 };
+  }
+  const exact = measured.get(others);
+  if (Number.isFinite(exact) && exact > 0) {
+    return { penalty: exact, measured: true, from: others };
+  }
+  // Beyond what was measured, hold the largest reading rather than continue the
+  // curve. Two readings say nothing about the shape past them, and a budget
+  // that extrapolates a memory bottleneck will be wrong in whichever direction
+  // it guesses.
+  let largestKey = 0;
+  let largestValue = 1;
+  for (const [key, value] of measured) {
+    if (key <= others && key > largestKey && Number.isFinite(value) && value > 0) {
+      largestKey = key;
+      largestValue = value;
+    }
+  }
+  if (largestKey === 0) {
+    return { penalty: 1, measured: false, from: 0 };
+  }
+  return { penalty: largestValue, measured: true, from: largestKey };
+}
+
+/**
+ * A cost, corrected for what else will be running.
+ *
+ * @param {number} costSecondsPerSecond - As the benchmarks priced it, alone.
+ * @param {number} othersRunning
+ * @param {ContentionPenalties | null} measured
+ * @returns {number}
+ */
+export function costWithContention(costSecondsPerSecond, othersRunning, measured) {
+  if (!Number.isFinite(costSecondsPerSecond) || costSecondsPerSecond <= 0) {
+    return costSecondsPerSecond;
+  }
+  return costSecondsPerSecond * contentionPenalty(othersRunning, measured).penalty;
+}
+
+/**
+ * Turn measured decode speeds into penalties.
+ *
+ * @param {number} aloneSpeed - Decode speed with the machine to itself.
+ * @param {Array<{ others: number, speed: number }>} beside - One reading per
+ *   number of other jobs running.
+ * @returns {ContentionPenalties | null} Null when the alone reading is missing,
+ *   since every penalty is relative to it.
+ */
+export function penaltiesFrom(aloneSpeed, beside) {
+  if (!Number.isFinite(aloneSpeed) || aloneSpeed <= 0) {
+    return null;
+  }
+  const penalties = new Map();
+  for (const reading of Array.isArray(beside) ? beside : []) {
+    const others = Number.isFinite(reading?.others) ? Math.round(reading.others) : null;
+    const speed = Number(reading?.speed);
+    if (others === null || others <= 0 || !Number.isFinite(speed) || speed <= 0) {
+      continue;
+    }
+    // Cost is the reciprocal of speed, so the penalty is the reciprocal ratio.
+    // A job that runs at half the speed costs twice as much.
+    const penalty = aloneSpeed / speed;
+    // Below 1 would mean the machine got FASTER for being busier. It happens in
+    // the noise on a fast host, and it is not a discovery — it is a reading
+    // that says there is no penalty to measure here.
+    penalties.set(others, penalty > 1 ? penalty : 1);
+  }
+  return penalties.size > 0 ? penalties : null;
+}

package/services/hls-session-manager.js

@@ -21,6 +21,8 @@ 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 { contentionPenalty } from "./contention.js";
+import { minimumBufferFrom } from "./supply-margin.js";
 import {
   ENCODE_RUN_EVENT,
   ENCODE_RUN_STATE,
@@ -1371,6 +1373,10 @@ export class HlsSessionManager {
     softwarePresetBenchmark = null,
     decodeCostModel = null,
     getSourceStats = null,
+    // What a second job costs on this host, measured at startup. Null when it
+    // could not be measured, and then nothing is corrected — the alternative
+    // is inventing a penalty, which is the same fault as inventing a fill rate.
+    contentionPenalties = null,
     tonemapSupported = false,
     getCachedMediaInfo = null,
     getCachedAudioTracks = null,
@@ -1397,6 +1403,7 @@ export class HlsSessionManager {
     // realtime budget to tell a CPU limit from a download-starved input:
     // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
     this.getSourceStats = typeof getSourceStats === "function" ? getSourceStats : null;
+    this.contentionPenalties = contentionPenalties instanceof Map ? contentionPenalties : null;
     // Totals across every torrent this proxy holds, used to price what the
     // torrent itself costs the machine (item 7). Optional: a proxy wired
     // without it simply never learns that figure.
@@ -2915,6 +2922,26 @@ export class HlsSessionManager {
    * @param {string} event - One of {@link ENCODE_RUN_EVENT}.
    * @returns {string} The state now in force.
    */
+  /**
+   * How many of this proxy's encoders are running right now.
+   *
+   * Suspended runs are not counted: a process stopped by the look-ahead cap
+   * competes for nothing, and counting it would price a machine as busier than
+   * it is — the same distinction the host-load line had to learn (2026-08-15,
+   * `ffmpeg=0% system=24%` with both encoders parked).
+   *
+   * @returns {number}
+   */
+  #encodersRunningNow() {
+    let running = 0;
+    for (const session of this.sessionsById.values()) {
+      if (session.runState === ENCODE_RUN_STATE.STARTING || session.runState === ENCODE_RUN_STATE.PRODUCING) {
+        running += 1;
+      }
+    }
+    return running;
+  }
+
   #transitionRun(session, event) {
     const from = session.runState ?? INITIAL_RUN_STATE;
     const to = nextState(from, event);
@@ -3368,6 +3395,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";
@@ -6067,7 +6100,19 @@ export class HlsSessionManager {
       // 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);
+      // Two corrections, and they are different facts about the machine. The
+      // availability share removes work nobody has been charged for; the
+      // contention penalty says what OUR OWN second job costs, because the
+      // budget adds independent prices and this host does not behave that way
+      // — the same work measured 2.6× dearer beside one encoder and 3.7×
+      // beside two (2026-08-18). `concurrentBesideThis` already counts what is
+      // committed; this multiplies by how badly running at all together goes.
+      const othersRunning = concurrentBesideThis > 0 ? this.#encodersRunningNow() : 0;
+      const { penalty } = contentionPenalty(othersRunning, this.contentionPenalties);
+      const onThisMachine = correctForAvailability(
+        speed === null ? null : speed / penalty,
+        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
@@ -7589,6 +7634,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/hwaccel.js

@@ -25,6 +25,7 @@ import { mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fitDecodeCost } from "./decode-cost-fit.js";
+import { penaltiesFrom } from "./contention.js";
 import { fileURLToPath } from "node:url";
 import {
   parseFfmpegBitrateKbps,
@@ -751,6 +752,88 @@ function parseClipCharacteristics(stderr) {
  * @param {{ ffmpegBin: string, logger?: { info: (m: string) => void, warn: (m: string) => void }, clipsDir?: string }} options
  * @returns {Promise<{ pixelTerm: number, bitrateTerm: number, constantTerm: number } | null>}
  */
+/**
+ * What a second job costs on this host, measured rather than assumed.
+ *
+ * The budget adds seconds of work per second of content — this encode, plus
+ * that decode, plus what is already committed — and the addon host contradicted
+ * that directly on 2026-08-18: decoding ran at 2.10-2.25x alone, 0.79-0.90x
+ * with one encoder beside it and 0.56-0.64x with two. The same work costs 2.6×
+ * more for having company. Heat is not the cause (the hot idle machine was the
+ * fastest reading of all); four cores sharing one path to memory is.
+ *
+ * So it is measured the way everything else here is: the same clip decoded
+ * alone, then decoded again while an encoder of the same clip runs beside it.
+ * The ratio is the penalty. The encoder is stopped as soon as the reading is
+ * taken, and the whole thing costs one decode plus one short encode.
+ *
+ * @param {{ ffmpegBin: string, logger?: { info: (m: string) => void, warn: (m: string) => void }, clipsDir?: string, upTo?: number }} options
+ * @returns {Promise<Map<number, number> | null>} Penalties by how many other
+ *   jobs were running, or null when the readings could not be taken.
+ */
+export async function benchmarkContention({ ffmpegBin, logger, clipsDir = CALIBRATION_DIR, upTo = 2 }) {
+  const log = logger ?? { info: () => {}, warn: () => {} };
+  // The cheapest clip in the set: this measures the MACHINE's behaviour under
+  // company, not the clip's own cost, so the smallest one says it soonest.
+  const clip = path.join(clipsDir, "cal-h264-480-lo.mp4");
+  const startedAt = Date.now();
+  const alone = await measureDecodeSlope(ffmpegBin, clip);
+  if (!alone) {
+    log.warn("hwaccel: contention could not be measured; costs will be added as though jobs were independent");
+    return null;
+  }
+  /** @type {Array<{ others: number, speed: number }>} */
+  const beside = [];
+  /** @type {import("node:child_process").ChildProcess[]} */
+  const load = [];
+  try {
+    for (let others = 1; others <= Math.max(1, upTo); others += 1) {
+      load.push(
+        spawn(
+          ffmpegBin,
+          [
+            "-hide_banner", "-loglevel", "error", "-nostats",
+            "-stream_loop", "-1", "-i", clip,
+            "-an", "-c:v", "libx264", "-preset", "fast", "-f", "null", "-"
+          ],
+          { stdio: ["ignore", "ignore", "ignore"], windowsHide: true }
+        )
+      );
+      // Let the encoder reach its own speed before reading anything: an encode
+      // measured in its first moments is measuring the process starting.
+      await new Promise((resolve) => {
+        setTimeout(resolve, 2_000);
+      });
+      const withCompany = await measureDecodeSlope(ffmpegBin, clip);
+      if (withCompany) {
+        beside.push({ others, speed: withCompany.speed });
+      }
+    }
+  } finally {
+    for (const child of load) {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // Already gone: the reading is what mattered, and nothing else uses it.
+      }
+    }
+  }
+  const penalties = penaltiesFrom(alone.speed, beside);
+  if (!penalties) {
+    log.warn("hwaccel: contention readings said nothing; costs will be added as though jobs were independent");
+    return null;
+  }
+  log.info(
+    `hwaccel: a second job costs ${[...penalties.entries()]
+      .map(([others, penalty]) => `${penalty.toFixed(2)}x beside ${others}`)
+      .join(", ")} ` +
+    `(decode alone ${alone.speed.toFixed(2)}x, ` +
+    `${beside.map((reading) => `${reading.speed.toFixed(2)}x beside ${reading.others}`).join(", ")}, ` +
+    `measured in ${((Date.now() - startedAt) / 1000).toFixed(1)}s)`
+  );
+  return penalties;
+}
+
 export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBRATION_DIR }) {
   const log = logger ?? { info: () => {}, warn: () => {} };
   const startedAllAt = Date.now();

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/contention.test.js

@@ -0,0 +1,76 @@
+/**
+ * @file The price of a second job, with the readings it was derived from.
+ *
+ * Measured on the addon host 2026-08-18: decoding the same clip ran at 2.20x
+ * alone, 0.85x with one encoder beside it and 0.60x with two. The budget has
+ * been adding independent prices, and these say two jobs that each fit alone do
+ * not fit together.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { contentionPenalty, costWithContention, penaltiesFrom } from "../services/contention.js";
+
+/** The addon host's own readings. */
+const ALONE = 2.2;
+const BESIDE = [
+  { others: 1, speed: 0.85 },
+  { others: 2, speed: 0.6 }
+];
+
+test("the penalties are the ratios of the measured speeds", () => {
+  const penalties = penaltiesFrom(ALONE, BESIDE);
+
+  assert.ok(penalties);
+  // 2.2 / 0.85 = 2.59: the same work costs two and a half times more with one
+  // encoder beside it.
+  assert.ok(Math.abs(penalties.get(1) - 2.588) < 0.01, `${penalties.get(1)}`);
+  assert.ok(Math.abs(penalties.get(2) - 3.667) < 0.01, `${penalties.get(2)}`);
+});
+
+test("alone on the machine is what the benchmarks measure, so nothing is corrected", () => {
+  const penalties = penaltiesFrom(ALONE, BESIDE);
+  const answer = contentionPenalty(0, penalties);
+  assert.equal(answer.penalty, 1);
+  assert.equal(answer.measured, true);
+  assert.equal(costWithContention(0.45, 0, penalties), 0.45);
+});
+
+test("a cost beside one other job is the measured multiple, not the sum of two prices", () => {
+  const penalties = penaltiesFrom(ALONE, BESIDE);
+  // Decoding priced at 0.45 s/s alone becomes 1.17 s/s beside an encoder —
+  // which is what the field measured (1.18), and what additivity cannot say.
+  const corrected = costWithContention(0.45, 1, penalties);
+  assert.ok(Math.abs(corrected - 1.165) < 0.01, `${corrected}`);
+});
+
+test("beyond the readings it holds the largest instead of extrapolating", () => {
+  const penalties = penaltiesFrom(ALONE, BESIDE);
+  const four = contentionPenalty(4, penalties);
+  assert.equal(four.penalty, penalties.get(2), "two readings say nothing about a fourth job");
+  assert.equal(four.from, 2, "and the answer says which reading it came from");
+  assert.equal(four.measured, true);
+});
+
+test("with nothing measured the prediction is left alone, not guessed at", () => {
+  const answer = contentionPenalty(1, null);
+  assert.equal(answer.penalty, 1);
+  assert.equal(answer.measured, false, "the caller must be able to say the figure is uncorrected");
+  assert.equal(costWithContention(0.45, 1, null), 0.45);
+  assert.equal(contentionPenalty(1, new Map()).measured, false);
+});
+
+test("a machine that got faster for being busier has no penalty to measure", () => {
+  // Noise on a fast host, not a discovery. Measured on the developer's desktop,
+  // the difference between one and two jobs is inside the scatter.
+  const penalties = penaltiesFrom(20, [{ others: 1, speed: 21 }]);
+  assert.equal(penalties.get(1), 1);
+});
+
+test("readings that are not measurements are left out", () => {
+  assert.equal(penaltiesFrom(0, BESIDE), null, "every penalty is relative to the alone reading");
+  assert.equal(penaltiesFrom(ALONE, []), null);
+  assert.equal(penaltiesFrom(ALONE, [{ others: 0, speed: 2 }]), null, "zero others is not a penalty");
+  assert.equal(penaltiesFrom(ALONE, [{ others: 1, speed: Number.NaN }]), null);
+});

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);
-});