@torrent-tv/proxy 2.29.0 → 2.30.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.29.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/piece-reader.js

@@ -23,6 +23,7 @@
 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;
@@ -304,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,
@@ -495,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,

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