@torrent-tv/proxy 2.70.0 → 2.71.1

package/test/demand-register.test.js

@@ -0,0 +1,195 @@
+/**
+ * @file What is wanted, by whom, and how urgently.
+ *
+ * These are the rules the download layer and the memory store both read, so a
+ * defect here is a defect in two places at once. Everything is numbers: no
+ * torrent, no library, no piece store.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { DemandRegister } from "../services/demand/DemandRegister.js";
+import { unionOf, Window } from "../services/demand/Window.js";
+import {
+  isConditional,
+  mayDisplaceSlowPeer,
+  selectionPriority,
+  Urgency
+} from "../services/demand/Urgency.js";
+import { nearestFirst, piecesNeededFor, piecesOf, piecesWithin } from "../services/demand/pieces.js";
+
+const MEGABYTE = 1024 * 1024;
+
+test("a window states bytes and refuses what it cannot mean", () => {
+  const window = new Window({
+    claimant: "video", fileIndex: 0, byteStart: 100, byteEnd: 199, urgency: Urgency.NEAR
+  });
+  assert.equal(window.byteLength, 100, "inclusive at both ends");
+
+  assert.throws(() => new Window({
+    claimant: "", fileIndex: 0, byteStart: 0, byteEnd: 1, urgency: 0
+  }), /claimant/, "a window nobody can release is a leak with a name missing");
+  assert.throws(() => new Window({
+    claimant: "video", fileIndex: 0, byteStart: 200, byteEnd: 100, urgency: 0
+  }), /Byte end/);
+  assert.throws(() => new Window({
+    claimant: "video", fileIndex: -1, byteStart: 0, byteEnd: 1, urgency: 0
+  }), /File index/);
+});
+
+test("windows of different files are never merged", () => {
+  const register = new DemandRegister();
+  register.state({ claimant: "a", fileIndex: 0, byteStart: 0, byteEnd: 99, urgency: Urgency.NEAR });
+  register.state({ claimant: "b", fileIndex: 1, byteStart: 0, byteEnd: 99, urgency: Urgency.NEAR });
+
+  // Byte 50 of file 0 and byte 50 of file 1 are different bytes. Two viewers on
+  // two episodes of one release is the ordinary case, not an edge one.
+  assert.deepEqual(register.union(), [
+    { byteStart: 0, byteEnd: 99 },
+    { byteStart: 0, byteEnd: 99 }
+  ]);
+  assert.deepEqual(register.files(), [0, 1]);
+});
+
+test("the union of overlapping windows is their union, not their sum", () => {
+  // Picture and sound are two readers of one file and their windows overlap by
+  // construction. Adding them would report a demand that is not there.
+  assert.deepEqual(
+    unionOf([
+      { byteStart: 0, byteEnd: 99 },
+      { byteStart: 50, byteEnd: 149 }
+    ]),
+    [{ byteStart: 0, byteEnd: 149 }]
+  );
+  // Touching ranges are one run: 0-99 and 100-199 have nothing between them.
+  assert.deepEqual(
+    unionOf([
+      { byteStart: 100, byteEnd: 199 },
+      { byteStart: 0, byteEnd: 99 }
+    ]),
+    [{ byteStart: 0, byteEnd: 199 }]
+  );
+  assert.deepEqual(
+    unionOf([
+      { byteStart: 0, byteEnd: 99 },
+      { byteStart: 200, byteEnd: 299 }
+    ]),
+    [{ byteStart: 0, byteEnd: 99 }, { byteStart: 200, byteEnd: 299 }],
+    "a gap between them is a gap"
+  );
+});
+
+test("a claimant states one window, and restating replaces it", () => {
+  const register = new DemandRegister();
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: 99, urgency: Urgency.NEAR });
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 100, byteEnd: 199, urgency: Urgency.NEAR });
+
+  // A reader walking a film restates its window many times a second. If those
+  // accumulated, the download set would be the whole file within a minute.
+  assert.equal(register.size, 1);
+  assert.deepEqual(register.union(0), [{ byteStart: 100, byteEnd: 199 }]);
+});
+
+test("a withdrawal names its own claimant and nothing else", () => {
+  const register = new DemandRegister();
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: 99, urgency: Urgency.NEAR });
+  register.state({ claimant: "audio", fileIndex: 0, byteStart: 0, byteEnd: 99, urgency: Urgency.NEAR });
+
+  assert.equal(register.withdraw("audio"), true);
+  assert.equal(register.withdraw("audio"), false, "a second release withdraws nothing");
+  assert.equal(register.withdraw("nobody"), false, "a stray release matches nothing");
+  assert.equal(register.size, 1, "and video still wants what it wanted");
+});
+
+test("the speculative levels are stated only while nothing urgent is missing", () => {
+  const register = new DemandRegister();
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: 99, urgency: Urgency.BLOCKED });
+  register.state({ claimant: "fill", fileIndex: 0, byteStart: 1000, byteEnd: 9999, urgency: Urgency.TAIL });
+  register.state({ claimant: "back", fileIndex: 0, byteStart: 0, byteEnd: 999, urgency: Urgency.BEHIND });
+
+  // Something urgent is missing: the speculative levels are not stated at all.
+  // Withdrawn, not lowered — a withdrawn window is not in the download set, so
+  // a peer with nothing urgent to give cannot fall through to it and spend the
+  // shared link on a piece nobody is waiting for.
+  assert.deepEqual(
+    register.levelsToState((window) => window.urgency !== Urgency.BLOCKED),
+    [Urgency.BLOCKED, Urgency.NEAR, Urgency.AHEAD]
+  );
+
+  // Everything urgent has arrived: they are stated, in order.
+  assert.deepEqual(
+    register.levelsToState(() => true),
+    [Urgency.BLOCKED, Urgency.NEAR, Urgency.AHEAD, Urgency.TAIL, Urgency.BEHIND]
+  );
+
+  // The tail is complete but the gap behind is not: the gap stays stated and
+  // nothing below it exists to withhold.
+  assert.deepEqual(
+    register.levelsToState((window) => window.urgency !== Urgency.BEHIND),
+    [Urgency.BLOCKED, Urgency.NEAR, Urgency.AHEAD, Urgency.TAIL, Urgency.BEHIND]
+  );
+});
+
+test("only the level being waited on may take a block from a slow peer", () => {
+  assert.equal(mayDisplaceSlowPeer(Urgency.BLOCKED), true);
+  for (const urgency of [Urgency.NEAR, Urgency.AHEAD, Urgency.TAIL, Urgency.BEHIND]) {
+    assert.equal(mayDisplaceSlowPeer(urgency), false);
+  }
+});
+
+test("the library is given the only distinction it keeps", () => {
+  // Measured against the vendored 2.8.5: distinct non-zero priorities order the
+  // selection list once and are round-robined afterwards by `shufflePriority`.
+  // Zero is the only value that stays put, always last.
+  assert.equal(selectionPriority(Urgency.BLOCKED), 1);
+  assert.equal(selectionPriority(Urgency.NEAR), 1);
+  assert.equal(selectionPriority(Urgency.AHEAD), 1);
+  assert.equal(selectionPriority(Urgency.TAIL), 0);
+  assert.equal(selectionPriority(Urgency.BEHIND), 0);
+
+  assert.equal(isConditional(Urgency.AHEAD), false);
+  assert.equal(isConditional(Urgency.TAIL), true);
+});
+
+test("bytes become pieces in one place, and a partial piece is a whole piece", () => {
+  const pieceLength = 4 * MEGABYTE;
+  // A file starting one piece into the torrent, wanting its first byte.
+  assert.deepEqual(
+    piecesOf({ fileOffset: pieceLength, byteStart: 0, byteEnd: 0, pieceLength }),
+    { from: 1, to: 1 }
+  );
+  // A range ending one byte into the next piece still needs that whole piece:
+  // the protocol delivers and verifies nothing smaller.
+  assert.deepEqual(
+    piecesOf({ fileOffset: 0, byteStart: 0, byteEnd: pieceLength, pieceLength }),
+    { from: 0, to: 1 }
+  );
+  assert.equal(piecesOf({ fileOffset: 0, byteStart: 10, byteEnd: 5, pieceLength }), null);
+  assert.equal(piecesOf({ fileOffset: 0, byteStart: 0, byteEnd: 1, pieceLength: 0 }), null);
+});
+
+test("a budget buys whole places, and a window needs one more than it measures", () => {
+  const pieceLength = 16 * MEGABYTE;
+  // The failure this rounding hid: 64 MB of allowance is four places, and two
+  // readers asking for 96 MB each want six. Counted in bytes the shortage is
+  // plain; counted in floored pieces it is not.
+  assert.equal(piecesWithin(64 * MEGABYTE, pieceLength), 4);
+  assert.equal(piecesNeededFor(96 * MEGABYTE, pieceLength), 7, "six, plus the one it can straddle");
+  assert.equal(piecesWithin(0, pieceLength), 0);
+  assert.equal(piecesNeededFor(0, pieceLength), 0);
+});
+
+test("the gap behind the playhead is stated nearest first", () => {
+  // WebTorrent walks a selection from its start upwards, so one claim over
+  // everything behind the viewer would be fetched from the beginning of the
+  // file — the end furthest from where a backward seek lands.
+  const ranges = nearestFirst({ byteStart: 0, byteEnd: 999, parts: 4 });
+  assert.equal(ranges.length, 4);
+  assert.equal(ranges[0].byteEnd, 999, "the part nearest the playhead comes first");
+  assert.equal(ranges[ranges.length - 1].byteStart, 0, "and the furthest comes last");
+  for (const range of ranges) {
+    assert.ok(range.byteStart <= range.byteEnd);
+  }
+  assert.deepEqual(nearestFirst({ byteStart: 10, byteEnd: 5, parts: 2 }), []);
+});

package/test/fastest-wires.test.js

@@ -91,13 +91,35 @@ test("a refusal is counted as a refusal", () => {
   const result = askFastestWiresFor(torrent, 11);
   assert.equal(result.asked, 0);
   assert.equal(result.considered, 2);
+  // Refused, but not because every block was spoken for — this stub has no
+  // reservations at all. The two reasons are different and only the second is
+  // the one WebTorrent's displacement thresholds decide.
+  assert.equal(result.refusedWhileReserved, 0);
+});
+
+test("a refusal with every block already reserved is counted separately", () => {
+  // The interesting refusal: a fast peer we picked was turned away because
+  // every block belongs to somebody else and displacement did not happen. The
+  // thresholds that decide it are constants in the library — the asker above
+  // 16 KB/s, the holder below 48 KB/s and twice as slow — so a holder at
+  // 50 KB/s is never displaced however long the piece has waited. This number
+  // is what would justify replacing that rule.
+  const { torrent } = torrentWith([wire({ speed: 500 })], { refuse: true });
+  torrent.pieces = [];
+  torrent.pieces[11] = { reserve: () => -1, cancel: () => undefined };
+  const result = askFastestWiresFor(torrent, 11);
+  assert.equal(result.asked, 0);
+  assert.equal(result.refusedWhileReserved, 1);
 });
 
 test("a build without the request entry is reported, not silently skipped", () => {
   assert.equal(canPlaceRequests({ wires: [] }), false);
   assert.equal(canPlaceRequests({ wires: [], _request: () => true }), true);
   const result = askFastestWiresFor({ wires: [wire({ speed: 1 })] }, 1);
-  assert.deepEqual(result, { asked: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 });
+  assert.deepEqual(
+    result,
+    { asked: 0, refusedWhileReserved: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 }
+  );
 });
 
 test("a wire that cannot say how fast it is ranks last rather than throwing", () => {

package/test/read-bands.test.js

@@ -11,10 +11,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { bandWidthsFrom, bandsFrom, sameBands } from "../services/torrent-worker/piece-reader.js";
+import { Urgency } from "../services/demand/Urgency.js";
 
 const PIECE = 8 * 1024 * 1024;
 
-test("the urgent band keeps the highest priority, and the lead bands come behind it in order", () => {
+test("the urgent band is the one being read, and the lead bands come behind it in order", () => {
   const bands = bandsFrom({
     urgent: { from: 100, to: 103 },
     pieceIndex: 100,
@@ -26,15 +27,15 @@ test("the urgent band keeps the highest priority, and the lead bands come behind
   assert.deepEqual(
     bands,
     [
-      { from: 100, to: 103, priority: 4 },
-      { from: 104, to: 108, priority: 3 },
-      { from: 109, to: 128, priority: 2 }
+      { from: 100, to: 103, urgency: Urgency.NEAR },
+      { from: 104, to: 108, urgency: Urgency.AHEAD },
+      { from: 109, to: 128, urgency: Urgency.AHEAD }
     ],
     "no gap, no overlap, and each band strictly less urgent than the one in front"
   );
 });
 
-test("no priority is zero, because the library's own whole-file fill sits there", () => {
+test("no band is speculative while the reader is still walking the file", () => {
   const bands = bandsFrom({
     urgent: { from: 0, to: 1 },
     pieceIndex: 0,
@@ -44,7 +45,7 @@ test("no priority is zero, because the library's own whole-file fill sits there"
   });
 
   assert.ok(
-    bands.every((band) => band.priority > 0),
+    bands.every((band) => band.urgency <= Urgency.AHEAD),
     "a band at 0 would be indistinguishable from the background fill of the whole torrent"
   );
 });
@@ -72,7 +73,7 @@ test("what was never downloaded behind the viewer is not asked for until the lea
   });
   assert.deepEqual(
     covered[covered.length - 1],
-    { from: 0, to: 49, priority: 1 },
+    { from: 0, to: 49, urgency: Urgency.BEHIND },
     "once there is nothing left ahead, the gap behind the viewer is worth filling"
   );
 });
@@ -121,12 +122,18 @@ test("with nothing measured yet both lead bands fall back to the reader's own wi
 });
 
 test("an unchanged claim is recognised, so it is not released and re-made on every read", () => {
-  const bands = [{ from: 1, to: 2, priority: 4 }, { from: 3, to: 9, priority: 3 }];
+  const bands = [
+    { from: 1, to: 2, urgency: Urgency.NEAR },
+    { from: 3, to: 9, urgency: Urgency.AHEAD }
+  ];
 
   assert.equal(sameBands(bands, [...bands.map((band) => ({ ...band }))]), true);
-  assert.equal(sameBands(bands, [{ from: 1, to: 2, priority: 4 }]), false);
+  assert.equal(sameBands(bands, [{ from: 1, to: 2, urgency: Urgency.NEAR }]), false);
   assert.equal(
-    sameBands(bands, [{ from: 1, to: 2, priority: 4 }, { from: 3, to: 9, priority: 2 }]),
+    sameBands(bands, [
+      { from: 1, to: 2, urgency: Urgency.NEAR },
+      { from: 3, to: 9, urgency: Urgency.BEHIND }
+    ]),
     false,
     "the same range at another urgency is a different claim"
   );

package/test/read-window.test.js

@@ -62,11 +62,13 @@ async function recordingTorrent({ pieceCount, present = () => true }) {
     bitfield: { get: (index) => present(index) },
     files: [{ offset: 0, length: totalLength, name: "file.bin" }],
     _critical: [],
+    _selections: { _items: [] },
     calls,
     held,
     _select(from, to, _priority, _notify, isStreamSelection) {
       calls.push({ call: "select", from, to, stream: isStreamSelection === true });
       held.push(`${from}-${to}`);
+      this._selections._items.push({ from, to });
     },
     _deselect(from, to, isStreamSelection) {
       calls.push({ call: "deselect", from, to, stream: isStreamSelection === true });
@@ -74,6 +76,10 @@ async function recordingTorrent({ pieceCount, present = () => true }) {
       if (at >= 0) {
         held.splice(at, 1);
       }
+      const item = this._selections._items.findIndex((one) => one.from === from && one.to === to);
+      if (item >= 0) {
+        this._selections._items.splice(item, 1);
+      }
     },
     critical(from, to) {
       calls.push({ call: "critical", from, to });
@@ -181,7 +187,7 @@ test("an abandoned read leaves nothing selected", async () => {
   }
 });
 
-test("two readers add up, and one leaving takes only its own window", async () => {
+test("two readers add up, and one leaving takes only its own", async () => {
   const { torrent, store, directory } = await recordingTorrent({ pieceCount: 8000 });
   try {
     const head = readFragments({
@@ -195,18 +201,24 @@ test("two readers add up, and one leaving takes only its own window", async () =
     (await head.next()).value.release();
     (await tail.next()).value.release();
 
-    assert.equal(torrent.held.length, 2, "the two readers did not both hold a window");
-    const [headWindow, tailWindow] = torrent.held;
+    // Not a count: each reader states several bands by level, and two readers
+    // wanting the same pieces are one instruction. What matters is that both
+    // are represented and that leaving removes only what leaving should.
+    const pieceOf = (range) => Number(range.split("-")[0]);
+    const held = [...torrent.held];
+    assert.ok(held.some((range) => pieceOf(range) < 4000), "the head reader holds nothing");
+    assert.ok(held.some((range) => pieceOf(range) >= 4000), "the tail reader holds nothing");
 
     await tail.return();
-    assert.deepEqual(
-      torrent.held,
-      [headWindow],
-      `leaving reader took the wrong window (expected to remove ${tailWindow})`
+    const after = [...torrent.held];
+    assert.ok(
+      after.some((range) => pieceOf(range) < 4000),
+      "the head reader's window went with the tail reader"
     );
+    assert.ok(after.length < held.length, "the tail reader took nothing away when it left");
 
     await head.return();
-    assert.deepEqual(torrent.held, []);
+    assert.deepEqual(torrent.held, [], "the last reader left something behind");
   } finally {
     store.destroy(() => undefined);
     await fs.rm(directory, { recursive: true, force: true });

package/test/swarm-selection.test.js

@@ -0,0 +1,220 @@
+/**
+ * @file The one place that speaks to WebTorrent.
+ *
+ * Driven against a stub torrent shaped like the vendored 2.8.5: a selection
+ * list it can be asked about, a bitfield saying what has arrived, and the
+ * private `_select`/`_deselect` the real one exposes.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { DemandRegister } from "../services/demand/DemandRegister.js";
+import { Urgency } from "../services/demand/Urgency.js";
+import { SwarmSelection } from "../services/download/SwarmSelection.js";
+
+const PIECE = 1024;
+
+/**
+ * @param {object} [params]
+ * @param {number[]} [params.have] - Pieces that have arrived.
+ * @param {number} [params.files] - How many files, each ten pieces long.
+ * @returns {object}
+ */
+function stubTorrent({ have = [], files = 1 } = {}) {
+  const arrived = new Set(have);
+  const items = [];
+  return {
+    pieceLength: PIECE,
+    store: null,
+    files: Array.from({ length: files }, (unused, index) => ({
+      offset: index * 10 * PIECE,
+      length: 10 * PIECE
+    })),
+    bitfield: { get: (index) => arrived.has(index) },
+    _critical: [],
+    _selections: { _items: items },
+    calls: { select: [], deselect: [], critical: [] },
+    _select(from, to, priority, notify, isStream) {
+      this.calls.select.push({ from, to, priority, isStream });
+      items.push({ from, to, priority });
+    },
+    _deselect(from, to) {
+      this.calls.deselect.push({ from, to });
+      const at = items.findIndex((item) => item.from === from && item.to === to);
+      if (at >= 0) {
+        items.splice(at, 1);
+      }
+    },
+    critical(from, to) {
+      this.calls.critical.push({ from, to });
+      for (let index = from; index <= to; index += 1) {
+        this._critical[index] = true;
+      }
+    },
+    /** Pretend the library dropped a satisfied selection, which it does. */
+    forget(from, to) {
+      const at = items.findIndex((item) => item.from === from && item.to === to);
+      if (at >= 0) {
+        items.splice(at, 1);
+      }
+    }
+  };
+}
+
+test("nothing is asked of the swarm until somebody states a need", () => {
+  const torrent = stubTorrent();
+  const selection = new SwarmSelection({ torrent, register: new DemandRegister() });
+
+  assert.deepEqual(selection.reconcile(), { stated: 0, withdrawn: 0 });
+  assert.equal(torrent.calls.select.length, 0);
+});
+
+test("two viewers of one film are two instructions, and both are urgent", () => {
+  const torrent = stubTorrent();
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  // One stopped at the start, one stopped further in. Both pictures are still.
+  register.state({ claimant: "v1", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.BLOCKED });
+  register.state({ claimant: "v2", fileIndex: 0, byteStart: 5 * PIECE, byteEnd: 6 * PIECE - 1, urgency: Urgency.BLOCKED });
+  selection.reconcile();
+
+  assert.deepEqual(torrent.calls.select, [
+    { from: 0, to: 0, priority: 1, isStream: true },
+    { from: 5, to: 5, priority: 1, isStream: true }
+  ]);
+  // Both may take a block from a slow peer, and the mark spans both.
+  assert.deepEqual(torrent.calls.critical, [{ from: 0, to: 5 }]);
+});
+
+test("the same pieces wanted by two claimants are one instruction", () => {
+  const torrent = stubTorrent();
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  // Picture and sound of one viewer read the same file and overlap.
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.NEAR });
+  register.state({ claimant: "audio", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.NEAR });
+  const first = selection.reconcile();
+
+  assert.equal(first.stated, 1, "one range, told once");
+  assert.equal(torrent.calls.select.length, 1);
+});
+
+test("the speculative levels are withdrawn whole the moment something urgent is missing", () => {
+  const torrent = stubTorrent({ have: [0] });
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.NEAR });
+  register.state({ claimant: "fill", fileIndex: 0, byteStart: 5 * PIECE, byteEnd: 9 * PIECE - 1, urgency: Urgency.TAIL });
+  selection.reconcile();
+
+  assert.equal(selection.statedRanges().length, 2, "nothing urgent is missing, so the tail is stated");
+  assert.ok(torrent.calls.select.some((call) => call.priority === 0), "and it is stated as zero");
+
+  // The viewer moves on to a piece that has not arrived.
+  register.state({ claimant: "video", fileIndex: 0, byteStart: PIECE, byteEnd: 2 * PIECE - 1, urgency: Urgency.NEAR });
+  selection.reconcile();
+
+  assert.deepEqual(
+    selection.statedRanges().map((range) => range.priority),
+    [1],
+    "the tail is out of the download set entirely, not lowered — a peer with nothing urgent to give must not be able to fall through to it"
+  );
+  assert.ok(torrent.calls.deselect.length > 0);
+});
+
+test("a selection the library drops once satisfied is stated again", () => {
+  const torrent = stubTorrent();
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.NEAR });
+  selection.reconcile();
+  assert.equal(torrent.calls.select.length, 1);
+
+  // Nothing changed: no second instruction.
+  selection.reconcile();
+  assert.equal(torrent.calls.select.length, 1);
+
+  // WebTorrent removes a selection once every piece in it has arrived, and says
+  // nothing about having done so. The window is still wanted.
+  torrent.forget(0, 0);
+  selection.reconcile();
+  assert.equal(torrent.calls.select.length, 2, "stated again, because the library had let it go");
+});
+
+test("a claimant that withdraws takes its instruction with it", () => {
+  const torrent = stubTorrent();
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.BLOCKED });
+  selection.reconcile();
+  register.withdraw("video");
+  const after = selection.reconcile();
+
+  assert.equal(after.withdrawn, 1);
+  assert.equal(selection.statedRanges().length, 0);
+  // And the displacement mark goes with it: WebTorrent never clears it itself,
+  // so a reader walking a film would leave every piece of it marked.
+  assert.equal(torrent._critical.some((marked) => marked === true), false);
+});
+
+test("a window is bounded by its own file, so it cannot claim the next one", () => {
+  const torrent = stubTorrent({ files: 3 });
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  // Asking past the end of file 1. File 1 occupies pieces 10-19.
+  register.state({
+    claimant: "video", fileIndex: 1, byteStart: 0, byteEnd: 100 * PIECE, urgency: Urgency.NEAR
+  });
+  selection.reconcile();
+
+  assert.deepEqual(torrent.calls.select, [{ from: 10, to: 19, priority: 1, isStream: true }]);
+});
+
+test("releasing everything leaves the library holding nothing of ours", () => {
+  const torrent = stubTorrent();
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register });
+
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: 3 * PIECE, urgency: Urgency.BLOCKED });
+  selection.reconcile();
+  selection.releaseAll();
+
+  assert.equal(torrent._selections._items.length, 0);
+  assert.equal(selection.statedRanges().length, 0);
+  assert.equal(torrent._critical.some((marked) => marked === true), false);
+});
+
+test("the store is told what will be read soon, from the same stated needs", () => {
+  const torrent = stubTorrent();
+  const protectedBy = new Map();
+  torrent.store = {
+    protectRange: (claimant, from, to) => protectedBy.set(claimant, `${from}-${to}`),
+    releaseProtection: (claimant) => protectedBy.delete(claimant)
+  };
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register, findStore: () => torrent.store });
+
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.NEAR });
+  register.state({ claimant: "fill", fileIndex: 0, byteStart: 5 * PIECE, byteEnd: 9 * PIECE - 1, urgency: Urgency.TAIL });
+  selection.reconcile();
+
+  // One statement, two views of it. Until 2026-09-02 a reader said the same
+  // thing twice — once to the store for memory, once to the torrent for
+  // download — and a third piece of code read the first to rebuild the second.
+  assert.equal(protectedBy.get("video"), "0-0");
+  // But only the urgent levels: memory holds what will be READ soon, and the
+  // tail is fetched speculatively. Protecting it would push out a piece the
+  // decoder is about to want.
+  assert.equal(protectedBy.has("fill"), false);
+
+  register.withdraw("video");
+  selection.reconcile();
+  assert.equal(protectedBy.size, 0, "a reader that withdrew still held memory");
+});