@torrent-tv/proxy 2.82.0 → 2.83.1

package/services/delivery-probe.js

@@ -99,16 +99,46 @@ export function allowedGap({
   if (!(bytesPerSecond > 0) || !(intervalMs > 0)) {
     return null;
   }
-  const drainMs = (Math.max(queuedBytes, 0) / bytesPerSecond) * 1000;
-  const waitMs =
-    drainMs +
-    Math.max(rttMs, 0) +
-    Math.max(echoIntervalMs, 0) +
-    Math.max(peerLoopLagMs, 0);
   // At least one: a probe sent and not yet echoed is the ordinary state.
-  return Math.max(1, Math.ceil(waitMs / intervalMs));
+  return Math.max(1, Math.ceil(allowedWaitMs({ queuedBytes, bytesPerSecond, rttMs, echoIntervalMs, peerLoopLagMs }) / intervalMs));
+}
+
+/**
+ * How long a probe may legitimately take to be reported back, in milliseconds.
+ *
+ * THE QUANTITY {@link allowedGap} COMPUTES AND THEN THROWS AWAY by dividing it
+ * into probes. Probes are the wrong unit and always were: the same probe goes
+ * down every channel INCLUDING the one carrying the film, and SCTP schedules
+ * per association, so a probe waits behind queued video exactly as a segment
+ * does. What is behind is then not the peer's answer but the probe itself —
+ * and the honest measure of that is the age of the newest probe the peer has
+ * seen, which this is compared against.
+ *
+ * Four terms, every one measured: the queue's own drain time at the rate this
+ * connection is achieving, the crossing, the peer's reporting cadence, and how
+ * late the peer's event loop is running.
+ *
+ * @param {{ queuedBytes: number, bytesPerSecond: number, rttMs: number,
+ *   echoIntervalMs?: number, peerLoopLagMs?: number }} state
+ * @returns {number}
+ */
+export function allowedWaitMs({ queuedBytes, bytesPerSecond, rttMs, echoIntervalMs = 0, peerLoopLagMs = 0 }) {
+  if (!(bytesPerSecond > 0)) {
+    return 0;
+  }
+  const drainMs = (Math.max(queuedBytes, 0) / bytesPerSecond) * 1000;
+  return drainMs + Math.max(rttMs, 0) + Math.max(echoIntervalMs, 0) + Math.max(peerLoopLagMs, 0);
 }
 
+/**
+ * How far back the send times of probes are kept.
+ *
+ * A probe older than the point at which the reverse direction is called gone
+ * can say nothing further, and that bound is itself derived per connection —
+ * this is the outer edge of it, kept so the map cannot grow with the session.
+ */
+const PROBE_HISTORY_MS = 10 * 60 * 1000;
+
 /** The label the browser gives the unordered, non-retransmitting channel. */
 export const UNRELIABLE_LABEL = "proxy-fast";
 
@@ -144,12 +174,33 @@ const REPORT_INTERVAL_MS = 5_000;
  * as {@link wedgeIsCertain} in `data-channel-handler.js`, applied to the
  * probe's own counter instead of the transport's byte counter.
  *
- * @param {{ stuckForMs: number, longestHealthySeenGapMs: number, intervalMs?: number }} state
- * @returns {{ certain: boolean, needMs: number }}
+ * THE FLOOR IS NOT ONE PROBE INTERVAL. "The longest gap this connection has
+ * ever shown" is nothing at all in its first minutes, and the floor under it
+ * was a single interval — 500 ms — so any two-second quiet stretch while the
+ * browser filled its cushion read as longer than anything healthy ever seen.
+ * Field 2026-09-11: two captures of 180 s each, triggered at `wedged 1s` and
+ * `wedged 2s`, on a connection with `rtt=5ms`, every queue at 0 B and the
+ * viewer watching; 65 MB of them were left on the addon's disk.
+ *
+ * What replaces it is the connection's own answer to how long a legitimate
+ * report may take: the peer reports twice a second, the report has to cross,
+ * and the peer's own event loop may be late — all three measured, all three
+ * already summed for `echoStaleMs`. A stretch shorter than that proves nothing
+ * whatever about the association.
+ *
+ * @param {{ stuckForMs: number, longestHealthySeenGapMs: number, intervalMs?: number,
+ *   legitimateReportMs?: number }} state
+ * @returns {{ isCertain: boolean, needMs: number }}
  */
-export function probeWedgeIsCertain({ stuckForMs, longestHealthySeenGapMs, intervalMs = PROBE_INTERVAL_MS }) {
-  const needMs = Math.max(longestHealthySeenGapMs, intervalMs);
-  return { certain: stuckForMs >= needMs, needMs };
+export function probeWedgeIsCertain({
+  stuckForMs,
+  longestHealthySeenGapMs,
+  intervalMs = PROBE_INTERVAL_MS,
+  legitimateReportMs = 0
+}) {
+  const floorMs = Math.max(intervalMs, Number.isFinite(legitimateReportMs) ? legitimateReportMs : 0);
+  const needMs = Math.max(longestHealthySeenGapMs, floorMs);
+  return { isCertain: stuckForMs >= needMs, needMs };
 }
 
 /**
@@ -218,47 +269,76 @@ export function probeWedgeIsCertain({ stuckForMs, longestHealthySeenGapMs, inter
 export function readProbeState(state) {
   const seenOf = (label) =>
     state.seen instanceof Map ? state.seen.get(label) : state.seen?.[label];
+  /**
+   * @param {unknown} source
+   * @param {string} label
+   * @returns {number | null}
+   */
+  const timeOf = (source, label) => {
+    const value = source instanceof Map ? source.get(label) : /** @type {any} */ (source)?.[label];
+    return Number.isFinite(value) ? Number(value) : null;
+  };
   const allowedOf = (label) => {
     const source = state.allowed;
     const value = source instanceof Map ? source.get(label) : source?.[label];
     return Number.isInteger(value) ? Number(value) : null;
   };
   const parts = [];
-  let orderedBehind = false;
-  let unreliableBehind = false;
-  let unreliableKnown = false;
-  let judgeable = false;
+  let isOrderedBehind = false;
+  let isUnreliableBehind = false;
+  let isUnreliableKnown = false;
+  let isJudgeable = false;
   for (const label of state.labels) {
     const seen = seenOf(label);
     const gap = Number.isInteger(seen) ? state.seq - Number(seen) : null;
     const allowance = allowedOf(label);
-    parts.push(`${label}=${seen ?? "?"}(gap ${gap ?? "?"} of ${allowance ?? "?"})`);
+    // BY TIME WHERE IT IS KNOWN. The count is what the line prints, because it
+    // is what a reader recognises; what decides is a time.
+    //
+    // The measured one-way delay first: it is the forward direction itself,
+    // with the two clocks reconciled from the exchange. The age of the newest
+    // reported probe is the fallback, and it is larger than the thing itself by
+    // the peer's reporting cadence and the way back — which is why its own
+    // allowance carries both of those and the one-way allowance carries
+    // neither.
+    const oneWay = timeOf(state.oneWayMs, label);
+    const oneWayAllowed = timeOf(state.allowedOneWayMs, label);
+    const lagMs = oneWay !== null && oneWayAllowed !== null ? oneWay : timeOf(state.behindMs, label);
+    const mayWaitMs = oneWay !== null && oneWayAllowed !== null
+      ? oneWayAllowed
+      : timeOf(state.allowedWaitMs, label);
+    const lagText = lagMs === null || mayWaitMs === null
+      ? ""
+      : ` ${Math.round(lagMs)}ms of ${Math.round(mayWaitMs)}ms${oneWay !== null ? " one way" : ""}`;
+    parts.push(`${label}=${seen ?? "?"}(gap ${gap ?? "?"} of ${allowance ?? "?"}${lagText})`);
     if (allowance === null) {
       continue;
     }
-    judgeable = true;
-    const behind = gap === null || gap > allowance;
+    isJudgeable = true;
+    const isBehind = lagMs !== null && mayWaitMs !== null
+      ? lagMs > mayWaitMs
+      : gap === null || gap > allowance;
     if (label === UNRELIABLE_LABEL) {
-      unreliableKnown = true;
-      unreliableBehind = behind;
-    } else if (behind) {
-      orderedBehind = true;
+      isUnreliableKnown = true;
+      isUnreliableBehind = isBehind;
+    } else if (isBehind) {
+      isOrderedBehind = true;
     }
   }
-  const advancing = state.peerBytesAdvancing === true;
+  const isPeerAdvancing = state.peerBytesAdvancing === true;
   const detail =
     `sent=${state.seq} ${parts.join(" ")} ` +
     `echoAge=${state.echoAgeMs === null ? "never" : `${state.echoAgeMs}ms`}` +
     (state.peerBytesAdvancing === null || state.peerBytesAdvancing === undefined
       ? ""
-      : ` peerBytes=${advancing ? "advancing" : "still"}`) +
+      : ` peerBytes=${isPeerAdvancing ? "advancing" : "still"}`) +
     (Number.isFinite(state.peerLoopLagMs) ? ` peerLoopLag=${Math.round(Number(state.peerLoopLagMs))}ms` : "") +
     (state.peerVisibility ? ` peerTab=${state.peerVisibility}` : "");
 
   if (state.echoes === 0) {
     return { verdict: "no-echo-yet", detail };
   }
-  if (!judgeable) {
+  if (!isJudgeable) {
     return { verdict: "no-rate-yet", detail };
   }
   const staleAfterMs = Number.isFinite(state.echoStaleMs) && state.echoStaleMs > 0
@@ -267,21 +347,21 @@ export function readProbeState(state) {
   if (state.echoAgeMs !== null && state.echoAgeMs > staleAfterMs) {
     return { verdict: "reverse-direction-gone", detail };
   }
-  if (!orderedBehind && !(unreliableKnown && unreliableBehind)) {
+  if (!isOrderedBehind && !(isUnreliableKnown && isUnreliableBehind)) {
     return { verdict: "flowing", detail };
   }
   // Bytes are still arriving at the far end. Whatever the probe gaps say, this
   // association has not stopped — the probes are behind a backlog, which is
   // what filling a cushion looks like from here.
-  if (advancing) {
+  if (isPeerAdvancing) {
     return { verdict: "flowing", detail };
   }
-  if (orderedBehind && unreliableKnown && !unreliableBehind) {
+  if (isOrderedBehind && isUnreliableKnown && !isUnreliableBehind) {
     return { verdict: "stream-stuck", detail };
   }
-  if (orderedBehind) {
+  if (isOrderedBehind) {
     return {
-      verdict: unreliableKnown ? "association-stopped" : "ordered-behind-no-comparison",
+      verdict: isUnreliableKnown ? "association-stopped" : "ordered-behind-no-comparison",
       detail
     };
   }
@@ -327,6 +407,18 @@ export function createDeliveryProbe({
     const now = Date.now();
     connection.seq += 1;
     connection.sentAt = now;
+    // WHEN each probe went out, so that what the peer reports can be read as a
+    // time rather than as a count of probes. Pruned to the oldest probe any
+    // judgement could still be about: once a probe is older than the point at
+    // which the reverse direction is called gone, its age says nothing further.
+    connection.sentAtBySeq.set(connection.seq, now);
+    for (const [probeNumber, sentAt] of connection.sentAtBySeq) {
+      if (now - sentAt > PROBE_HISTORY_MS) {
+        connection.sentAtBySeq.delete(probeNumber);
+      } else {
+        break;
+      }
+    }
     const message = JSON.stringify({ type: "probe", seq: connection.seq, sentAt: now });
     for (const channel of connection.channels.keys()) {
       try {
@@ -343,6 +435,10 @@ export function createDeliveryProbe({
     const rttMs = Number(delivery?.rttMs) || 0;
     /** @type {Map<string, number | null>} */
     const allowed = new Map();
+    /** How long each channel's newest unreported probe may legitimately be. */
+    const allowedWait = new Map();
+    /** The same, for the measured one-way time where the clocks are reconciled. */
+    const allowedOneWay = new Map();
     for (const [channel, label] of connection.channels) {
       let queuedBytes = 0;
       try {
@@ -358,6 +454,26 @@ export function createDeliveryProbe({
         peerLoopLagMs: connection.peerLoopLagMs ?? 0,
         intervalMs
       });
+      const waitMs = allowedWaitMs({
+        queuedBytes,
+        bytesPerSecond,
+        rttMs,
+        echoIntervalMs: connection.echoIntervalMs,
+        peerLoopLagMs: connection.peerLoopLagMs ?? 0
+      });
+      const heldWait = allowedWait.get(label);
+      if (!Number.isFinite(heldWait) || waitMs > heldWait) {
+        allowedWait.set(label, waitMs);
+      }
+      // What a probe may take ONE WAY: the queue's own drain time and half the
+      // crossing. Neither the peer's reporting cadence nor its loop delay
+      // belongs here — with the clocks reconciled they are no longer in the
+      // measurement they would have to be allowed for.
+      const oneWayAllowed = allowedWaitMs({ queuedBytes, bytesPerSecond, rttMs: rttMs / 2 });
+      const heldOneWay = allowedOneWay.get(label);
+      if (!Number.isFinite(heldOneWay) || oneWayAllowed > heldOneWay) {
+        allowedOneWay.set(label, oneWayAllowed);
+      }
       // Several channels can carry one label only in malformed cases; the
       // larger allowance is the safer of the two.
       const held = allowed.get(label);
@@ -398,6 +514,25 @@ export function createDeliveryProbe({
       peerLoopLagMs: connection.peerLoopLagMs,
       peerVisibility: connection.peerVisibility,
       allowed,
+      // WHAT IS BEHIND, IN TIME. For each channel: how old the newest probe the
+      // peer has reported seeing is. The same probe goes down every channel
+      // including the one carrying the film, and SCTP schedules per
+      // association, so a probe waits behind queued video exactly as a segment
+      // does — which means a count of outstanding probes measures the queue,
+      // not the association. This is the queue's own time, against the time the
+      // queue is allowed to take.
+      behindMs: Object.fromEntries(
+        [...connection.seen.entries()].map(([label, newestSeenNumber]) => {
+          const sentAt = connection.sentAtBySeq.get(newestSeenNumber);
+          return [label, Number.isFinite(sentAt) ? now - sentAt : null];
+        })
+      ),
+      allowedWaitMs: Object.fromEntries(allowedWait.entries()),
+      // The measured forward delay, where the two clocks have been reconciled.
+      // Preferred over the age above because it is the thing itself: the age
+      // also carries the peer's reporting cadence and the way back.
+      oneWayMs: Object.fromEntries(connection.oneWayMs.entries()),
+      allowedOneWayMs: Object.fromEntries(allowedOneWay.entries()),
       // Same arithmetic for the echo's own age: the peer cannot answer sooner
       // than its own cadence allows, nor sooner than its own event loop runs.
       echoStaleMs:
@@ -422,11 +557,24 @@ export function createDeliveryProbe({
     // as a legitimate gap, is the wedge this exists to catch.
     const stuckForMs = connection.lastSeenAdvanceAt === 0 ? 0 : now - connection.lastSeenAdvanceAt;
     if (verdict === "association-stopped") {
-      const { certain, needMs } = probeWedgeIsCertain({
+      const { isCertain, needMs } = probeWedgeIsCertain({
         stuckForMs,
-        longestHealthySeenGapMs: connection.longestHealthySeenGapMs
+        longestHealthySeenGapMs: connection.longestHealthySeenGapMs,
+        // The same sum the echo's own staleness is judged by: the peer reports
+        // twice a second, the report has to cross, and the peer's loop may be
+        // late. Nothing shorter than that says anything.
+        // BOTH cadences, because they beat against each other: a probe sent
+        // just after the peer composed a report shows up only in the NEXT one.
+        // So the longest legitimate gap between two advances is one probe
+        // interval plus one report interval plus the crossing plus whatever
+        // the peer's own loop is behind by.
+        legitimateReportMs:
+          intervalMs +
+          connection.echoIntervalMs +
+          rttMs +
+          Math.max(connection.peerLoopLagMs ?? 0, 0)
       });
-      if (certain && !connection.probeCaptureStarted) {
+      if (isCertain && !connection.probeCaptureStarted) {
         connection.probeCaptureStarted = true;
         const reasonText =
           `probe seen-counter unmoved ${Math.round(stuckForMs / 1000)}s against the ` +
@@ -497,6 +645,24 @@ export function createDeliveryProbe({
           reportedAt: 0,
           lastSeenAdvanceAt: 0,
           longestHealthySeenGapMs: 0,
+          sentAtBySeq: new Map(),
+          // THE TWO CLOCKS, separated by the exchange rather than assumed to
+          // agree. Every report carries when each channel's newest probe
+          // arrived at the peer and when the report itself left; with the time
+          // this proxy stamped into that probe, and the time the report
+          // arrives, that is the four timestamps an offset is computed from.
+          //
+          // The estimate is kept from the report with the SMALLEST round trip
+          // seen, because that is the one that queued the least — and the two
+          // directions here are as unequal as they get, film one way and almost
+          // nothing the other, which is exactly where an offset taken from a
+          // busy moment is wrong by half the difference.
+          /** @type {number | null} */
+          clockOffsetMs: null,
+          /** @type {number} */
+          offsetFromRoundTripMs: Number.POSITIVE_INFINITY,
+          /** How long the newest probe took to reach the peer, by channel. @type {Map<string, number>} */
+          oneWayMs: new Map(),
           probeCaptureStarted: false,
           timer: null
         };
@@ -565,6 +731,43 @@ export function createDeliveryProbe({
           connection.lastSeenAdvanceAt = now;
         }
       }
+      // THE FOUR TIMESTAMPS. `t1` is when this proxy sent the probe the peer
+      // is reporting, `t2` when the peer received it, `t3` when the peer sent
+      // this report, `t4` is now. From them the round trip is
+      // `(t4 - t1) - (t3 - t2)` — the peer's own thinking time removed — and
+      // the difference between the two clocks is `((t2 - t1) + (t3 - t4)) / 2`.
+      //
+      // The offset is kept from the report whose round trip was SMALLEST: that
+      // arithmetic assumes the two directions are equally quick, which here
+      // they are not — film one way, almost nothing the other — and the least
+      // queued sample is the one where the assumption costs least. A fresh
+      // minimum replaces the estimate, so a clock that jumps is followed within
+      // a few reports rather than believed for ever.
+      const peerSentAt = Number(echo?.sentAt);
+      const seenAt = echo?.seenAt;
+      if (Number.isFinite(peerSentAt) && seenAt && typeof seenAt === "object") {
+        for (const [label, peerSawAtRaw] of Object.entries(seenAt)) {
+          const peerSawAt = Number(peerSawAtRaw);
+          const newestSeenNumber = connection.seen.get(label);
+          const weSentAt = Number.isInteger(newestSeenNumber)
+            ? connection.sentAtBySeq.get(newestSeenNumber)
+            : undefined;
+          if (!Number.isFinite(peerSawAt) || !Number.isFinite(weSentAt)) {
+            continue;
+          }
+          const roundTrip = (now - weSentAt) - (peerSentAt - peerSawAt);
+          if (roundTrip >= 0 && roundTrip < connection.offsetFromRoundTripMs) {
+            connection.offsetFromRoundTripMs = roundTrip;
+            connection.clockOffsetMs = ((peerSawAt - weSentAt) + (peerSentAt - now)) / 2;
+          }
+          if (connection.clockOffsetMs !== null) {
+            // What the probe itself took, one way, with the clocks reconciled.
+            // Negative only if the offset is stale, and then it says so rather
+            // than being hidden.
+            connection.oneWayMs.set(label, peerSawAt - weSentAt - connection.clockOffsetMs);
+          }
+        }
+      }
       // What the far end says it has received at the transport level. It is the
       // one figure that separates a backlog from a stopped association, and it
       // arrives on the direction that goes on working through a freeze.
@@ -575,17 +778,19 @@ export function createDeliveryProbe({
       // Sum of per-channel bytes. Transport's bytesReceived advances on SACKs
       // (140 B/s on a wedge) and gives a false "advancing" every other tick —
       // channel bytes are flat on a wedge, so they are the correct signal.
-      const ch = echo?.report?.channels;
-      if (ch && typeof ch === "object") {
-        let total = 0;
-        let has = false;
-        for (const v of Object.values(ch)) {
-          if (v && typeof v.bytes === "number" && Number.isFinite(v.bytes)) {
-            total += v.bytes;
-            has = true;
+      const peerChannels = echo?.report?.channels;
+      if (peerChannels && typeof peerChannels === "object") {
+        let bytesAcrossChannels = 0;
+        let hasChannelReport = false;
+        for (const channelReport of Object.values(peerChannels)) {
+          if (channelReport && Number.isFinite(channelReport.bytes)) {
+            bytesAcrossChannels += channelReport.bytes;
+            hasChannelReport = true;
           }
         }
-        if (has) connection.peerChannelBytes = total;
+        if (hasChannelReport) {
+          connection.peerChannelBytes = bytesAcrossChannels;
+        }
       }
       // How far behind the far end's own event loop is running. A browser that
       // cannot run its timers cannot answer a probe, and every allowance here

package/services/disk/keep.js

@@ -0,0 +1,48 @@
+/**
+ * @file How long material nobody is using is kept.
+ *
+ * ONE NUMBER, IN ONE PLACE, because everything it governs stands for the same
+ * unmeasured thing: whether the viewer comes back. Everything else in the
+ * decision is measured or measurable — re-downloading a piece from the swarm is
+ * ~1430 ms on the field host, re-making a segment is its own encode time, and
+ * the disk now has an owner that prices holding it. Only the return is unknown,
+ * and a period is what stands in for it.
+ *
+ * IT WAS THREE NUMBERS AND THEY CONTRADICTED EACH OTHER (read 2026-09-10):
+ *
+ *   torrent and its downloaded bytes   15 minutes
+ *   session                            30 minutes
+ *   produced segments                   6 hours
+ *
+ * The torrent therefore went at fifteen minutes while the session it feeds
+ * lived to thirty, so between them there was a session with no source: a viewer
+ * returning at the twentieth minute got a session that could not make a single
+ * new segment until the torrent was added again. That is not two answers to one
+ * question, it is a contradiction — and it is what two independent guesses about
+ * one unknown produce.
+ *
+ * With one hour for both kinds of material the session dies first, which is the
+ * right order and needs no rule of its own to enforce.
+ *
+ * WHY AN HOUR, honestly: nothing derives it. It is a stand-in, chosen to be
+ * long enough that an interruption — a phone call, a meal — does not cost the
+ * film, and short enough that a household disk is not held for a day by
+ * somebody who is not coming back. It is the OWNER'S disk, and holding
+ * gigabytes on it because there happens to be room is taking something that is
+ * not ours.
+ *
+ * WHAT REPLACES IT, and the proxy is already in a position to measure it: every
+ * session opened on an output whose segments are still on disk IS a return, and
+ * its age is known. `services/disk/returns.js` records them. A week of those and
+ * the distribution answers this directly — keep material for as long as returns
+ * actually happen — and then the two kinds can have different numbers, since
+ * their costs of coming back differ.
+ */
+
+/**
+ * How long material nobody has read is kept, in milliseconds.
+ *
+ * Read by the torrent pool for a torrent and its downloaded bytes, and by the
+ * session manager for the segments an encoder produced.
+ */
+export const IDLE_KEEP_MS = 60 * 60 * 1000;

package/services/disk/returns.js

@@ -0,0 +1,103 @@
+/**
+ * @file How long after material stops being read somebody asks for it again.
+ *
+ * The one term of "how long do we keep this" that nothing measures. Everything
+ * else in that decision is a measured quantity — re-downloading a piece from
+ * the swarm is ~1430 ms on the field host, re-making a segment is its own
+ * encode time, and the disk has an owner that prices holding it. Only the
+ * return is unknown, and `IDLE_KEEP_MS` is a guess standing in for it.
+ *
+ * IT IS MEASURABLE HERE AND NOWHERE ELSE. A session opened on an output whose
+ * segments are still on disk IS a return, and its age is known exactly: the
+ * store records when each output was last read. Nothing needs to be inferred.
+ *
+ * This changes no behaviour. It records, and says what it has seen once in a
+ * while, so that after a week of ordinary use the period can be derived from
+ * what viewers actually do instead of from what a period felt like.
+ */
+
+/** How many returns are kept. Enough to see a shape, few enough to say in a line. */
+const KEPT = 200;
+
+export class Returns {
+  /** Ages in milliseconds, newest last. @type {number[]} */
+  #ages = [];
+
+  /** Sessions opened on material this proxy no longer had. */
+  #cold = 0;
+
+  /** Sessions opened on material that was still there. */
+  #warm = 0;
+
+  /**
+   * Note a session being opened on an output.
+   *
+   * @param {object} params
+   * @param {number | null} params.lastReadAt - When that output was last read,
+   *   or null where this proxy has never held it.
+   * @param {number} params.now
+   * @returns {void}
+   */
+  note({ lastReadAt, now }) {
+    if (!Number.isFinite(lastReadAt) || lastReadAt === null || lastReadAt <= 0) {
+      this.#cold += 1;
+      return;
+    }
+    this.#warm += 1;
+    this.#ages.push(Math.max(0, now - /** @type {number} */ (lastReadAt)));
+    while (this.#ages.length > KEPT) {
+      this.#ages.shift();
+    }
+  }
+
+  /**
+   * What the returns look like, or null while there have been none.
+   *
+   * The MEDIAN and the LONGEST, because those are the two the period has to sit
+   * between: shorter than the median throws away material half the returns
+   * wanted, and longer than the longest keeps material no return has ever
+   * reached.
+   *
+   * @returns {{ warm: number, cold: number, medianMs: number, longestMs: number } | null}
+   */
+  shape() {
+    if (this.#ages.length === 0) {
+      return null;
+    }
+    const sorted = [...this.#ages].sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return {
+      warm: this.#warm,
+      cold: this.#cold,
+      medianMs: sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle],
+      longestMs: sorted[sorted.length - 1]
+    };
+  }
+
+  /**
+   * One line, for the log, or null while there is nothing to say.
+   *
+   * @param {number} keepMs - What is being kept for now, so the reading and the
+   *   guess it will replace stand side by side.
+   * @returns {string | null}
+   */
+  describe(keepMs) {
+    const shape = this.shape();
+    if (shape === null) {
+      return null;
+    }
+    return (
+      `returns: ${shape.warm} session(s) opened on material still held, ` +
+      `${shape.cold} on material gone; median ${minutes(shape.medianMs)} after the last read, ` +
+      `longest ${minutes(shape.longestMs)} — kept for ${minutes(keepMs)}`
+    );
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function minutes(ms) {
+  return `${Math.round(ms / 60000)}min`;
+}

package/services/download/SwarmSelection.js

@@ -180,15 +180,15 @@ export class SwarmSelection {
       this.#clearDisplacement();
       return;
     }
-    const from = Math.min(...blocked.map((range) => range.from));
-    const to = Math.max(...blocked.map((range) => range.to));
-    if (this.#displacing && this.#displacing.from === from && this.#displacing.to === to) {
+    const nearest = Math.min(...blocked.map((range) => range.from));
+    const furthest = Math.max(...blocked.map((range) => range.to));
+    if (this.#displacing && this.#displacing.from === nearest && this.#displacing.to === furthest) {
       return;
     }
     this.#clearDisplacement();
     try {
-      this.#torrent.critical?.(from, to);
-      this.#displacing = { from, to };
+      this.#torrent.critical?.(nearest, furthest);
+      this.#displacing = { from: nearest, to: furthest };
     } catch {
       // silent-ok: displacement is an optimisation, and a torrent being torn
       // down is not worth failing a read over.

package/services/download/registry.js

@@ -41,6 +41,26 @@ export function demandFor(torrent) {
   return entry;
 }
 
+/**
+ * Whether this torrent is still short of anything anybody asked for.
+ *
+ * Read by the upload policy: while a reader is missing bytes, a little upload
+ * buys the reciprocity that gets them; once nothing declared is missing it buys
+ * nothing at all, and on 2026-09-11 the proxy went on offering 512 KB/s of a
+ * fully downloaded file to 596 peers for forty-eight minutes, reading a 4 MB
+ * piece off the disk for every 16 KB it sent.
+ *
+ * False for a torrent nothing has been stated about, which is the same answer
+ * and the right one: nobody is waiting for it.
+ *
+ * @param {object} torrent
+ * @returns {boolean}
+ */
+export function hasUnmetDemand(torrent) {
+  const held = byTorrent.get(torrent);
+  return held ? held.selection.hasUrgentMissing() : false;
+}
+
 /**
  * Give up everything stated for a torrent that is going.
  *

package/services/encode/EncodeRun.js

@@ -642,6 +642,7 @@ export class EncodeRun {
     const outcome = classifyEncodeExit({
       code,
       producedThrough: this.#produced.size > 0 ? this.reached : null,
+      producedCount: this.#produced.size,
       lastSegmentIndex: endOfWork,
       inputUnavailable: this.inputUnavailable(this.lastError)
     });

package/services/encode/Encoder.js

@@ -82,6 +82,21 @@ export class Encoder {
     throw new Error(`${this.name} does not say how to build its video arguments.`);
   }
 
+  /**
+   * What this kind needs BEFORE the input when it is being benchmarked.
+   *
+   * Not `inputArgs`: those set up hardware DECODING, and a benchmark is fed raw
+   * frames — there is nothing to decode. What a device-backed encoder still
+   * needs is the device itself, and without it `h264_vaapi` and `h264_qsv` fail
+   * to open at all, so the benchmark would answer "this host cannot encode"
+   * about a host that encodes perfectly well.
+   *
+   * @returns {string[]}
+   */
+  benchmarkInputArgs() {
+    return [];
+  }
+
   /**
    * How to encode raw frames at one rung of this kind's speed ladder, for the
    * startup benchmark and nothing else.

package/services/encode/QsvEncoder.js

@@ -35,6 +35,11 @@ export class QsvEncoder extends Encoder {
     };
   }
 
+  /** @returns {string[]} */
+  benchmarkInputArgs() {
+    return this.device ? ["-qsv_device", this.device] : [];
+  }
+
   /** @param {string | null} rung @returns {string[]} */
   benchmarkArgs(rung = null) {
     const preset = rung ? ["-preset", rung] : [];