@torrent-tv/proxy 2.35.0 → 2.36.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.36.1
+
+- **Fix**: The cut list of a copied picture is built from the picture's own keyframes, and no longer from every entry in the container's table. A Matroska CuePoint belongs to the track named inside it, and RFC 9559 leaves the muxer free to index whichever tracks it likes — both field files index their subtitles as well. Measured over the swarm on 2026-08-18, reading only the head and the table: `Minions.and.Monsters.1080p.mkv` has **2778 video entries, one every 2.002 s, and 4669 more across four subtitle tracks**; `Moana.2.2024.720p.BluRay … MegaPeer.mkv` has **1055 video entries and 5007 across five**. Read without the track, the extra times entered the cut list as though they were keyframes; ffmpeg can only cut a copied picture at a real keyframe at or after the time it is given, so each such cut landed at the next one instead — which is exactly the disagreement the field measured, and why it was always positive: 2.002 s on the first file (its own keyframe spacing), a median of 6.3 s and a worst case of 21 s on the second. The reader now takes the first video track's number from Tracks — already inside the head it fetches, with one short extra read only for a file that keeps Tracks elsewhere — and keeps the entries of that track. Nothing else about the two-read approach changes, and a session costs nothing more. With the fix the same two files read 2778 and 1055 times, all of them keyframes. When the filter leaves NOTHING — a table whose entries name a track number Tracks never declares — the unfiltered table is used rather than no table: that case is this reader failing to recognise the file, and answering with nothing would put an even grid on a copied picture, which is the failure it exists to prevent.
+- **Chore**: `scripts/read-container-index.mjs` reads the index of any `.torrent` over the swarm — two short ranged reads, in memory, no file written — so a claim about what a container says can be checked against a real film in seconds. Written after the measurement above was made by hand three times.
+
+## 2.36.0
+
+- **New**: The torrent is charged for the megabytes it is measured to be moving, and the price it is charged at no longer contains work that is not the torrent's. Two faults, both visible in one field log from the addon host (2026-08-18): the same session reported **145.4 ms of CPU per MB over 8.7 MB and 23.1 ms per MB over 54 MB**, a sixfold disagreement that followed the size of the interval rather than anything about the torrent — because 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. 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 now measured directly, in the intervals where nothing encodes and not one byte moves, and subtracted before the rest is called the torrent's (`services/torrent-cost.js`). What the threshold was reaching for is arrived at from the readings instead: the draw's own readings disagree by a measured amount, that disagreement is worth `scatter × elapsed` seconds over an interval, and a remainder smaller than it measures the wobble in the subtraction rather than the torrent — so a small interval fails on the same arithmetic that lets a large one through, with no size chosen anywhere. The second fault: the price was then charged against the file's own byte rate — what the viewer consumes — so a fully downloaded file moving nothing still paid, and a file being fetched ahead of the viewer, which is how every session starts, paid too little. It is charged against the rate the torrent is measured to be moving, sampled every five seconds per watched torrent and divided among the files of it being read, so two episodes of one pack do not each pay for the whole download.
+- **New**: No separate penalty for downloading, because the measurement says none is needed. The readings of 2026-08-18 have decoding at 10.1-11.2x with nothing running and 6.45-6.71x while the torrent pulled 1.8 MB/s — an extra 0.050-0.066 seconds of work per second of content, which is **28-37 ms per megabyte moved**, against the 20-35 ms/MB the host measures for itself. The download's effect on other work is the processor time it consumes, and that is already priced; unlike a second encoder, which costs 2.71× and is not explained by any sum. So this closes roadmap item 6 with a subtraction rather than another multiplier.
+- **New**: A quality step is judged against the speed this file's own supply demands, not against a chosen margin. `1.5` (and `1.8` where decoding had no price) stood for "faster than realtime by enough", and what "enough" means is measured per file and per swarm by the reader that waits for the pieces: `1 + worst wait / median interval`, which the proxy has been printing since 2.30.0 without using. On the field torrent of 2026-08-17 that is 1.67, and on the 720p rip of the same evening 4.04-8.14 — a torrent on which no re-encoded step could have kept up, and which a fixed 1.5 admitted. Where the swarm has not been measured yet — fewer than two interruptions — the bar is realtime, which is the one thing that can be said without measuring it, and the offer is restated as soon as the reader has something to say. The refusal line names the figure it refused against and where it came from. One chosen number survives, and only where nothing can be measured: a host whose calibration produced no decode term at all is judged on an encode-only prediction that was several times optimistic in the field, and its bar stays at the 1.8 it has had since before decoding was priced, because lowering it to realtime would make the least-measured hosts the most permissive.
+- **Chore**: Two learning thresholds removed, both of which were chosen numbers standing in for measurements. A reading of an encoder's speed is no longer withheld for the first twenty seconds of a run: each sample now carries the serial of the run it was taken from and a pair whose serials differ is discarded, which is what the wait stood in for — a restart spends up to a second and a half making its directory and burying its predecessor, and a sample taken in that window carries the old run's position, so paired with the new one it reads a twenty-minute seek as twenty minutes produced in five seconds. The wait cost every reading a short run could have given, which is how a rung spent three minutes below realtime teaching nothing (2026-08-15); the serial costs none. And a new median is adopted when it has moved further than the readings behind it disagree with each other, instead of by more than five per cent (`services/learned-median.js`). What remains chosen is the length of the history a median is taken over, and it is now written down as such rather than given a measured-sounding reason.
+
 ## 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.

package/package.json

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

package/scripts/read-container-index.mjs

@@ -0,0 +1,108 @@
+/**
+ * @file What this proxy would cut a file at, read from a real torrent.
+ *
+ * The keyframe readers take two short ranged reads, so the index of a 7 GB film
+ * can be examined over the swarm in seconds without downloading it. Run against
+ * a `.torrent` file to see what the container's own table says, per track, and
+ * what the reader hands to the cut list.
+ *
+ *   node scripts/read-container-index.mjs path/to/film.torrent [more.torrent …]
+ *
+ * Developer tool: nothing here runs in a session, and no viewer is involved.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import MemoryChunkStore from "memory-chunk-store";
+import WebTorrent from "webtorrent";
+import { readMatroskaKeyframeTimes } from "../services/container-index/matroska.js";
+import { readMp4KeyframeTimes } from "../services/container-index/mp4.js";
+import { readAviKeyframeTimes } from "../services/container-index/avi.js";
+
+const torrents = process.argv.slice(2);
+if (torrents.length === 0) {
+  console.error("usage: node scripts/read-container-index.mjs <file.torrent> [...]");
+  process.exit(1);
+}
+
+/**
+ * Collect one byte range of a torrent file.
+ *
+ * @param {import("webtorrent").TorrentFile} file
+ * @param {number} start
+ * @param {number} end - Inclusive.
+ * @returns {Promise<Buffer>}
+ */
+function readRangeOf(file, start, end) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const stream = file.createReadStream({ start, end });
+    stream.on("data", (chunk) => chunks.push(chunk));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+
+/**
+ * Say what a set of times looks like: how many, where it starts, how far apart.
+ *
+ * @param {string} label
+ * @param {number[] | null} times
+ * @returns {void}
+ */
+function describe(label, times) {
+  if (!times || times.length === 0) {
+    console.log(`${label}: no index`);
+    return;
+  }
+  const gaps = times.slice(1).map((time, index) => time - times[index]).sort((left, right) => left - right);
+  const median = gaps.length > 0 ? gaps[Math.floor(gaps.length / 2)] : 0;
+  console.log(
+    `${label}: ${times.length} times, first ${times.slice(0, 4).map((time) => time.toFixed(3)).join(" ")}, ` +
+    `median gap ${median.toFixed(3)}s, last ${times[times.length - 1].toFixed(3)}`
+  );
+}
+
+for (const torrentPath of torrents) {
+  // uTP is off: binding its socket needs a permission this does not have on
+  // every developer machine, and TCP peers are enough to read an index.
+  const client = new WebTorrent({ utp: false });
+  console.log(`\n=== ${path.basename(torrentPath)} ===`);
+  await new Promise((resolve) => {
+    // In memory, deliberately. The file store creates the whole file on disk at
+    // its full length before a byte of it is wanted — reading the index of four
+    // films that way filled 34 GB and then failed with the disk full. Only two
+    // short ranges are ever read here, so they can simply be held.
+    client.add(fs.readFileSync(torrentPath), { store: MemoryChunkStore }, async (torrent) => {
+      try {
+        // Nothing is wanted up front; the ranged reads below select what they need.
+        torrent.deselect(0, torrent.pieces.length - 1, 0);
+        const file = torrent.files
+          .filter((candidate) => /\.(mkv|mp4|avi)$/i.test(candidate.name))
+          .sort((left, right) => right.length - left.length)[0];
+        if (!file) {
+          console.log("no video file in this torrent");
+          return resolve();
+        }
+        console.log(`file: ${file.name} (${(file.length / 1e9).toFixed(2)} GB)`);
+        const readRange = async (start, end) => {
+          const last = Math.min(end, file.length - 1);
+          return start > last ? null : readRangeOf(file, start, last);
+        };
+        if (/\.mkv$/i.test(file.name)) {
+          describe("matroska", await readMatroskaKeyframeTimes(readRange, file.length));
+        } else if (/\.mp4$/i.test(file.name)) {
+          describe("mp4", await readMp4KeyframeTimes(readRange, file.length));
+        } else {
+          describe("avi", await readAviKeyframeTimes(readRange, file.length));
+        }
+      } catch (error) {
+        console.log(`failed: ${error?.message ?? error}`);
+      } finally {
+        resolve();
+      }
+    });
+  });
+  await new Promise((done) => client.destroy(done));
+}
+process.exit(0);

package/services/container-index/matroska.js

@@ -28,6 +28,14 @@ const ID_TIMESTAMP_SCALE = 0x2ad7b1;
 const ID_CUES = 0x1c53bb6b;
 const ID_CUE_POINT = 0xbb;
 const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+// TrackType 1 is video; 2 is audio, 17 subtitles, and the rest are rarer still.
+const TRACK_TYPE_VIDEO = 1;
 
 // How much of the file start to read. Must cover the EBML header, the SeekHead
 // and Info; 64 KB is generous for every real muxer (the file measured needed
@@ -36,6 +44,10 @@ const HEAD_BYTES = 64 * 1024;
 // Cap on the Cues read. A two-hour film indexes to tens of KB; anything beyond
 // this is not a normal index and not worth pulling over a torrent.
 const MAX_CUES_BYTES = 8 * 1024 * 1024;
+// Cap on a Tracks read, for the rare file whose Tracks element sits outside the
+// head window. Track entries are small, so a file with dozens of them still
+// fits well inside this.
+const MAX_TRACKS_BYTES = 1024 * 1024;
 // Matroska's default timestamp scale (nanoseconds per tick) when Info omits it.
 const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
 
@@ -121,13 +133,64 @@ function readTimestampScale(head, segmentDataOffset) {
 }
 
 /**
- * Cue times (seconds, ascending) from a Cues payload.
+ * The number of the first video track, from a Tracks payload.
+ *
+ * The FIRST one, because that is the track ffmpeg is told to copy (`0:v:0`).
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, size: number }} tracks
+ * @returns {number | null}
+ */
+function readVideoTrackNumber(buffer, tracks) {
+  const tracksEnd = Math.min(buffer.length, tracks.dataOffset + tracks.size);
+  for (const entry of iterateElements(buffer, tracks.dataOffset, tracksEnd)) {
+    if (entry.id !== ID_TRACK_ENTRY) {
+      continue;
+    }
+    const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
+    let number = null;
+    let type = null;
+    for (const field of iterateElements(buffer, entry.dataOffset, entryEnd)) {
+      if (field.id === ID_TRACK_NUMBER) {
+        number = readUint(buffer, field.dataOffset, field.size);
+      } else if (field.id === ID_TRACK_TYPE) {
+        type = readUint(buffer, field.dataOffset, field.size);
+      }
+    }
+    if (number !== null && type === TRACK_TYPE_VIDEO) {
+      return number;
+    }
+  }
+  return null;
+}
+
+/**
+ * Cue times (seconds, ascending) of ONE track, from a Cues payload.
+ *
+ * The track is the whole point, and leaving it out is what this reader got
+ * wrong until 2026-08-18. A CuePoint belongs to the track named inside its
+ * CueTrackPositions, and a muxer indexes whatever tracks it likes: RFC 9559
+ * says each keyframe of a video track SHOULD be referenced, and that the Cues
+ * Element "can be used to index every single timestamp of every Block or they
+ * can be indexed selectively". Both field files index their SUBTITLE tracks as
+ * well — `Minions.and.Monsters.1080p.mkv` has 2778 video entries every 2.002 s
+ * plus 4669 across four subtitle tracks; `Moana.2 … MegaPeer.mkv` has 1055
+ * video entries plus 5007 across five.
+ *
+ * Read without the track, those extra times enter the cut list as though they
+ * were keyframes. ffmpeg can only cut a COPIED picture at a real keyframe at or
+ * after the time it is given, so every cut asked for at one of them lands late
+ * — which is exactly what the field measured: on the first file every deviation
+ * was 2.002 s, that file's own keyframe spacing, and on the second the median
+ * was 6.3 s with a worst case of 21 s. Never once negative.
  *
  * @param {Buffer} cues
  * @param {number} timestampScale - Nanoseconds per tick.
+ * @param {number | null} trackNumber - Null keeps every entry, which is right
+ *   only for a file that indexes one track.
  * @returns {number[]}
  */
-function readCueTimes(cues, timestampScale) {
+function readCueTimes(cues, timestampScale, trackNumber) {
   const times = [];
   const secondsPerTick = timestampScale / 1e9;
   for (const point of iterateElements(cues)) {
@@ -135,11 +198,26 @@ function readCueTimes(cues, timestampScale) {
       continue;
     }
     const pointEnd = Math.min(cues.length, point.dataOffset + point.size);
+    let time = null;
+    let belongsToTrack = trackNumber === null;
     for (const field of iterateElements(cues, point.dataOffset, pointEnd)) {
       if (field.id === ID_CUE_TIME) {
-        times.push(readUint(cues, field.dataOffset, field.size) * secondsPerTick);
-        break;
+        time = readUint(cues, field.dataOffset, field.size) * secondsPerTick;
+        continue;
+      }
+      if (field.id !== ID_CUE_TRACK_POSITIONS || belongsToTrack) {
+        continue;
       }
+      const positionsEnd = Math.min(pointEnd, field.dataOffset + field.size);
+      for (const inner of iterateElements(cues, field.dataOffset, positionsEnd)) {
+        if (inner.id === ID_CUE_TRACK && readUint(cues, inner.dataOffset, inner.size) === trackNumber) {
+          belongsToTrack = true;
+          break;
+        }
+      }
+    }
+    if (time !== null && belongsToTrack) {
+      times.push(time);
     }
   }
   times.sort((left, right) => left - right);
@@ -195,6 +273,64 @@ export async function readMatroskaKeyframeTimes(readRange, fileSize) {
   const payloadEnd = Math.min(cuesChunk.length, cuesElement.dataOffset + cuesElement.size);
   const payload = cuesChunk.subarray(cuesElement.dataOffset, payloadEnd);
 
-  const times = readCueTimes(payload, readTimestampScale(head, seekHead.segmentDataOffset));
-  return times.length > 0 ? times : null;
+  // Whose entries to keep. Tracks sits near the head and is normally inside the
+  // bytes already fetched; when it is not, SeekHead says where it is and one
+  // more short read gets it. Nothing is fetched twice and nothing is scanned.
+  const videoTrack = await readVideoTrack(readRange, head, seekHead, fileSize);
+  const timestampScale = readTimestampScale(head, seekHead.segmentDataOffset);
+  const times = readCueTimes(payload, timestampScale, videoTrack);
+  if (times.length > 0) {
+    return times;
+  }
+  if (videoTrack === null) {
+    return null;
+  }
+  // The filter left nothing, and that is not an answer about the file: a table
+  // exists, and this reader simply failed to recognise which of its entries
+  // belong to the picture — a track numbered one way in Tracks and another in
+  // the cue points, or an entry with no CueTrack at all. Returning null here
+  // would put an EVEN grid on a copied picture, which is the failure this
+  // module exists to prevent, so the unfiltered table is used instead: less
+  // exact than the picture's own keyframes, better than a grid that has nothing
+  // to do with the file.
+  const unfiltered = readCueTimes(payload, timestampScale, null);
+  return unfiltered.length > 0 ? unfiltered : null;
+}
+
+/**
+ * The video track's number — from the head when it is there, and from one extra
+ * short read when it is not.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {Buffer} head
+ * @param {{ segmentDataOffset: number, entries: Map<number, number> }} seekHead
+ * @param {number} fileSize
+ * @returns {Promise<number | null>} Null when Tracks cannot be read at all, and
+ *   then every cue entry is kept — right for a file that indexes only its
+ *   picture, wrong for one that does not, and nothing here can tell them apart.
+ *   Refusing the index instead would put an even grid on a copied picture,
+ *   which is the failure this reader exists to prevent.
+ */
+async function readVideoTrack(readRange, head, seekHead, fileSize) {
+  const inHead = findElement(head, ID_TRACKS, [], seekHead.segmentDataOffset);
+  if (inHead && inHead.dataOffset + inHead.size <= head.length) {
+    return readVideoTrackNumber(head, inHead);
+  }
+  const relative = seekHead.entries.get(ID_TRACKS);
+  if (relative === undefined) {
+    return null;
+  }
+  const offset = seekHead.segmentDataOffset + relative;
+  if (!Number.isFinite(offset) || offset <= 0 || offset >= fileSize) {
+    return null;
+  }
+  const chunk = await readRange(offset, Math.min(fileSize - 1, offset + MAX_TRACKS_BYTES));
+  if (!chunk || chunk.length === 0) {
+    return null;
+  }
+  const element = [...iterateElements(chunk, 0, chunk.length)][0];
+  if (!element || element.id !== ID_TRACKS) {
+    return null;
+  }
+  return readVideoTrackNumber(chunk, { dataOffset: element.dataOffset, size: element.size });
 }

package/services/contention.js

@@ -1,128 +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;
-}
+/**
+ * @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;
+}