@torrent-tv/proxy 2.34.0 → 2.36.0

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,
@@ -156,21 +157,18 @@ const ENCODE_BENCHMARK_MAX_PLAUSIBLE_SPEED = 1000;
 const ENCODE_BENCHMARK_TIMEOUT_MS = 10_000;
 /** Progress reports arrive line by line. */
 const NEWLINE = String.fromCharCode(10);
-// Require the predicted speed to clear realtime by this much. The benchmarks
-// run at startup with an idle CPU; during playback ffmpeg competes with
-// in-process WebTorrent (download + hashing) and delivery, so real throughput
-// is lower, and the margin covers that plus complex scenes.
-//
-// It was 1.8 while the prediction counted ENCODING only and was therefore
-// several times too optimistic on a re-encode; with the decode term the
-// prediction is within ~13 % of measured, so the margin no longer has to stand
-// in for a missing term as well as for load.
-const PRESET_SPEED_MARGIN = 1.5;
-// The bar for a prediction that has NO decode term — a host whose calibration
-// clips are missing, or whose fit was rejected. That figure is the one the
-// margin was 1.8 for, and lowering it there would make an uncalibrated host
-// more permissive than it was before any of this existed.
-const ENCODE_ONLY_SPEED_MARGIN = 1.8;
+// Producing one second of video per second of clock. Not a margin and not a
+// choice — the definition of keeping up, and the bar when nothing better is
+// known about the supply this step will meet.
+const REALTIME = 1;
+// The bar where decoding CANNOT be priced — no calibration fit, or a source the
+// probe said too little about. This one is not measured and cannot be: the
+// prediction it guards counts encoding only, which on the field host was
+// several times optimistic, and there is no reading on such a host to correct
+// it with. It is left at the figure it has had since before decoding was
+// priced, because lowering it to realtime would make the least-measured hosts
+// the most permissive. Where decoding IS priced, nothing chosen remains.
+const UNPRICED_DECODE_BAR = 1.8;
 
 /**
  * @param {number} targetWidth
@@ -751,6 +749,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();
@@ -981,7 +1061,7 @@ export function predictedRealtimeSpeed({
  * The encoder figure is the FASTEST benchmarked preset: it is the best this
  * host can do, so a rung it cannot hold cannot be held at any quality setting.
  *
- * @param {{ benchmark: Array<{ preset: string, pixelsPerSec: number }>, decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, outputPixelsPerSec: number }} params
+ * @param {{ benchmark: Array<{ preset: string, pixelsPerSec: number }>, decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, outputPixelsPerSec: number, requiredSpeed?: number | null }} params
  * @returns {{ speed: number | null, sustainable: boolean }}
  */
 export function canSustainOutput({
@@ -990,7 +1070,8 @@ export function canSustainOutput({
   source = null,
   outputPixelsPerSec,
   observedDecodeCostSec = null,
-  concurrentCostSec = 0
+  concurrentCostSec = 0,
+  requiredSpeed = null
 }) {
   if (!Array.isArray(benchmark) || benchmark.length === 0) {
     // Nothing measured on this host: the budget cannot refuse what it cannot
@@ -1031,11 +1112,45 @@ export function canSustainOutput({
   if (speed === null) {
     return { speed: null, sustainable: true };
   }
-  return { speed, sustainable: speed >= PRESET_SPEED_MARGIN };
+  return { speed, sustainable: speed >= speedBar(requiredSpeed) };
+}
+
+/**
+ * The speed a step has to reach to be worth offering.
+ *
+ * Realtime is not enough on its own: a step that produces exactly one second
+ * per second never recovers the seconds lost while its reader waits for the
+ * swarm, so it survives its own supply only if what it gains between
+ * interruptions covers what one interruption costs. That is measured per file
+ * and per swarm by the reader — `1 + worst wait / median interval`, in
+ * `supply-margin.js` — and on the field torrent of 2026-08-17 it came to 1.67
+ * against the 1.5 that used to stand here, and to 4.04-8.14 on a torrent whose
+ * swarm no encoder could have kept up with.
+ *
+ * Where that figure does not exist yet — fewer than two interruptions measured
+ * — the bar is realtime. It is the one thing that can be said without
+ * measuring the swarm, and the offer is restated as soon as the reader has
+ * something to say.
+ *
+ * @param {number | null | undefined} requiredSpeed - What this file's own
+ *   interruptions demand, when they have been measured.
+ * @returns {number}
+ */
+export function speedBar(requiredSpeed) {
+  return Number.isFinite(requiredSpeed) && requiredSpeed > REALTIME ? requiredSpeed : REALTIME;
 }
 
-/** The margin a predicted speed must clear to be offered. */
-export const REALTIME_SPEED_MARGIN = PRESET_SPEED_MARGIN;
+/**
+ * The bar for a cost description — the supply's demand where decoding is
+ * priced, and never below the unpriced-decode bar where it is not.
+ *
+ * @param {{ decodeModel?: object | null, source?: object | null, observedDecodeCostSec?: number | null, requiredSpeed?: number | null }} cost
+ * @returns {number}
+ */
+function barFor(cost) {
+  const measured = speedBar(cost?.requiredSpeed);
+  return isDecodePriced(cost) ? measured : Math.max(UNPRICED_DECODE_BAR, measured);
+}
 
 /**
  * Benchmark software libx264 presets on this host. Encodes a short synthetic
@@ -1294,7 +1409,7 @@ async function decodeToRawFrames(ffmpegBin, log) {
  *
  * @param {Array<{ preset: string, pixelsPerSec: number }>} benchmark - slowest→fastest
  * @param {number} pixelsPerSecNeeded
- * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null }} [cost]
+ * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, requiredSpeed?: number | null }} [cost]
  * @returns {string}
  */
 /**
@@ -1322,8 +1437,7 @@ export function pickSoftwarePreset(benchmark, pixelsPerSecNeeded, cost = {}) {
   const observed = Number.isFinite(cost?.observedDecodeCostSec) && cost.observedDecodeCostSec > 0
     ? cost.observedDecodeCostSec
     : null;
-  const priced = isDecodePriced(cost);
-  const bar = priced ? PRESET_SPEED_MARGIN : ENCODE_ONLY_SPEED_MARGIN;
+  const bar = barFor(cost);
   // The FIRST entry that clears the bar wins — the list is in quality order, so
   // that is the best picture this host can hold. Every entry is examined rather
   // than the walk stopping at the first miss, because the measurements do not
@@ -1410,9 +1524,9 @@ export function buildResolutionLadder(ceilingWidth, ceilingHeight) {
  * Choose the software encode settings (resolution + preset) that fit the
  * realtime budget on this host. From the resolution ladder (ceiling downward),
  * pick the HIGHEST rung whose encode throughput — predicted from the startup
- * benchmark's fastest preset — clears realtime × PRESET_SPEED_MARGIN. Then, at
- * that resolution, pick the highest-quality preset that still clears the
- * margin. When even the lowest rung cannot clear it, use the lowest rung with
+ * benchmark's fastest preset — clears the speed this file's own supply
+ * demands (`speedBar`). Then, at that resolution, pick the highest-quality
+ * preset that still clears it. When even the lowest rung cannot clear it, use the lowest rung with
  * the fastest preset (best effort — a smaller picture beats sub-realtime
  * playback at full size). Returns null when no benchmark or ceiling is
  * available (the caller keeps the ceiling resolution and the default preset).
@@ -1420,7 +1534,7 @@ export function buildResolutionLadder(ceilingWidth, ceilingHeight) {
  * @param {Array<{ preset: string, pixelsPerSec: number }>} benchmark - slowest→fastest
  * @param {{ width: number, height: number }} ceiling
  * @param {number} outputFps
- * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null }} [cost]
+ * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, requiredSpeed?: number | null }} [cost]
  * @returns {{ width: number, height: number, preset: string, ladder: Array<{ width: number, height: number }>, rungIndex: number } | null}
  */
 export function chooseSoftwareEncodeSettings(benchmark, ceiling, outputFps, cost = {}) {
@@ -1433,7 +1547,7 @@ export function chooseSoftwareEncodeSettings(benchmark, ceiling, outputFps, cost
     return null;
   }
   const fastest = cheapestPresetPixelsPerSec(benchmark); // the cheapest preset's throughput
-  const bar = isDecodePriced(cost) ? PRESET_SPEED_MARGIN : ENCODE_ONLY_SPEED_MARGIN;
+  const bar = barFor(cost);
   let chosenIndex = ladder.length - 1; // default: lowest rung (best effort)
   for (let i = 0; i < ladder.length; i += 1) {
     const speed = predictedRealtimeSpeed({

package/services/learned-median.js

@@ -0,0 +1,79 @@
+/**
+ * @file Publishing a value that is learned from repeated readings.
+ *
+ * Four costs are learned this way — what a file costs to decode, what copying
+ * it costs, what a soundtrack costs, what the torrent costs per megabyte — and
+ * each has the same two decisions to make: which figure the readings amount to,
+ * and when a new figure replaces the published one.
+ *
+ * The first is the median, because one starved moment must not drag the answer.
+ *
+ * The second used to be "more than five per cent", a figure nobody measured.
+ * It is now the scatter of the readings themselves: a median that has moved
+ * further than its own readings disagree with each other has moved for a
+ * reason, and one that has not is the same answer read again. Republishing
+ * costs something real — every session recomputes its offer, on the path that
+ * serves every playlist, init and segment — so the question is worth asking,
+ * but it is answered from the measurements rather than from a constant.
+ */
+
+/**
+ * The middle of a set of readings, or null when there are none.
+ *
+ * @param {number[]} values
+ * @returns {number | null}
+ */
+export function medianOf(values) {
+  const usable = (Array.isArray(values) ? values : []).filter((value) => Number.isFinite(value));
+  if (usable.length === 0) {
+    return null;
+  }
+  const sorted = [...usable].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+}
+
+/**
+ * How far the readings sit from their own middle — the median of their
+ * distances to it.
+ *
+ * The median distance rather than the mean one, for the same reason the value
+ * itself is a median: a single disturbed reading describes the disturbance, not
+ * the host.
+ *
+ * @param {number[]} values
+ * @returns {number | null} Null when there is nothing to measure. Zero is a
+ *   real answer: readings that all agree disagree by nothing.
+ */
+export function scatterOf(values) {
+  const middle = medianOf(values);
+  if (middle === null) {
+    return null;
+  }
+  const distances = (Array.isArray(values) ? values : [])
+    .filter((value) => Number.isFinite(value))
+    .map((value) => Math.abs(value - middle));
+  return medianOf(distances);
+}
+
+/**
+ * Whether a newly computed median should replace the published one.
+ *
+ * @param {number | null} published - What every session is answering with now.
+ * @param {number} median - What the readings say today.
+ * @param {number[]} readings - The readings that median came from.
+ * @returns {boolean}
+ */
+export function movedBeyondScatter(published, median, readings) {
+  if (!Number.isFinite(median)) {
+    return false;
+  }
+  if (!Number.isFinite(published)) {
+    return true; // nothing published yet; the first answer is always news
+  }
+  const scatter = scatterOf(readings);
+  if (scatter === null) {
+    return true;
+  }
+  return Math.abs(median - published) > scatter;
+}

package/services/torrent-cost.js

@@ -0,0 +1,88 @@
+/**
+ * @file What the torrent itself costs this machine, per megabyte it moves.
+ *
+ * Downloading, verifying every piece and pushing segments down a data channel
+ * are work on the same box as the encoder, and they scale with what is moved.
+ * The reading is taken only while nothing is encoding, because that is the one
+ * moment the spending needs no arithmetic to attribute: what the process uses
+ * then is the torrent's.
+ *
+ * Except that it is not all the torrent's, and that is what this file exists
+ * for. Measured on the addon host 2026-08-18, one session reported **145.4 ms
+ * per megabyte over 8.7 MB** and **23.1 ms per megabyte over 54 MB** — the same
+ * host, the same minute, a sixfold disagreement that follows the size of the
+ * interval rather than anything about the torrent. A process with nothing to do
+ * still runs its timers, its tunnel and its session sweeps, and that draw does
+ * not shrink when fewer megabytes move: divided by a small number it swamps the
+ * answer. A minimum-megabytes threshold stood against exactly this and did not
+ * hold, because a chosen number was standing in for a measured one.
+ *
+ * The draw is measurable. An interval in which nothing encodes and the torrents
+ * move no bytes at all costs whatever this process spends anyway; subtract that
+ * from an interval which did move bytes, and what remains is the torrent's.
+ */
+
+/**
+ * The share of one core this process draws while it has nothing to do.
+ *
+ * @param {{ cpuSeconds: number, elapsedSeconds: number }} interval - CPU seconds
+ *   already divided by the number of cores, so the figure is comparable with
+ *   the wall seconds every other cost in the budget is stated in.
+ * @returns {number | null} Null when the interval cannot be divided.
+ */
+export function baseDrawFrom({ cpuSeconds, elapsedSeconds }) {
+  if (!Number.isFinite(cpuSeconds) || !Number.isFinite(elapsedSeconds) || !(elapsedSeconds > 0)) {
+    return null;
+  }
+  if (!(cpuSeconds >= 0)) {
+    return null;
+  }
+  return cpuSeconds / elapsedSeconds;
+}
+
+/**
+ * What one megabyte cost, once the draw that would have been spent anyway is
+ * taken off.
+ *
+ * The draw is subtracted, so what is left is only as certain as the draw is.
+ * The draw's own readings disagree with each other by a measured amount, and
+ * over an interval that disagreement is worth `scatter × elapsed` seconds of
+ * CPU: a reading whose remainder is smaller than that measures the wobble in
+ * the subtraction rather than the torrent. This is what the removed
+ * minimum-megabytes threshold was reaching for, arrived at from the readings
+ * instead of from a chosen size — a small interval fails it because little was
+ * moved in it, and a large one passes on the same arithmetic.
+ *
+ * @param {{ cpuSeconds: number, elapsedSeconds: number, megabytes: number, baseDraw: number | null, drawScatter?: number | null }} interval
+ * @returns {number | null} Seconds of work per megabyte, or null when this
+ *   interval cannot say — no base draw measured yet, nothing moved, or the
+ *   interval spent no more than the draw and its own uncertainty account for.
+ */
+export function costPerMegabyteFrom({ cpuSeconds, elapsedSeconds, megabytes, baseDraw, drawScatter = null }) {
+  if (!Number.isFinite(cpuSeconds) || !Number.isFinite(elapsedSeconds) || !(elapsedSeconds > 0)) {
+    return null;
+  }
+  if (!Number.isFinite(megabytes) || !(megabytes > 0)) {
+    return null;
+  }
+  if (!Number.isFinite(baseDraw) || !(baseDraw >= 0)) {
+    // Nothing measured to subtract. Publishing the whole spending as the
+    // torrent's is what produced the 145 ms/MB reading, so this interval says
+    // nothing instead.
+    return null;
+  }
+  const attributable = cpuSeconds - baseDraw * elapsedSeconds;
+  if (!(attributable > 0)) {
+    // The draw accounts for everything this interval spent. Not a discovery
+    // that the torrent is free — a reading with nothing left in it.
+    return null;
+  }
+  const uncertainty = Number.isFinite(drawScatter) && drawScatter > 0 ? drawScatter * elapsedSeconds : 0;
+  if (!(attributable > uncertainty)) {
+    // What is left is inside the disagreement between the draw's own readings.
+    // Dividing it by a small number of megabytes is how 145 ms/MB was reported
+    // on a host that costs 23.
+    return null;
+  }
+  return attributable / megabytes;
+}

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

@@ -24,7 +24,7 @@ import {
   canSustainOutput,
   decodeSpeedFor,
   predictedRealtimeSpeed,
-  REALTIME_SPEED_MARGIN
+  speedBar
 } from "../services/hwaccel.js";
 import { HlsSessionManager, sourceDecodeCharacteristics } from "../services/hls-session-manager.js";
 import { parseFfmpegBitrateKbps, parseFfmpegVideoDimensions, parseFfmpegVideoFps } from "../services/ffmpeg-banner.js";
@@ -111,7 +111,7 @@ test("with no decode fit the prediction is the encoder alone — what it was bef
   assert.equal(speed, 5.99, "the old figure, four times the truth on that rung");
 });
 
-test("a rung is refused when the combined speed is under the margin", () => {
+test("a rung is refused when the combined speed is under the bar", () => {
   // The addon host's fastest preset, read from its own log: 11.2 Mpx/s.
   const benchmark = [{ preset: "ultrafast", pixelsPerSec: 11.2e6 }];
   const source = MEASURED_FILM;
@@ -123,14 +123,10 @@ test("a rung is refused when the combined speed is under the margin", () => {
     outputPixelsPerSec: 1280 * 720 * 24
   });
   assert.equal(heavy.sustainable, false, "720p needs 22 Mpx/s from an 11.2 Mpx/s host");
-  assert.ok(heavy.speed < REALTIME_SPEED_MARGIN);
-
-  // And this is the gap the model does NOT close: the 240p rung predicts 1.58x
-  // and clears a margin of 1.5, while the field measured that same rung at
-  // 0.388-0.947x under real load — a host simultaneously copying 1080p,
-  // downloading the torrent and pushing segments. The prediction is honest for
-  // an idle machine; the margin is what has to carry the load, and 1.5 does not
-  // carry it. Pinned here so the arithmetic is not rediscovered from a log.
+  assert.ok(heavy.speed < 1, `predicted ${heavy.speed.toFixed(2)}x`);
+
+  // The 240p rung of that film predicts 1.58x on an idle machine, and with
+  // nothing known about the swarm the bar is realtime, so it is offered.
   const light = canSustainOutput({
     benchmark,
     decodeModel: ADDON_HOST_MODEL,
@@ -141,6 +137,26 @@ test("a rung is refused when the combined speed is under the margin", () => {
   assert.equal(light.sustainable, true);
 });
 
+test("the bar is what this file's own supply demands, when it has been measured", () => {
+  // The field torrent of 2026-08-17: waits of 1.49 s median arriving every
+  // 2.22 s demand 1.67x of any step that is to survive them. The same 240p rung
+  // predicted at 1.58x clears realtime and does not clear that.
+  const benchmark = [{ preset: "ultrafast", pixelsPerSec: 11.2e6 }];
+  const rung = {
+    benchmark,
+    decodeModel: ADDON_HOST_MODEL,
+    source: MEASURED_FILM,
+    outputPixelsPerSec: 426 * 240 * 24
+  };
+  assert.equal(canSustainOutput({ ...rung, requiredSpeed: 1.67 }).sustainable, false);
+  assert.equal(canSustainOutput({ ...rung, requiredSpeed: 1.2 }).sustainable, true);
+  // A swarm that has not been measured cannot raise the bar, and cannot lower
+  // it below realtime either.
+  assert.equal(speedBar(null), 1);
+  assert.equal(speedBar(0.4), 1);
+  assert.equal(speedBar(1.67), 1.67);
+});
+
 test("a reading from the running encoder outranks the model of the clips", () => {
   // The field case, 2026-08-14: the 240p rung of that film ran at 0.95x at its
   // best on a host whose fastest preset benchmarked at 11.2 Mpx/s. Subtracting
@@ -340,8 +356,24 @@ test("the master playlist drops the rungs the host cannot hold", async (t) => {
   const stronger = { ...session, id: "dddddddd-eeee-ffff-0000-111111111111", offeredHeightsCache: undefined };
   manager.sessionsById.set(stronger.id, stronger);
   const master = manager.buildMasterPlaylist(stronger.id);
-  assert.ok(master, "1080p copied plus the one rung this host can produce");
+  assert.ok(master, "1080p copied plus the rungs this host can produce");
   const heights = [...master.matchAll(/^v\/(\d+)\/index\.m3u8$/gm)].map((match) => Number(match[1]));
-  assert.deepEqual(heights, [1080, 240]);
+  assert.deepEqual(heights, [1080, 360, 240], "nothing is known about this swarm, so the bar is realtime");
   assert.deepEqual(manager.offeredHeights(stronger), heights);
+
+  // The same host, once the reader has measured what this file's supply
+  // demands: waits arriving as they did on the field torrent of 2026-08-17 ask
+  // 1.67x of any step, and the rungs that only just cleared realtime go.
+  const onAThinSwarm = {
+    ...stronger,
+    id: "eeeeeeee-ffff-0000-1111-222222222222",
+    offeredHeightsCache: undefined,
+    supplyFigures: { requiredSpeed: 1.67, worstWaitSec: 1.49, medianIntervalSec: 2.22, samples: 12 }
+  };
+  manager.sessionsById.set(onAThinSwarm.id, onAThinSwarm);
+  assert.deepEqual(
+    manager.offeredHeights(onAThinSwarm),
+    [1080],
+    "the copied height costs no encoder and stays; nothing re-encoded survives that supply"
+  );
 });

package/test/learned-median.test.js

@@ -0,0 +1,37 @@
+/**
+ * @file Adopting a new median only when it has moved further than the readings
+ * behind it disagree with each other.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { medianOf, movedBeyondScatter, scatterOf } from "../services/learned-median.js";
+
+test("the median is the middle reading, and the mean of the two middle ones", () => {
+  assert.equal(medianOf([3, 1, 2]), 2);
+  assert.equal(medianOf([1, 2, 3, 4]), 2.5);
+  assert.equal(medianOf([]), null);
+  assert.equal(medianOf([Number.NaN]), null);
+});
+
+test("the scatter is the median distance from the middle", () => {
+  assert.equal(scatterOf([10, 10, 10]), 0);
+  assert.equal(scatterOf([8, 10, 12]), 2);
+  assert.equal(scatterOf([]), null);
+});
+
+test("the first answer is always adopted", () => {
+  assert.equal(movedBeyondScatter(null, 5, [5]), true);
+});
+
+test("a move smaller than the readings' own disagreement is the same answer", () => {
+  assert.equal(movedBeyondScatter(10, 11, [8, 10, 12]), false);
+});
+
+test("a move larger than that disagreement is adopted", () => {
+  assert.equal(movedBeyondScatter(10, 13, [8, 10, 12]), true);
+});
+
+test("readings that all agree let any change through", () => {
+  assert.equal(movedBeyondScatter(10, 10.4, [10, 10, 10]), true);
+  assert.equal(movedBeyondScatter(10, 10, [10, 10, 10]), false);
+});