@torrent-tv/proxy 2.28.0 → 2.30.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.30.0
+
+- **New**: The speed a step must sustain, and the smallest buffer that hides an interruption, are now COMPUTED from the supply's own behaviour instead of being chosen by hand — printed first, used later. A step producing at `v` gains `v - 1` seconds of cushion per second and an interruption of `W` seconds costs `W`, so it survives its own supply only while `(v - 1) × T > W`, that is `v > 1 + W / T`, with `W` the worst recent wait for a piece and `T` the median interval between such waits. On the field torrent of 2026-08-17 that is **2.42x**, against the 1.5 assumed today and the 1.05 measured on the step that stalled; on the same file's copied stream it is 1.31 against 8x measured, which is why a copy never stalls. The buffer follows from the same readings: one whole segment — the one being played — plus the worst interruption that can arrive before it refills, whichever source it comes from, which was **7-9 s** where the browser waits for 25. Both figures are logged per file every half minute, so the next session says whether the arithmetic describes reality BEFORE anything is decided by it. The arithmetic is a pure module with the field session's own numbers as its tests (`services/supply-margin.js`).
+
+## 2.29.0
+
+- **New**: A piece a reader is blocked on is handed to the fastest peers that hold it. Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times in two minutes, 1.0-4.5 s each, on pieces a median of five peers already had. A block belongs to exactly one wire, so the read ends when the SLOWEST holder delivers, and `critical()` only lets the library take a block from a slow wire when its own picker happens to visit an idle one. This asks for it deliberately: when the wait starts, and again on the sampling tick that already runs while it lasts, the piece is pushed onto the three fastest unchoked holders through the library's own request entry with hotswap enabled. Nothing is duplicated — the library moves a block to a wire at least twice as fast, which bounds how often it can move at all. A refusal is counted rather than ignored (a full pipeline, or nothing reservable even with hotswap, means the piece waits on the wire and not on the picker), and a build that offers no such entry says so instead of failing silently. The wait line now reports `steered onto N of M holders`, so the next session says by number whether the tail shortened.
+
 ## 2.28.0
 
 - **Fix**: The playlist and the media agree again, and the container's keyframe table was never at fault. On a file whose first timestamp is 2.002 s, the copied picture was asked to cut at 808.808 s on the 0-based grid and cut at 806.806 s — exactly the container's start time early, because that branch keeps the source's own timestamps and re-labels the output afterwards, so a cut list stated in 0-based terms is applied 2 s away from where it means. The soundtrack, re-encoded and on the other branch, cut where it was asked. The two then wrote different values into the shared boundary table and corrected each other for the whole session (#202: 808.808 → 806.806 → 808.750 → …), the playlist drifted a whole segment from the media, and the player refetched fragments it could not place. The cut list is now stated in the source's terms on that branch, which is the same shift the seek on it already applies.

package/package.json

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

package/services/supply-margin.js

@@ -0,0 +1,159 @@
+/**
+ * @file What speed a step must run at, and how much buffer a viewer needs —
+ * both derived from the supply's own interruptions rather than chosen by hand.
+ *
+ * The two numbers this replaces were guesses. The speed margin was 1.5, and on
+ * the field session of 2026-08-17 a step admitted by it ran at 1.05x and
+ * stalled; the pre-buffer target was 25 s, which is sixteen seconds of waiting
+ * before the picture starts that nobody had shown to be necessary.
+ *
+ * Both follow from the same two measured quantities, and from nothing else:
+ *
+ *   W — how long a read waits for a piece it needs (the worst recent one);
+ *   T — how long there is between such waits (the median recent interval).
+ *
+ * **The margin.** A step producing at speed `v` gains `v - 1` seconds of
+ * cushion for every second it runs, and an interruption of `W` seconds costs
+ * `W`. It therefore survives its own supply only if what it gains between
+ * interruptions exceeds what one costs:
+ *
+ *     (v - 1) × T > W        i.e.        v > 1 + W / T
+ *
+ * On the field torrent: waits every 2.22 s, worst 3.16 s, so the honest bar is
+ * 2.42 — against the 1.5 that was assumed, and the 1.05 that was measured. The
+ * same arithmetic explains why a copied stream never stalls: at 8x it gains
+ * 15.5 s between interruptions and loses at most 4.8 s.
+ *
+ * **The buffer.** It must cover the worst interruption that can arrive before
+ * it can be refilled, whichever source that interruption comes from, plus the
+ * segment being played — which must be whole:
+ *
+ *     B = segment duration + max(W_supply, D_production, T_transfer)
+ *
+ * On the same session that is 7-9 s rather than 25. It rises by itself when a
+ * session's interruptions grow, which is what makes it safe to lower: the
+ * figure is continuously measured, not chosen once.
+ *
+ * Every quantity here is measured. Nothing in this file is a coefficient, and
+ * nothing smooths, weights or decays anything.
+ */
+
+/**
+ * One measured interruption: how long a read waited, and when the wait ended.
+ *
+ * @typedef {object} SupplyWait
+ * @property {number} waitedMs - How long the read was blocked.
+ * @property {number} at - Wall-clock ms when the wait ended.
+ */
+
+/**
+ * The speed a step must sustain to survive this file's supply on this swarm.
+ *
+ * Returns null when the evidence does not exist yet — fewer than two waits
+ * means no interval has been observed, and an interval invented from one point
+ * would be exactly the kind of number this file exists to remove. A caller with
+ * null must say it does not know, never substitute a default.
+ *
+ * @param {SupplyWait[]} waits - Recent waits, in any order.
+ * @returns {{ requiredSpeed: number, worstWaitSec: number, medianIntervalSec: number, samples: number } | null}
+ */
+export function requiredSpeedFrom(waits) {
+  const ordered = usableWaits(waits);
+  if (ordered.length < 2) {
+    return null;
+  }
+  const worstWaitSec = Math.max(...ordered.map((wait) => wait.waitedMs)) / 1000;
+  const intervals = [];
+  for (let index = 1; index < ordered.length; index += 1) {
+    const gapMs = ordered[index].at - ordered[index - 1].at;
+    if (gapMs > 0) {
+      intervals.push(gapMs / 1000);
+    }
+  }
+  if (intervals.length === 0) {
+    return null;
+  }
+  const medianIntervalSec = median(intervals);
+  if (!(medianIntervalSec > 0)) {
+    return null;
+  }
+  return {
+    requiredSpeed: 1 + worstWaitSec / medianIntervalSec,
+    worstWaitSec,
+    medianIntervalSec,
+    samples: ordered.length
+  };
+}
+
+/**
+ * The smallest buffer at which no interruption reaches the viewer.
+ *
+ * Each term is the worst OBSERVED value over a recent window, and a term with
+ * nothing observed contributes nothing rather than a guess. The segment is
+ * always included: the one being played has to be whole.
+ *
+ * @param {object} observed
+ * @param {number} observed.segmentSeconds - The session's segment duration.
+ * @param {number} [observed.worstSupplyWaitSec] - Longest wait for a piece.
+ * @param {number} [observed.worstProductionGapSec] - Longest gap between
+ *   consecutive segments beyond their own length: what a step at 1.0x costs.
+ * @param {number} [observed.worstTransferSec] - Longest time to move one
+ *   segment over the channel to the viewer.
+ * @returns {{ seconds: number, from: string } | null} Null when the segment
+ *   duration is unknown, since then nothing here can be stated.
+ */
+export function minimumBufferFrom(observed = {}) {
+  const segmentSeconds = Number(observed.segmentSeconds);
+  if (!Number.isFinite(segmentSeconds) || segmentSeconds <= 0) {
+    return null;
+  }
+  const terms = [
+    { name: "supply", seconds: positiveOrZero(observed.worstSupplyWaitSec) },
+    { name: "production", seconds: positiveOrZero(observed.worstProductionGapSec) },
+    { name: "transfer", seconds: positiveOrZero(observed.worstTransferSec) }
+  ];
+  const worst = terms.reduce(
+    (largest, term) => (term.seconds > largest.seconds ? term : largest),
+    { name: "none", seconds: 0 }
+  );
+  return {
+    seconds: segmentSeconds + worst.seconds,
+    // Which interruption sets the figure, so a session's log says what the
+    // viewer is actually waiting for rather than only how long.
+    from: worst.name
+  };
+}
+
+/**
+ * Waits that can be reasoned about, oldest first.
+ *
+ * @param {SupplyWait[]} waits
+ * @returns {SupplyWait[]}
+ */
+function usableWaits(waits) {
+  if (!Array.isArray(waits)) {
+    return [];
+  }
+  return waits
+    .filter((wait) => Number.isFinite(wait?.waitedMs) && wait.waitedMs > 0 && Number.isFinite(wait?.at))
+    .sort((left, right) => left.at - right.at);
+}
+
+/**
+ * @param {number[]} values - Non-empty.
+ * @returns {number}
+ */
+function median(values) {
+  const sorted = [...values].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];
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function positiveOrZero(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : 0;
+}

package/services/torrent-worker/fastest-wires.js

@@ -0,0 +1,121 @@
+/**
+ * @file Put the piece a reader is blocked on onto the fastest wires that hold
+ * it.
+ *
+ * Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed
+ * at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times
+ * in two minutes, 1.0-4.5 s each. So the shortage is not bandwidth. The piece
+ * that blocked had been requested from a median of five peers, and what set the
+ * tail was WHICH wire held the last outstanding block: a block is reserved for
+ * exactly one wire, and the read finishes when the slowest holder delivers.
+ *
+ * What the library already does, and what it does not: `torrent.critical()`
+ * (which the reader already sets over its window) enables HOTSWAP — an idle
+ * wire may take a block away from the SLOWEST holder. It does not duplicate:
+ * `piece.reserve()` returns -1 once every block is spoken for, and the
+ * end-game that would ask a second peer for the same block is commented out in
+ * `webtorrent/lib/torrent.js`. Hotswap therefore fires only when the library's
+ * own picker happens to visit an idle wire while our piece is critical.
+ *
+ * This asks for it on purpose, and chooses who: the wires that are unchoked,
+ * hold the piece and are measurably fastest are handed the piece through the
+ * same entry the library's picker uses, with hotswap enabled. Nothing is
+ * duplicated and no protocol rule is bent — the block moves to a faster holder
+ * instead of staying with whoever got it first.
+ */
+
+/**
+ * The library's own request entry. Internal, so its absence must be noticed
+ * rather than swallowed: without it this lever silently does nothing.
+ *
+ * @param {object} torrent
+ * @returns {boolean}
+ */
+export function canPlaceRequests(torrent) {
+  return typeof torrent?._request === "function";
+}
+
+/**
+ * Wires that could deliver this piece right now, fastest first.
+ *
+ * Excluded, each for its own reason: a wire that is choking us cannot be asked
+ * at all; one that does not hold the piece has nothing to give; a destroyed one
+ * is a corpse. Speed is the library's own measurement over its own window, so
+ * nothing here needs a history of its own.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @returns {object[]}
+ */
+export function wiresForPiece(torrent, pieceIndex) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
+  const usable = [];
+  for (const wire of wires) {
+    if (!wire || wire.destroyed || wire.peerChoking) {
+      continue;
+    }
+    if (wire.peerPieces?.get?.(pieceIndex) !== true) {
+      continue;
+    }
+    usable.push(wire);
+  }
+  return usable.sort((left, right) => speedOf(right) - speedOf(left));
+}
+
+/**
+ * A wire's measured download speed in bytes per second, or 0 when it has not
+ * been measured. Wrapped because `downloadSpeed` is a method on the wire and a
+ * throw from a destroyed one must not take the caller with it.
+ *
+ * @param {object} wire
+ * @returns {number}
+ */
+function speedOf(wire) {
+  try {
+    const speed = wire?.downloadSpeed?.();
+    return Number.isFinite(speed) ? speed : 0;
+  } catch {
+    // A wire that cannot say how fast it is ranks last, which is the honest
+    // answer — and the caller's own log line reports how many were asked.
+    return 0;
+  }
+}
+
+/**
+ * Ask the fastest holders of `pieceIndex` for it.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @param {number} [limit] - How many wires to push it onto.
+ * @returns {{ asked: number, considered: number, fastestBytesPerSecond: number }}
+ *   `asked` counts requests the library actually placed: it refuses when a
+ *   wire's pipeline is full or when nothing can be reserved even with hotswap,
+ *   and that refusal is information — a piece nobody can be asked for is
+ *   waiting on the wire, not on the picker.
+ */
+export function askFastestWiresFor(torrent, pieceIndex, limit = 3) {
+  if (!canPlaceRequests(torrent) || !Number.isInteger(pieceIndex) || pieceIndex < 0) {
+    return { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+  }
+  const candidates = wiresForPiece(torrent, pieceIndex);
+  let asked = 0;
+  for (const wire of candidates.slice(0, Math.max(1, limit))) {
+    try {
+      // `true` is hotswap: if every block is reserved, take one from the
+      // slowest holder. That is the whole point — the reader is blocked
+      // precisely because a slow holder has one.
+      if (torrent._request(wire, pieceIndex, true) === true) {
+        asked += 1;
+      }
+    } catch (error) {
+      // Internal call: report it once per attempt rather than letting the lever
+      // fail in silence.
+      throw new Error(`could not place a request for piece ${pieceIndex}: ${error?.message ?? error}`);
+    }
+  }
+  return {
+    asked,
+    considered: candidates.length,
+    fastestBytesPerSecond: candidates.length > 0 ? speedOf(candidates[0]) : 0
+  };
+}

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

@@ -22,6 +22,8 @@
 
 import { findSharedStore } from "../piece-store/shared-piece-store.js";
 import { logger } from "../../utils/logger.js";
+import { askFastestWiresFor, canPlaceRequests } from "./fastest-wires.js";
+import { minimumBufferFrom, requiredSpeedFrom } from "../supply-margin.js";
 
 /** Only waits at least this long are reported; sequential reading stays silent. */
 const PIECE_WAIT_LOG_MS = 1_000;
@@ -303,6 +305,77 @@ function whenPieceReady(torrent, index, cancellation) {
  *   the media's byte rate should size it in seconds of playback instead.
  * @returns {AsyncGenerator<PieceFragment>}
  */
+/**
+ * The last interruptions this file's readers met, newest last.
+ *
+ * Bounded and per file, because both figures derived from it describe THIS
+ * file on THIS swarm: a piece is 8 MiB here and 512 KiB elsewhere, and a swarm
+ * that answers in 200 ms today may not tomorrow. Nothing is stored beyond the
+ * process — a restart starts from no evidence, which is the honest state.
+ *
+ * @type {Map<string, Array<{ waitedMs: number, at: number }>>}
+ */
+const supplyWaits = new Map();
+
+/** How many interruptions are kept per file. */
+const SUPPLY_WAIT_HISTORY = 40;
+
+/** How often the derived figures are printed, at most. */
+const SUPPLY_REPORT_INTERVAL_MS = 30_000;
+
+/** When each file's figures were last printed. */
+const supplyReportedAt = new Map();
+
+/**
+ * Record one interruption and, at most twice a minute, say what it implies.
+ *
+ * The two figures are the whole of roadmap item 3: the speed a step must
+ * sustain to survive this supply (`1 + worst wait / median interval`), and the
+ * smallest buffer that hides an interruption from the viewer. Both are printed
+ * before either is USED, so the field says whether the arithmetic describes
+ * reality before anything is decided by it.
+ *
+ * @param {string} key - Something stable per file.
+ * @param {string} label - What to call it in the log.
+ * @param {number} waitedMs
+ * @returns {void}
+ */
+function noteSupplyWait(key, label, waitedMs) {
+  const history = supplyWaits.get(key) ?? [];
+  history.push({ waitedMs, at: Date.now() });
+  while (history.length > SUPPLY_WAIT_HISTORY) {
+    history.shift();
+  }
+  supplyWaits.set(key, history);
+
+  const now = Date.now();
+  if (now - (supplyReportedAt.get(key) ?? 0) < SUPPLY_REPORT_INTERVAL_MS) {
+    return;
+  }
+  const demand = requiredSpeedFrom(history);
+  if (!demand) {
+    return;
+  }
+  supplyReportedAt.set(key, now);
+  const buffer = minimumBufferFrom({
+    segmentSeconds: SEGMENT_SECONDS_FOR_BUFFER,
+    worstSupplyWaitSec: demand.worstWaitSec
+  });
+  logger.info(
+    `supply "${label.slice(0, 40)}": a step must run at ${demand.requiredSpeed.toFixed(2)}x ` +
+    `to survive this swarm (worst wait ${demand.worstWaitSec.toFixed(2)}s, one every ` +
+    `${demand.medianIntervalSec.toFixed(2)}s, ${demand.samples} measured) — ` +
+    `and the smallest buffer that hides it is ${buffer ? buffer.seconds.toFixed(1) : "?"}s`
+  );
+}
+
+/**
+ * The segment length the buffer figure is stated against. The reader does not
+ * know the session's own, and this is a REPORT rather than a decision — the
+ * decision, when it is made, will use the session's real one.
+ */
+const SEGMENT_SECONDS_FOR_BUFFER = 4;
+
 export async function* readFragments({
   torrent,
   fileIndex,
@@ -438,6 +511,35 @@ export async function* readFragments({
       }
 
       const waitStartedAt = Date.now();
+      // The reader is blocked, so this piece is now the only thing that matters
+      // on this torrent: hand it to the fastest wires that hold it. A block is
+      // reserved for exactly one wire, and the read ends when the slowest
+      // holder delivers — measured 2026-08-17, the swarm had a fivefold surplus
+      // of bandwidth and the reader still waited 1.0-4.5 s, 47 times in two
+      // minutes, on pieces five peers already had.
+      let pushed = { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+      const pushToFastest = () => {
+        try {
+          const result = askFastestWiresFor(torrent, pieceIndex);
+          pushed = {
+            asked: pushed.asked + result.asked,
+            considered: result.considered,
+            fastestBytesPerSecond: result.fastestBytesPerSecond
+          };
+        } catch (error) {
+          // The entry is internal to the library; if a version changes it, this
+          // lever stops working and that must be visible rather than silent.
+          logger.warn(`piece-reader: could not steer piece ${pieceIndex} — ${error?.message ?? error}`);
+        }
+      };
+      if (canPlaceRequests(torrent)) {
+        pushToFastest();
+      } else {
+        logger.warn(
+          "piece-reader: this webtorrent build offers no way to place a request; " +
+            "the blocked piece cannot be steered onto a faster peer"
+        );
+      }
       // Sampled while waiting rather than after: once the piece lands, nothing
       // is outstanding on it any more and every count reads zero.
       let supply = null;
@@ -446,6 +548,9 @@ export async function* readFragments({
         if (!supply || sample.blocks > supply.blocks) {
           supply = sample;
         }
+        // Wires come and go, and their speeds change: a holder that was slow a
+        // moment ago may now be the fastest one available.
+        pushToFastest();
       }, 500);
       try {
         await whenPieceReady(torrent, pieceIndex, cancellation);
@@ -462,6 +567,7 @@ export async function* readFragments({
       // short, an immediate hit means it is longer than it needs to be. Applied
       // before the logging below so the line reports the window the next piece
       // will actually use.
+      noteSupplyWait(`${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`, file?.name ?? "", waitedMs);
       const widened = nextWindowPieces({
         current: windowPieces,
         base: basePieces,
@@ -482,7 +588,14 @@ export async function* readFragments({
             (supply
               ? `${supply.holders}/${supply.peers} peers had it, ${supply.askedOf} were asked, ` +
                 `${supply.blocks} blocks (${Math.round((supply.blocks * 16384) / 1024)}KB) in flight at peak`
-              : "no sample taken")
+              : "no sample taken") +
+            // What WE did about it, so the next session says whether steering
+            // the piece onto faster holders shortens the tail — by number
+            // rather than by impression.
+            `; steered onto ${pushed.asked} of ${pushed.considered} holders` +
+            (pushed.fastestBytesPerSecond > 0
+              ? `, fastest ${Math.round(pushed.fastestBytesPerSecond / 1024)}KB/s`
+              : "")
         );
       }
 

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

@@ -0,0 +1,155 @@
+/**
+ * @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/fastest-wires.test.js

@@ -0,0 +1,121 @@
+/**
+ * @file Choosing who is asked for the piece a reader is blocked on.
+ *
+ * The measurement behind it (2026-08-17): a fivefold bandwidth surplus and 47
+ * blocking waits in two minutes, on pieces a median of five peers already had.
+ * A block belongs to one wire, so the read ends when the SLOWEST holder
+ * delivers — which makes "who holds it" the thing worth deciding.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { askFastestWiresFor, canPlaceRequests, wiresForPiece } from "../services/torrent-worker/fastest-wires.js";
+
+/**
+ * @param {{ speed: number, has?: boolean, choking?: boolean, destroyed?: boolean }} options
+ * @returns {object}
+ */
+function wire({ speed, has = true, choking = false, destroyed = false }) {
+  return {
+    destroyed,
+    peerChoking: choking,
+    peerPieces: { get: () => has },
+    downloadSpeed: () => speed
+  };
+}
+
+/**
+ * @param {object[]} wires
+ * @returns {{ torrent: object, asked: Array<{ speed: number, hotswap: boolean }> }}
+ */
+function torrentWith(wires, { refuse = false } = {}) {
+  /** @type {Array<{ speed: number, hotswap: boolean }>} */
+  const asked = [];
+  const torrent = {
+    wires,
+    _request(target, _index, hotswap) {
+      asked.push({ speed: target.downloadSpeed(), hotswap });
+      return !refuse;
+    }
+  };
+  return { torrent, asked };
+}
+
+test("the fastest holders are asked first", () => {
+  const { torrent, asked } = torrentWith([
+    wire({ speed: 100_000 }),
+    wire({ speed: 900_000 }),
+    wire({ speed: 400_000 })
+  ]);
+
+  const result = askFastestWiresFor(torrent, 42);
+
+  assert.deepEqual(
+    asked.map((entry) => entry.speed),
+    [900_000, 400_000, 100_000],
+    "fastest first — the read ends when the slowest holder delivers"
+  );
+  assert.equal(result.asked, 3);
+  assert.equal(result.fastestBytesPerSecond, 900_000);
+});
+
+test("hotswap is always on, because that is the whole point", () => {
+  // The reader is blocked precisely because every block is reserved and one of
+  // them sits with a slow wire. Without hotswap the library answers "nothing to
+  // reserve" and the lever does nothing at all.
+  const { torrent, asked } = torrentWith([wire({ speed: 10 })]);
+  askFastestWiresFor(torrent, 7);
+  assert.deepEqual(asked.map((entry) => entry.hotswap), [true]);
+});
+
+test("a wire that cannot deliver is not asked", () => {
+  const { torrent, asked } = torrentWith([
+    wire({ speed: 900_000, choking: true }),
+    wire({ speed: 800_000, has: false }),
+    wire({ speed: 700_000, destroyed: true }),
+    wire({ speed: 1_000 })
+  ]);
+
+  const result = askFastestWiresFor(torrent, 3);
+
+  assert.equal(asked.length, 1, "a choking, an absent and a dead wire are all unusable");
+  assert.equal(result.considered, 1);
+});
+
+test("a refusal is counted as a refusal", () => {
+  // The library refuses when a wire's pipeline is full or nothing can be
+  // reserved even with hotswap. That is information: the piece is waiting on
+  // the wire, not on the picker.
+  const { torrent } = torrentWith([wire({ speed: 500 }), wire({ speed: 400 })], { refuse: true });
+  const result = askFastestWiresFor(torrent, 11);
+  assert.equal(result.asked, 0);
+  assert.equal(result.considered, 2);
+});
+
+test("a build without the request entry is reported, not silently skipped", () => {
+  assert.equal(canPlaceRequests({ wires: [] }), false);
+  assert.equal(canPlaceRequests({ wires: [], _request: () => true }), true);
+  const result = askFastestWiresFor({ wires: [wire({ speed: 1 })] }, 1);
+  assert.deepEqual(result, { asked: 0, considered: 0, fastestBytesPerSecond: 0 });
+});
+
+test("a wire that cannot say how fast it is ranks last rather than throwing", () => {
+  const mute = wire({ speed: 0 });
+  mute.downloadSpeed = () => {
+    throw new Error("destroyed");
+  };
+  const ranked = wiresForPiece({ wires: [mute, wire({ speed: 5 })] }, 0);
+  assert.equal(ranked.length, 2);
+  assert.equal(ranked[0].downloadSpeed(), 5);
+});
+
+test("a throw from the library is raised, never swallowed", () => {
+  const torrent = {
+    wires: [wire({ speed: 1 })],
+    _request() {
+      throw new Error("internal");
+    }
+  };
+  assert.throws(() => askFastestWiresFor(torrent, 5), /could not place a request for piece 5/);
+});

package/test/supply-interruptions.test.js

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

package/test/supply-margin.test.js

@@ -0,0 +1,112 @@
+/**
+ * @file The margin and the buffer, checked against the session they were
+ * derived from.
+ *
+ * The figures in these tests are the field measurements of 2026-08-17, so a
+ * change that breaks the arithmetic fails against reality rather than against
+ * an example someone invented.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { minimumBufferFrom, requiredSpeedFrom } from "../services/supply-margin.js";
+
+/**
+ * Waits spaced by `intervalSec`, each lasting `waitSec`.
+ *
+ * @param {number} count
+ * @param {number} intervalSec
+ * @param {number} waitSec
+ * @returns {Array<{ waitedMs: number, at: number }>}
+ */
+function evenlySpaced(count, intervalSec, waitSec) {
+  const waits = [];
+  for (let index = 0; index < count; index += 1) {
+    waits.push({ waitedMs: waitSec * 1000, at: 1_000_000 + index * intervalSec * 1000 });
+  }
+  return waits;
+}
+
+test("the margin is what the supply's own interruptions demand", () => {
+  // The field torrent: a wait every 2.22 s, the worst of them 3.16 s.
+  const waits = evenlySpaced(10, 2.22, 1.49);
+  waits[4].waitedMs = 3160;
+
+  const answer = requiredSpeedFrom(waits);
+
+  assert.ok(answer);
+  assert.equal(answer.worstWaitSec, 3.16);
+  assert.equal(answer.medianIntervalSec, 2.22);
+  // 1 + 3.16 / 2.22 = 2.42. The step that was admitted by the hand-chosen 1.5
+  // ran at 1.05x and stalled; this is the bar it should have been held to.
+  assert.ok(Math.abs(answer.requiredSpeed - 2.4234) < 0.001, `got ${answer.requiredSpeed}`);
+});
+
+test("a copy at 8x clears its own supply with room to spare", () => {
+  // The same file's copied stream: waits up to 4.82 s, and it never stalled.
+  const waits = evenlySpaced(6, 15.5, 4.82);
+  const answer = requiredSpeedFrom(waits);
+  assert.ok(answer);
+  // 1 + 4.82/15.5 = 1.31, against 8x measured. Which is why a copy is the step
+  // a stranded viewer is always able to return to.
+  assert.ok(answer.requiredSpeed < 1.35, `got ${answer.requiredSpeed}`);
+});
+
+test("with too little evidence it says so instead of inventing a number", () => {
+  assert.equal(requiredSpeedFrom([]), null);
+  assert.equal(requiredSpeedFrom([{ waitedMs: 1500, at: 1 }]), null, "one wait shows no interval");
+  assert.equal(requiredSpeedFrom(null), null);
+  // Every wait at the same instant: no interval was observed, so no interval
+  // may be stated.
+  assert.equal(
+    requiredSpeedFrom([
+      { waitedMs: 1000, at: 5 },
+      { waitedMs: 1000, at: 5 }
+    ]),
+    null
+  );
+});
+
+test("readings that are not measurements are ignored, not averaged in", () => {
+  const answer = requiredSpeedFrom([
+    { waitedMs: 0, at: 1000 },
+    { waitedMs: Number.NaN, at: 2000 },
+    { waitedMs: 1000, at: 3000 },
+    { waitedMs: 2000, at: 5000 },
+    { waitedMs: 1500, at: 7000 }
+  ]);
+  assert.ok(answer);
+  assert.equal(answer.samples, 3, "only the three real waits count");
+});
+
+test("the buffer is one segment plus the worst interruption, and names which", () => {
+  const answer = minimumBufferFrom({
+    segmentSeconds: 4,
+    worstSupplyWaitSec: 3.16,
+    worstProductionGapSec: 1.2,
+    worstTransferSec: 0.066
+  });
+  assert.ok(answer);
+  assert.equal(answer.seconds, 7.16, "7.16 s against the 25 s that was chosen by hand");
+  assert.equal(answer.from, "supply");
+});
+
+test("a step that cannot keep up sets the buffer itself", () => {
+  const answer = minimumBufferFrom({
+    segmentSeconds: 4,
+    worstSupplyWaitSec: 1.4,
+    worstProductionGapSec: 6.5,
+    worstTransferSec: 0.05
+  });
+  assert.equal(answer.seconds, 10.5);
+  assert.equal(answer.from, "production", "the encoder, not the swarm, is what the viewer is waiting for");
+});
+
+test("a term with nothing observed contributes nothing", () => {
+  const answer = minimumBufferFrom({ segmentSeconds: 4 });
+  assert.equal(answer.seconds, 4, "one whole segment is the floor: the one being played");
+  assert.equal(answer.from, "none");
+  assert.equal(minimumBufferFrom({}), null, "without a segment duration nothing can be said");
+  assert.equal(minimumBufferFrom({ segmentSeconds: 0 }), null);
+});