@torrent-tv/proxy 2.29.0 → 2.30.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.30.1
+
+- **Fix**: A seek was undone a second after it was made. Measured 2026-08-17: the viewer jumped to 2083.4 s, both runs restarted at segment #373 — correctly — and then a request for #371, issued by the player BEFORE the jump and reissued a second later, dragged the encoder back to #370. The viewer sat at #374 waiting for it to return. Two things let that happen, and both are fixed. The behind-head repair refuses a request that is behind the position the VIEWER themselves reported: its existing guard only holds while a seek is still settling, which by then it was not. And a segment request may no longer move the recorded viewer position BACKWARDS past a reported seek — playback only ever moves forward from one, so nothing legitimate is lost, while a stale request can no longer rewrite the viewer's own statement, which is how the repair came to believe it. A reported seek is the viewer stating where they are; a request is evidence about where the player is reading, and evidence may refine a statement forward, never contradict it backwards. Pinned by `test/stale-request-after-seek.test.js`, whose control case shows the same traffic still repairing a genuinely misplaced run when the viewer has said nothing.
+
+## 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.1",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/hls-session-manager.js

@@ -4263,6 +4263,26 @@ export class HlsSessionManager {
     if (session.seekSettleTimer != null) {
       return;
     }
+    // And it outranks it AFTERWARDS too, which is what was missing. The guard
+    // above only holds while the settle timer is armed — a second later it is
+    // gone, and a request the browser issued BEFORE the seek is then treated as
+    // fresh evidence. Field 2026-08-17: a seek to 2083.4 s put both runs at
+    // #373, a request for #371 from before it arrived a second afterwards, and
+    // this repair moved the encoder to #370 — three segments behind the viewer,
+    // who waited for it to come back. A request BEHIND what the viewer
+    // themselves reported cannot be describing where they are.
+    const reportedSeconds = Number(session.viewerReportedSeconds);
+    if (Number.isFinite(reportedSeconds)) {
+      const reportedIndex = this.#segmentIndexForTime(session, reportedSeconds);
+      if (index < reportedIndex) {
+        this.#explainHold(
+          session,
+          session.segmentFormat.segmentFileName(index),
+          `it is behind #${reportedIndex}, where the viewer said they are — answered, not obeyed`
+        );
+        return;
+      }
+    }
     // What separates a request the viewer is waiting for from the player
     // scanning the playlist is not TIME but what else it is asking for. On a
     // seek hls.js fires dozens of DIFFERENT indices within half a second (field
@@ -4370,6 +4390,14 @@ export class HlsSessionManager {
     // The browser holds one session id for the whole file and knows nothing of
     // variants, so a seek it reports means the stream on screen.
     named.viewerPositionSeconds = positionSeconds;
+    // What the viewer SAID, kept apart from what requests imply. A request is
+    // evidence about where the player is reading; a reported seek is the viewer
+    // stating where they are, and after one, requests already in flight
+    // describe a place that no longer exists. Field 2026-08-17: a seek to
+    // 2083.4 s restarted both runs at #373, a request for #371 issued before it
+    // arrived a second later, and the encoder was dragged back to #370 — three
+    // segments behind the viewer, who then waited for it to return.
+    named.viewerReportedSeconds = positionSeconds;
     named.lastAccessedAt = Date.now();
     // The audio the viewer is listening to moves with them. It is a separate
     // encoder on a separate session that the browser cannot name, and nothing
@@ -4415,6 +4443,7 @@ export class HlsSessionManager {
       return false;
     }
     session.viewerPositionSeconds = positionSeconds;
+    session.viewerReportedSeconds = positionSeconds;
     session.lastAccessedAt = Date.now();
     // Every segment request being held right now was made for the position the
     // viewer has just left. Release them: hls.js keeps ONE fragment load
@@ -7021,7 +7050,16 @@ export class HlsSessionManager {
         // read when a quality change has to place the next variant's first
         // encode run. The freshest evidence wins: a seek overwrites this, and
         // the first request after the seek overwrites it back.
-        session.viewerPositionSeconds = this.#segmentStartTime(session, requested);
+        // A request refines this only FORWARD of what the viewer reported.
+        // Playback always moves forward from a seek, so nothing legitimate is
+        // lost — while a stale request from before the seek can no longer
+        // rewrite the viewer's own statement, which is what let the repair
+        // below drag the encoder backwards.
+        const requestedStart = this.#segmentStartTime(session, requested);
+        const reported = Number(session.viewerReportedSeconds);
+        if (!Number.isFinite(reported) || requestedStart >= reported) {
+          session.viewerPositionSeconds = requestedStart;
+        }
         // A viewer who has caught up must not wait out the monitor's interval —
         // but only if they HAVE caught up, which is why this re-evaluates the
         // same condition instead of resuming outright.

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/stale-request-after-seek.test.js

@@ -0,0 +1,183 @@
+/**
+ * @file A request issued before a seek must not steer the encoder.
+ *
+ * Field 2026-08-17: the viewer seeked to 2083.4 s, both runs restarted at
+ * segment #373, and a request for #371 — issued before the seek and reissued by
+ * the player a second later — moved the encoder to #370. The viewer was at
+ * #374 and waited for the encoder to come back to them.
+ *
+ * The rule pinned here: a reported seek is the viewer STATING where they are; a
+ * segment request is evidence about where the player is reading. Evidence may
+ * refine a statement forward, never contradict it backwards.
+ *
+ * Both cases go through `getFileStream`, the way production reaches the repair,
+ * and the second is the control: without a reported seek the very same traffic
+ * DOES move the encoder, which is what makes the first case a measurement of
+ * the guard rather than of the weather.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { ENCODE_RUN_STATE } from "../services/encode-run-state.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const SEGMENT_SECONDS = 4;
+const RUN_STARTS_AT = 373;
+const BEHIND_INDEX = 371;
+const SESSION_ID = "22222222-3333-4444-5555-666666666666";
+
+/**
+ * A live session whose run begins at #373 and whose directory is empty, so any
+ * segment request is a request for something not yet produced.
+ *
+ * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string }>}
+ */
+async function sessionWithRunAt373() {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "stale-seek-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const boundaries = [];
+  for (let index = 0; index <= 600; index += 1) {
+    boundaries.push(index * SEGMENT_SECONDS);
+  }
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    runState: ENCODE_RUN_STATE.PRODUCING,
+    fileName: "film.mkv",
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    consumers: new Set(),
+    segmentFormat: fmp4Format,
+    usesExplicitCuts: true,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentBoundaries: boundaries,
+    segmentCount: boundaries.length - 1,
+    encodeStartIndex: RUN_STARTS_AT,
+    // A live process: the repair refuses outright when nothing is encoding.
+    ffmpeg: { pid: 1234, killed: false, exitCode: null, signalCode: null, kill() { this.killed = true; } },
+    encodeRunGeneration: 0,
+    runSerial: 1,
+    behindHeadAsks: new Map(),
+    firstWantedAt: new Map(),
+    holdExplainedAt: new Map(),
+    seekSettleTimer: null,
+    seekTarget: null,
+    seekFailureTarget: -1,
+    seekFailureCount: 0,
+    waitEpoch: 0,
+    firstSegmentLogged: true,
+    progress: { processedSeconds: RUN_STARTS_AT * SEGMENT_SECONDS, speed: "1.0x", startPositionSeconds: RUN_STARTS_AT * SEGMENT_SECONDS }
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  return { manager, session, dirPath };
+}
+
+/**
+ * The traffic that dragged the encoder back: the same index asked for twice,
+ * first wanted long enough ago to pass the repair's patience guard.
+ *
+ * @param {object} session
+ */
+function askedTwiceLongEnough(session) {
+  session.firstWantedAt.set(BEHIND_INDEX, Date.now() - 5_000);
+  session.behindHeadAsks.set(BEHIND_INDEX, { count: 3, at: Date.now() });
+}
+
+/**
+ * Put the session down without going through disposal.
+ *
+ * Disposal signals the encoder and waits for it to die, which a stub cannot do
+ * — and none of that is what these tests are about. Clearing the map and any
+ * armed timer leaves nothing running.
+ *
+ * @param {HlsSessionManager} manager
+ * @param {object} session
+ * @param {string} dirPath
+ * @returns {Promise<void>}
+ */
+async function tidy(manager, session, dirPath) {
+  if (session.seekSettleTimer) {
+    clearTimeout(session.seekSettleTimer);
+    session.seekSettleTimer = null;
+  }
+  manager.sessionsById.clear();
+  manager.stop?.();
+  await rm(dirPath, { recursive: true, force: true });
+}
+
+test("a request behind where the viewer said they are does not move the encoder", async (t) => {
+  const { manager, session, dirPath } = await sessionWithRunAt373();
+  t.after(async () => {
+    await tidy(manager, session, dirPath);
+  });
+
+  // The viewer stated their position: 2083.4 s, which is segment #520 here.
+  manager.requestSeek(SESSION_ID, 2083.4);
+  session.encodeStartIndex = RUN_STARTS_AT;
+  askedTwiceLongEnough(session);
+
+  const answer = await manager.getFileStream(
+    SESSION_ID,
+    fmp4Format.segmentFileName(BEHIND_INDEX),
+    { requestSeq: 1 }
+  );
+
+  assert.equal(answer.kind, "warming-up", "the request is answered, not obeyed");
+  // The viewer's own seek legitimately armed a move to #519. What must NOT
+  // happen is the stale request replacing that with #370 — which is exactly
+  // what the field log shows: `seek settle → restart at segment #370`.
+  assert.notEqual(
+    session.seekTarget,
+    BEHIND_INDEX - 1,
+    "a request behind the viewer must not become the encoder's destination"
+  );
+  assert.equal(session.seekTarget, 519, "the viewer's own seek is what the encoder is going to");
+});
+
+test("the same traffic DOES move the encoder when the viewer has said nothing", async (t) => {
+  const { manager, session, dirPath } = await sessionWithRunAt373();
+  t.after(async () => {
+    await tidy(manager, session, dirPath);
+  });
+
+  // No reported seek: a run placed wrongly is exactly what the repair is for,
+  // and this is the case it must keep serving.
+  askedTwiceLongEnough(session);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(BEHIND_INDEX), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    BEHIND_INDEX - 1,
+    "with nothing said by the viewer, a request stuck behind the head still repairs the run"
+  );
+  assert.notEqual(session.seekSettleTimer, null);
+});
+
+test("a request cannot move the viewer's position backwards", async (t) => {
+  const { manager, session, dirPath } = await sessionWithRunAt373();
+  t.after(async () => {
+    await tidy(manager, session, dirPath);
+  });
+
+  manager.requestSeek(SESSION_ID, 2083.4);
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(BEHIND_INDEX), { requestSeq: 1 });
+
+  assert.equal(
+    session.viewerPositionSeconds,
+    2083.4,
+    "a stale request must not rewrite what the viewer reported — that is how the repair came to believe it"
+  );
+});

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