@torrent-tv/proxy 2.82.0 → 2.83.1

package/services/torrent-worker/worker.js

@@ -36,6 +36,8 @@ import {
   warmResumePosition
 } from "./container-tracks.js";
 import { fillFileInBackground } from "./background-fill.js";
+import { CompletedFiles, completedFilesRoot } from "../files/CompletedFiles.js";
+import { pieceFromWholeFiles, pieceIsInWholeFiles } from "../files/piece-from-whole-file.js";
 import { Command, Event } from "./protocol.js";
 import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../memory-report.js";
 import { forwardLogsTo, logger } from "../../utils/logger.js";
@@ -65,7 +67,7 @@ forwardLogsTo((_level, message) => {
 // the hook above had a chance to register. Verified the hard way: with a static
 // import the process still aborted, and the stack named the genuine polyfill.
 const { TorrentPool, resolveDhtBootstrap } = await import("../torrent-pool.js");
-const { collectStoreStats, machineReserveBytes, pieceBufferCollection, reviseSpillBudgets, reviseStoreBudgets } =
+const { collectStoreStats, findSharedStore, machineReserveBytes, pieceBufferCollection, reviseSpillBudgets, reviseStoreBudgets } =
   await import("../piece-store/shared-piece-store.js");
 
 // Resolved before the client exists, because the client builds its DHT in its
@@ -733,7 +735,9 @@ setInterval(() => {
       `on-disk=${Math.round((stats.spilledBytes || 0) / 1048576)}MB ` +
       `pinned=${stats.pinned} spilled=${stats.spilled} reads=${reads} (${fromMemoryShare}% from memory) ` +
       `spills=${stats.spills} revivals=${stats.revivals}` +
-      (stats.blockedByPins > 0 ? ` blocked-by-pins=${stats.blockedByPins}` : "") +
+      (stats.blockedByPins > 0 ? ` no-block-for=${stats.blockedByPins}` : "") +
+      (stats.admittedWithoutSlot > 0 ? ` to-disk-for-want-of-memory=${stats.admittedWithoutSlot}` : "") +
+      (stats.stillMs > 1000 ? ` nothing-moved-for=${Math.round(stats.stillMs / 1000)}s` : "") +
       (stats.evictedOnRevise > 0 ? ` evictedOnRevise=${stats.evictedOnRevise}` : "") +
       (stats.spillFailures > 0 ? ` spill-failures=${stats.spillFailures}` : "") +
       (stats.outstanding > 0 ? ` outstanding=${stats.outstanding}` : "")
@@ -922,6 +926,183 @@ setInterval(() => {
   }
 }, SUBTITLE_WARMUP_INTERVAL_MS).unref();
 
+/**
+ * Files this proxy has downloaded whole. One directory, two readers of it: this
+ * thread writes them, the main thread serves them without asking anybody.
+ */
+const completedFiles = new CompletedFiles({ root: completedFilesRoot() });
+
+/**
+ * Which torrent a set of files belongs to.
+ *
+ * The piece store hands its own files back without knowing what they are; this
+ * thread does know, and a file carries its torrent.
+ *
+ * @param {object[]} files
+ * @returns {string}
+ */
+const infoHashOf = (files) => String(files?.[0]?._torrent?.infoHash ?? "").toLowerCase();
+
+// WHERE A PIECE COMES FROM WHEN NEITHER TIER HAS IT. Handed to every store this
+// pool builds, so a film already assembled into a file is read from that file:
+// which is what lets its spilled copy be dropped as the duplicate it has become,
+// and what lets a torrent be destroyed and added again without fetching a byte.
+pool.buildStoresWith({
+  readPieceElsewhere: ({ index, pieceLength, length, files }) =>
+    pieceFromWholeFiles({
+      index,
+      pieceLength,
+      length,
+      files,
+      wholeFileAt: (fileIndex) => completedFiles.find(infoHashOf(files), fileIndex)
+    }),
+  isPieceElsewhere: ({ index, pieceLength, length, files }) =>
+    pieceIsInWholeFiles({
+      index,
+      pieceLength,
+      length,
+      files,
+      wholeFileAt: (fileIndex) => completedFiles.find(infoHashOf(files), fileIndex)
+    })
+});
+void completedFiles.adopt(() => null).then((adopted) => {
+  if (adopted > 0) {
+    logger.info(
+      `whole files: took up ${adopted} file(s) a previous life left in ${completedFiles.root}`
+    );
+  }
+});
+
+/**
+ * How often whole files are looked for.
+ *
+ * The work itself is one pass over the files of each torrent asking a boolean
+ * the library already keeps; writing one out happens at most once per file,
+ * ever.
+ */
+const WHOLE_FILE_SWEEP_MS = 10_000;
+
+/** Files being written out right now, so a sweep does not start a second one. */
+const beingKept = new Set();
+
+/**
+ * Keep every file that is now whole, and let go of a torrent that has nothing
+ * left to fetch.
+ *
+ * The instruction this serves, 2026-09-11: as soon as a torrent is fully
+ * downloaded, downloading stops, the torrent is deleted, and what was
+ * downloaded stays for as long as it is wanted.
+ *
+ * `file.done` is the library's own answer to "is every piece of this file
+ * here", and `torrent.done` to "is that true of every file". The second is a
+ * strong condition and will not fire for a season pack of which one episode is
+ * watched — nothing fetches the other four — and that is right: the instruction
+ * is about a torrent downloaded WHOLE.
+ *
+ * @returns {Promise<void>}
+ */
+async function keepWholeFiles() {
+  for (const [sourceKey, torrent] of [...pool.torrents]) {
+    // Lower case, because that is what the source key carries and the main
+    // thread looks these up by the key alone.
+    const infoHash = String(torrent?.infoHash ?? "").toLowerCase();
+    if (!infoHash || !Array.isArray(torrent.files)) {
+      continue;
+    }
+    const usage = pool.fileUsageByTorrent?.get?.(torrent);
+    for (const [fileIndex, file] of torrent.files.entries()) {
+      const key = `${infoHash}/${fileIndex}`;
+      if (file?.done !== true || completedFiles.find(infoHash, fileIndex) || beingKept.has(key)) {
+        continue;
+      }
+      // NOT WHILE SOMEBODY IS READING IT. Writing a film out is a read of the
+      // whole of it and a write of the whole of it — a gigabyte and a half on
+      // the file this was measured against — and doing that beside a viewer
+      // takes the disk and the piece store from them for nothing they asked
+      // for. The file is complete; it will still be complete when they leave.
+      if (usage?.has?.(fileIndex)) {
+        continue;
+      }
+      beingKept.add(key);
+      try {
+        const kept = await completedFiles.keep({
+          infoHash,
+          fileIndex,
+          length: file.length,
+          name: file.name,
+          open: () => file.createReadStream()
+        });
+        if (kept) {
+          logger.info(
+            `whole files: kept "${file.name}" (${Math.round(kept.length / 1048576)}MB) — ` +
+            "it is a file now, and reading it needs no torrent"
+          );
+          // The pieces it was built from are a second copy of the same bytes.
+          // Nothing is lost by dropping them: a read that wants one of them is
+          // answered from the file.
+          const store = findSharedStore(torrent);
+          const dropped = store?.dropDuplicatesHeldElsewhere?.() ?? 0;
+          if (dropped > 0) {
+            logger.info(
+              `whole files: dropped ${dropped} spilled piece(s) of "${file.name}" — ` +
+              "the film was on this disk twice and is not any more"
+            );
+          }
+          parentPort.postMessage({
+            type: Event.FILE_COMPLETE,
+            infoHash,
+            fileIndex,
+            path: kept.path,
+            length: kept.length,
+            name: kept.name
+          });
+        }
+      } catch (error) {
+        logger.warn(`whole files: could not keep "${file?.name}": ${error?.message ?? error}`);
+      } finally {
+        beingKept.delete(key);
+      }
+    }
+    // EVERYTHING, WITHOUT EXCEPTION, AND EVERY BYTE OF IT A FILE ON DISK. The
+    // torrent has no job left: there is nothing to fetch, and this proxy does
+    // not seed what nobody is watching.
+    //
+    // Safe to destroy only because a piece can now be read out of those files:
+    // a path that asks for this source again adds the torrent back, and what it
+    // verifies it reads from the files rather than from the swarm. Not while
+    // anybody is reading it, for the same reason the writing above waits.
+    const isWhole =
+      torrent.done === true &&
+      torrent.files.every((unused, fileIndex) => completedFiles.find(infoHash, fileIndex) !== null);
+    if (isWhole && !(usage?.size > 0)) {
+      logger.info(
+        `whole files: "${torrent.name}" is downloaded whole and saved — removing the torrent, keeping the files`
+      );
+      // THE RECIPE STAYS, and so does the entry that leads to it. Everything
+      // that asks this thread about a source — the track table, the media
+      // info, the keyframe table, the stats the browser polls — comes through
+      // `requireTorrent`, which adds a torrent back when the one it holds is
+      // no longer usable. Deleting the entry here would turn a viewer
+      // returning to this film into `Unknown source`, which is a worse failure
+      // than the one this removal is for.
+      //
+      // What the torrent finds when it comes back is the whole files: its
+      // store reads pieces from them, so it fetches nothing. It is added with
+      // verification skipped, and that is not a shortcut — the file was
+      // written out of pieces this client had already hashed, and its size was
+      // checked against what the torrent says. Re-hashing a gigabyte and a
+      // half to learn what we wrote down is a minute of a viewer's time for
+      // nothing.
+      pool.remove(torrent, "downloaded-whole");
+      pool.addWholeSource(sourceKey);
+    }
+  }
+}
+
+setInterval(() => {
+  void keepWholeFiles();
+}, WHOLE_FILE_SWEEP_MS).unref();
+
 /**
  * Keeps this thread alive ON PURPOSE — the one interval left accounted for
  * (no `.unref()`).

package/test/completed-files.test.js

@@ -0,0 +1,115 @@
+/**
+ * @file Files downloaded whole are files, and outlive the torrent that fetched
+ * them.
+ *
+ * Asked for in these words on 2026-09-11: as soon as a torrent is fully
+ * downloaded, downloading stops, the torrent is deleted, and the artefacts —
+ * what was downloaded — stay for as long as they are wanted.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { CompletedFiles } from "../services/files/CompletedFiles.js";
+
+const INFO_HASH = "abcdef0123456789abcdef0123456789abcdef01";
+
+/** @returns {Promise<string>} */
+const directory = () => fs.mkdtemp(path.join(os.tmpdir(), "whole-files-"));
+
+/**
+ * @param {Buffer} bytes
+ * @param {number} [chunk]
+ * @returns {() => NodeJS.ReadableStream}
+ */
+const opens = (bytes, chunk = 7) => () => {
+  const parts = [];
+  for (let at = 0; at < bytes.length; at += chunk) {
+    parts.push(bytes.subarray(at, Math.min(at + chunk, bytes.length)));
+  }
+  return Readable.from(parts);
+};
+
+test("a file read whole is kept whole, and reads back byte for byte", async () => {
+  const root = await directory();
+  const files = new CompletedFiles({ root });
+  const bytes = Buffer.from("the whole of a small film", "utf8");
+  try {
+    const kept = await files.keep({ infoHash: INFO_HASH, fileIndex: 3, length: bytes.length, name: "film.mkv", open: opens(bytes) });
+    assert.ok(kept, "the file was not kept");
+    assert.equal(kept.length, bytes.length);
+
+    const found = files.find(INFO_HASH, 3);
+    assert.deepEqual(found, kept, "what was kept is not what is found");
+    assert.deepEqual(await fs.readFile(found.path), bytes, "the bytes came back changed");
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("a read that ends early leaves nothing that looks whole", async () => {
+  const root = await directory();
+  const files = new CompletedFiles({ root });
+  const bytes = Buffer.from("half a film", "utf8");
+  try {
+    // The torrent says the file is longer than what its read produced — the
+    // data went away mid-write, which over a torrent is ordinary.
+    const kept = await files.keep({
+      infoHash: INFO_HASH,
+      fileIndex: 0,
+      length: bytes.length + 100,
+      open: opens(bytes)
+    });
+    assert.equal(kept, null, "a short file was kept as whole");
+    assert.equal(files.find(INFO_HASH, 0), null);
+    assert.deepEqual(
+      (await fs.readdir(path.join(root, INFO_HASH))).filter((entry) => entry !== "manifest.json"),
+      [],
+      "a partial file was left behind"
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("what a previous life left is taken up, and what is the wrong size is not", async () => {
+  const root = await directory();
+  const bytes = Buffer.from("a film from the last time this ran", "utf8");
+  try {
+    const first = new CompletedFiles({ root });
+    await first.keep({ infoHash: INFO_HASH, fileIndex: 2, length: bytes.length, name: "film.mkv", open: opens(bytes) });
+    // And one that was being written when the process died, under a name that
+    // says it is whole — the only way to tell is its size.
+    await fs.writeFile(path.join(root, INFO_HASH, "5"), Buffer.alloc(3));
+
+    const second = new CompletedFiles({ root });
+    const adopted = await second.adopt((infoHash, fileIndex) =>
+      infoHash === INFO_HASH && fileIndex === 2 ? bytes.length : 999
+    );
+    assert.equal(adopted, 1, "the whole file was not taken up, or the short one was");
+    assert.equal(second.find(INFO_HASH, 2)?.name, "film.mkv", "the name the torrent gave it was lost");
+    assert.equal(second.find(INFO_HASH, 5), null, "a file of the wrong size was taken up");
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("forgetting a torrent removes its files and nobody else's", async () => {
+  const root = await directory();
+  const files = new CompletedFiles({ root });
+  const other = "0123456789abcdef0123456789abcdef01234567";
+  const bytes = Buffer.from("kept", "utf8");
+  try {
+    await files.keep({ infoHash: INFO_HASH, fileIndex: 1, length: bytes.length, name: "one.mkv", open: opens(bytes) });
+    await files.keep({ infoHash: other, fileIndex: 1, length: bytes.length, name: "two.mkv", open: opens(bytes) });
+
+    await files.forget(INFO_HASH);
+    assert.equal(files.find(INFO_HASH, 1), null);
+    assert.ok(files.find(other, 1), "another torrent's file went with it");
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});

package/test/cuts-follow-published-grid.test.js

@@ -15,6 +15,7 @@
  */
 
 import assert from "node:assert/strict";
+import { computeCutGrid } from "../services/output/cut-grid.js";
 import { Timeline } from "../services/output/Timeline.js";
 import test from "node:test";
 
@@ -71,3 +72,37 @@ test("a session that published no grid falls back to the live one", () => {
   const session = { id: "no-playlist", timeline: new Timeline({ boundaries: [...CORRECTED], published: [], cutGrid: "uniform" }) };
   assert.deepEqual(manager.publishedGridFor(session), CORRECTED);
 });
+
+test("no segment is left shorter than a segment at the end of the film", () => {
+  // The field case of 2026-09-11, to the millisecond: a 54-minute film whose
+  // last keyframe sits 160 ms before the end. Taking it as a cut leaves a
+  // segment of 0.16 s — one the sound has no data in at all, which is how one
+  // output came to have 542 segments and the other 541.
+  const total = 3246.12;
+  const keyframes = [];
+  for (let at = 0; at < total - 1; at += 2) {
+    keyframes.push(Number(at.toFixed(3)));
+  }
+  keyframes.push(3245.96);
+
+  const grid = computeCutGrid({
+    useKeyframeGrid: true,
+    durationSeconds: total,
+    segDur: 6,
+    keyframeTimes: keyframes,
+    startTime: 0
+  });
+
+  const last = grid.boundaries[grid.boundaries.length - 1];
+  const before = grid.boundaries[grid.boundaries.length - 2];
+  assert.equal(last, total, "the film still ends where it ends");
+  assert.ok(
+    last - before >= 6,
+    `the last segment is ${(last - before).toFixed(3)}s, shorter than the 6s every other cut is held to`
+  );
+  // And the rule is the one every cut obeys, so no segment anywhere is short.
+  for (let index = 1; index < grid.boundaries.length; index += 1) {
+    const span = grid.boundaries[index] - grid.boundaries[index - 1];
+    assert.ok(span >= 6 - 0.05, `segment ${index - 1} lasts ${span.toFixed(3)}s`);
+  }
+});

package/test/delivery-probe.test.js

@@ -1,7 +1,13 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { allowedGap, readProbeState, PROBE_INTERVAL_MS, UNRELIABLE_LABEL } from "../services/delivery-probe.js";
+import {
+  allowedGap,
+  probeWedgeIsCertain,
+  readProbeState,
+  PROBE_INTERVAL_MS,
+  UNRELIABLE_LABEL
+} from "../services/delivery-probe.js";
 
 const ORDERED = ["proxy", "proxy-control"];
 const ALL = [...ORDERED, UNRELIABLE_LABEL];
@@ -278,3 +284,110 @@ test("a peer that reports no loop delay is judged exactly as before", () => {
   assert.doesNotMatch(reading.detail, /peerLoopLag=/);
   assert.doesNotMatch(reading.detail, /peerTab=/);
 });
+
+test("a quiet stretch shorter than a legitimate report is not a wedge", () => {
+  // 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. In its first minutes a connection has shown no healthy gap
+  // at all, and the floor under "longer than anything healthy" was a single
+  // probe interval — 500 ms — so any quiet moment beat it.
+  // Both cadences plus the crossing: a probe sent just after the peer composed
+  // a report shows up only in the next one.
+  const legitimateReportMs = 500 + 500 + 12 + 0;
+  assert.equal(
+    probeWedgeIsCertain({ stuckForMs: 1000, longestHealthySeenGapMs: 0, legitimateReportMs }).isCertain,
+    false,
+    "a second of quiet is shorter than one legitimate report and says nothing"
+  );
+  // And what the detector exists for is untouched: a counter frozen for
+  // minutes is far past any report this connection could legitimately owe.
+  assert.equal(
+    probeWedgeIsCertain({ stuckForMs: 60_000, longestHealthySeenGapMs: 0, legitimateReportMs }).isCertain,
+    true
+  );
+  // A peer whose event loop is late is owed that time as well.
+  assert.equal(
+    probeWedgeIsCertain({
+      stuckForMs: 3000,
+      longestHealthySeenGapMs: 0,
+      legitimateReportMs: 500 + 12 + 5000
+    }).isCertain,
+    false,
+    "a peer frozen for five seconds cannot answer sooner than that"
+  );
+});
+
+test("what is behind is judged in time, not in probes", () => {
+  // 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. Counting outstanding probes therefore measures
+  // the queue, not the association, which is why the count is only printed now.
+  const behind = { proxy: 800, "proxy-control": 800, "proxy-fast": 800 };
+  const mayWait = { proxy: 2000, "proxy-control": 2000, "proxy-fast": 2000 };
+
+  // Far behind in probes, well within the time its own queue is allowed.
+  const healthy = readProbeState(
+    state(
+      { proxy: 40, "proxy-control": 41, "proxy-fast": 42 },
+      { behindMs: behind, allowedWaitMs: mayWait }
+    )
+  );
+  assert.equal(healthy.verdict, "flowing");
+  assert.match(healthy.detail, /800ms of 2000ms/, "both readings belong in the line");
+
+  // The same gaps, the same allowance, and the probe is older than the queue
+  // could account for: that is the association and not the burst.
+  const wedged = readProbeState(
+    state(
+      { proxy: 40, "proxy-control": 41, "proxy-fast": 42 },
+      {
+        behindMs: { proxy: 9000, "proxy-control": 9000, "proxy-fast": 9000 },
+        allowedWaitMs: mayWait
+      }
+    )
+  );
+  assert.equal(wedged.verdict, "association-stopped");
+});
+
+test("with no send time recorded the count still decides", () => {
+  // A probe older than the history kept, or a connection that has just begun:
+  // the reading is absent rather than wrong, and the old comparison stands.
+  const { verdict } = readProbeState(
+    state({ proxy: 40, "proxy-control": 41, "proxy-fast": 42 }, { behindMs: {}, allowedWaitMs: {} })
+  );
+  assert.equal(verdict, "association-stopped");
+});
+
+test("the measured one-way time is preferred over the age of the report", () => {
+  // With the clocks reconciled, the proxy knows how long the probe itself took
+  // to reach the peer. The age of the newest reported probe is the same thing
+  // plus the peer's reporting cadence and the way back — so where both are
+  // known, the measurement wins and its allowance carries neither.
+  const { verdict } = readProbeState(
+    state(
+      { proxy: 40, "proxy-control": 41, "proxy-fast": 42 },
+      {
+        // The age says far behind against its allowance...
+        behindMs: { proxy: 9000, "proxy-control": 9000, "proxy-fast": 9000 },
+        allowedWaitMs: { proxy: 2000, "proxy-control": 2000, "proxy-fast": 2000 },
+        // ...while the probe itself took 300 ms of the 900 its queue may take.
+        oneWayMs: { proxy: 300, "proxy-control": 300, "proxy-fast": 300 },
+        allowedOneWayMs: { proxy: 900, "proxy-control": 900, "proxy-fast": 900 }
+      }
+    )
+  );
+  assert.equal(verdict, "flowing");
+});
+
+test("a one-way time past what the queue can account for is the association", () => {
+  const { verdict } = readProbeState(
+    state(
+      { proxy: 40, "proxy-control": 41, "proxy-fast": 42 },
+      {
+        oneWayMs: { proxy: 12_000, "proxy-control": 12_000, "proxy-fast": 12_000 },
+        allowedOneWayMs: { proxy: 900, "proxy-control": 900, "proxy-fast": 900 }
+      }
+    )
+  );
+  assert.equal(verdict, "association-stopped");
+});

package/test/encode-exit.test.js

@@ -91,3 +91,21 @@ test("every combination answers, and no input produces undefined", () => {
   }
   assert.ok(Object.values(ENCODE_EXIT).includes(classifyEncodeExit()));
 });
+
+test("a run that made nothing has not finished, whatever its exit code", () => {
+  // Field 2026-09-11: a run given #541..#541 was handed a start later than its
+  // own end, wrote 190 bytes that are not a fragment, and exited zero. Making
+  // no segment and being unable to read the directory were the same `null`, and
+  // the second reading — "cannot be contradicted, so it stands" — was applied
+  // to the first.
+  assert.equal(
+    classifyEncodeExit({ code: 0, producedThrough: null, producedCount: 0, lastSegmentIndex: 541 }),
+    ENCODE_EXIT.SHORT
+  );
+  // And the case that reading was written for still stands: nothing readable on
+  // disk is not a claim that nothing was made.
+  assert.equal(
+    classifyEncodeExit({ code: 0, producedThrough: null, producedCount: null, lastSegmentIndex: 623 }),
+    ENCODE_EXIT.COMPLETE
+  );
+});

package/test/keeping-period.test.js

@@ -0,0 +1,83 @@
+/**
+ * @file How long material nobody is using is kept, and where that number comes
+ * from.
+ *
+ * It was three numbers and they contradicted each other: a torrent went at
+ * fifteen minutes while the session it feeds lived to thirty, so between them
+ * there was a session with no source. All three stand for one unmeasured thing
+ * — whether the viewer comes back — so they are one number now, and the thing
+ * they stand for is being measured.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { IDLE_KEEP_MS } from "../services/disk/keep.js";
+import { Returns } from "../services/disk/returns.js";
+
+const MINUTE = 60 * 1000;
+
+test("material outlives the session that reads it", () => {
+  // The contradiction this replaced, stated as the rule it must never break
+  // again: whatever holds a source must not go while something that reads it
+  // is still alive. The session's own period is thirty minutes.
+  const SESSION_TTL_MS = 30 * MINUTE;
+  assert.ok(
+    IDLE_KEEP_MS > SESSION_TTL_MS,
+    "a session would outlive its own source again: material is kept " +
+      `${IDLE_KEEP_MS / MINUTE}min against a session's ${SESSION_TTL_MS / MINUTE}min`
+  );
+});
+
+test("one number, and both kinds of material read it", async () => {
+  // Two guesses about one unknown is what produced the contradiction. Asserted
+  // on the source: a second literal period appearing anywhere is the fault
+  // coming back.
+  const { readFileSync } = await import("node:fs");
+  const path = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const read = (relative) => readFileSync(path.join(here, "..", relative), "utf8");
+
+  assert.match(read("services/torrent-pool.js"), /TORRENT_IDLE_TTL_MS = IDLE_KEEP_MS/);
+  assert.match(read("services/hls-session-manager.js"), /SEGMENT_STORE_IDLE_MS = IDLE_KEEP_MS/);
+});
+
+test("a session opened on material still held is a return, and its age is kept", () => {
+  const returns = new Returns();
+  const now = 10 * 60 * MINUTE;
+
+  returns.note({ lastReadAt: now - 5 * MINUTE, now });
+  returns.note({ lastReadAt: now - 45 * MINUTE, now });
+  returns.note({ lastReadAt: now - 20 * MINUTE, now });
+
+  const shape = returns.shape();
+  assert.equal(shape.warm, 3);
+  assert.equal(shape.cold, 0);
+  assert.equal(shape.medianMs, 20 * MINUTE, "the middle return is not the median");
+  assert.equal(shape.longestMs, 45 * MINUTE);
+});
+
+test("a session opened on material this proxy never had is not a return", () => {
+  const returns = new Returns();
+  const now = 10 * 60 * MINUTE;
+
+  returns.note({ lastReadAt: null, now });
+  returns.note({ lastReadAt: 0, now });
+
+  assert.equal(returns.shape(), null, "an opening with nothing behind it was counted as a return");
+});
+
+test("the reading says what viewers do beside what is being kept", () => {
+  const returns = new Returns();
+  const now = 10 * 60 * MINUTE;
+  assert.equal(returns.describe(IDLE_KEEP_MS), null, "it spoke before it had anything to say");
+
+  returns.note({ lastReadAt: now - 12 * MINUTE, now });
+  returns.note({ lastReadAt: null, now });
+
+  const line = returns.describe(IDLE_KEEP_MS);
+  assert.match(line, /1 session\(s\) opened on material still held/);
+  assert.match(line, /1 on material gone/);
+  assert.match(line, /median 12min after the last read/);
+  assert.match(line, /kept for 60min/);
+});