@torrent-tv/proxy 2.69.2 → 2.71.0

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/memory-budget.test.js

@@ -8,9 +8,12 @@ import {
   watchedFigures
 } from "../services/memory-report.js";
 import {
-  budgetForNewStore,
-  SharedPieceStore,
-  totalStoreBudgetBytes
+  divideAllowance,
+  forgetMachineMemory,
+  machineAllowanceBytes,
+  machineReserveBytes,
+  noteMachineMemory,
+  SharedPieceStore
 } from "../services/piece-store/shared-piece-store.js";
 import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
@@ -19,31 +22,69 @@ import path from "node:path";
 const MEGABYTE = 1024 * 1024;
 const GIGABYTE = 1024 * MEGABYTE;
 
-test("the whole of the torrent stores is bounded, not each one of them", () => {
-  // The failure this replaces: the budget was per torrent, so two torrents took
-  // two of it. Whatever the machine has, the total is one budget.
-  const available = 8 * GIGABYTE;
-  const alone = budgetForNewStore(available, 1);
-  const withThree = budgetForNewStore(available, 3);
-  assert.equal(alone, totalStoreBudgetBytes(available));
-  assert.ok(withThree < alone, "a third store must not be given a first store's share");
-  assert.ok(withThree * 3 <= totalStoreBudgetBytes(available) + 3);
+test("the stores are allowed what the machine has, less what others were seen to need", () => {
+  // Not a share of what is free. A share is a number chosen out of nothing, and
+  // the three that were here until 2026-09-02 — a quarter, a 64 MB floor, a
+  // 512 MB ceiling — all came from one observation of one host on 2026-08-03.
+  // `MemAvailable` is what can be taken ON TOP of what is held, so what the
+  // stores already hold is added back to get the ceiling they could reach.
+  assert.equal(
+    machineAllowanceBytes(2 * GIGABYTE, 300 * MEGABYTE, 0),
+    2 * GIGABYTE + 300 * MEGABYTE
+  );
+  assert.equal(
+    machineAllowanceBytes(2 * GIGABYTE, 300 * MEGABYTE, 500 * MEGABYTE),
+    2 * GIGABYTE - 200 * MEGABYTE
+  );
+  assert.equal(
+    machineAllowanceBytes(100 * MEGABYTE, 0, 4 * GIGABYTE),
+    0,
+    "a reserve larger than everything leaves nothing, and says so rather than going negative"
+  );
 });
 
-test("the budget is a share of what the machine can give, capped", () => {
-  // A quarter of two gigabytes is under the ceiling and is what is taken.
-  assert.equal(totalStoreBudgetBytes(2 * GIGABYTE), 512 * MEGABYTE);
-  // A quarter of one gigabyte is 256 MB — below the ceiling, so not capped.
-  assert.equal(totalStoreBudgetBytes(GIGABYTE), 256 * MEGABYTE);
-  // And it never exceeds the ceiling however much is free.
-  assert.equal(totalStoreBudgetBytes(64 * GIGABYTE), 512 * MEGABYTE);
+test("what to leave for everyone else is measured, starts at nothing, and ages out", () => {
+  // Field 2026-09-02: while this proxy held 76-133 MB the machine's available
+  // memory fell from 2378 MB to 306 MB and came back. That fall was somebody
+  // else's, and it is the quantity to leave room for. On a quiet host the same
+  // reading stays near zero, which is the right answer there.
+  forgetMachineMemory();
+  assert.equal(noteMachineMemory(2378 * MEGABYTE, 100 * MEGABYTE), 0, "nothing is reserved on faith");
+
+  // A fall of 2072 MB while the stores grew by 20 MB: 2052 MB of it was theirs.
+  assert.equal(noteMachineMemory(306 * MEGABYTE, 120 * MEGABYTE), 2052 * MEGABYTE);
+
+  // Memory coming back does not lower what has been seen to be needed — the
+  // spike can happen again, and that is what there has to be room for.
+  assert.equal(noteMachineMemory(3567 * MEGABYTE, 120 * MEGABYTE), 2052 * MEGABYTE);
+
+  // But it does not stand for ever either. A window of observations, not a
+  // high-water: one spike hours ago must stop squeezing the stores, which is
+  // the same mistake the block re-use gap would make with an all-time maximum.
+  for (let quiet = 0; quiet < 60; quiet += 1) {
+    noteMachineMemory(3567 * MEGABYTE, 120 * MEGABYTE);
+  }
+  assert.equal(machineReserveBytes(), 0, "an hour of quiet leaves the spike behind");
 });
 
-test("a machine with almost nothing left still gets a workable floor", () => {
-  // Refusing to serve is worse than exceeding the share, and the memory line
-  // says plainly what is held either way.
-  const tiny = budgetForNewStore(32 * MEGABYTE, 4);
-  assert.equal(tiny, 64 * MEGABYTE);
+test("everyone gets what they asked for while the asks fit", () => {
+  // The usual case by a wide margin: two readers of one film declare 32-192 MB
+  // between them against gigabytes of free memory, so the machine's limit never
+  // binds and the demand is what decides.
+  assert.deepEqual(
+    divideAllowance([100 * MEGABYTE, 50 * MEGABYTE], GIGABYTE),
+    [100 * MEGABYTE, 50 * MEGABYTE]
+  );
+
+  // When they do not fit, each is cut in proportion to what it asked, so a
+  // store wanting little is not cut to make room for one wanting much.
+  const cut = divideAllowance([300 * MEGABYTE, 100 * MEGABYTE], 200 * MEGABYTE);
+  assert.equal(cut[0], 150 * MEGABYTE);
+  assert.equal(cut[1], 50 * MEGABYTE);
+  assert.equal(cut[0] + cut[1], 200 * MEGABYTE);
+
+  assert.deepEqual(divideAllowance([], GIGABYTE), []);
+  assert.deepEqual(divideAllowance([0, 0], 0), [0, 0], "nobody asking takes nothing");
 });
 
 test("the memory line says bytes, and names what it could not measure", () => {
@@ -131,7 +172,7 @@ test("a thread's reading leaves out what belongs to the process", () => {
   assert.doesNotMatch(line, /machine has/);
 });
 
-test("a store's allowance follows the machine, and never passes its reservation", async () => {
+test("a store's allowance follows the machine, in both directions", async () => {
   // The defect: a store created on an idle machine kept an idle machine's
   // allowance for life and went on growing into memory the host no longer had.
   const directory = await mkdtemp(path.join(os.tmpdir(), "budget-revision-"));
@@ -149,11 +190,14 @@ test("a store's allowance follows the machine, and never passes its reservation"
     assert.ok(lowered.ceilingBytes < born, "a busier machine buys fewer slots");
     assert.equal(store.stats().budgetBytes, lowered.ceilingBytes, "the line says what is allowed now");
 
-    // The machine empties again: the ceiling may rise, but never above the
-    // reservation, because `maxByteLength` was fixed from it and `grow()`
-    // cannot pass it.
+    // The machine empties again: the ceiling rises with it, PAST where this
+    // store started. Until 2026-09-02 it could not — the ceiling was capped at
+    // a figure computed once in the constructor, so a torrent opened while the
+    // machine was full kept a small allowance for its whole life however much
+    // memory was freed afterwards.
     const raised = store.reviseGrowthCeiling(1024 * 1024 * 1024);
-    assert.equal(raised.ceilingBytes, born, "the reservation is the hard limit");
+    assert.ok(raised.ceilingBytes > born, "an emptier machine buys more slots than it started with");
+    assert.equal(store.stats().budgetBytes, raised.ceilingBytes);
   } finally {
     await new Promise((resolve) => store.destroy(resolve));
     await rm(directory, { recursive: true, force: true });

package/test/piece-store-eviction.test.js

@@ -181,3 +181,223 @@ test("the store says why it spills: what is asked of it, what it had to take, ho
     await fs.rm(directory, { recursive: true, force: true });
   }
 });
+
+test("a piece nobody has declared does not push out one that is being read", async () => {
+  const capacity = 4;
+  const { store, directory } = await makeStore(capacity);
+  try {
+    // A reader declares the pieces it will need, and they are put in memory.
+    store.protectRange("video", 0, 3);
+    for (let index = 0; index < 4; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+    assert.equal(store.stats().resident, capacity, "the declared window fills the store");
+
+    // Now pieces arrive that the download fetched ahead of every reader. Before
+    // 2026-09-02 each of them claimed a slot and evicted one of the four above,
+    // which was then read back from disk moments later: 6565 spills and 7575
+    // revivals in 44 minutes, 53.6% of reads served from memory.
+    for (let index = 100; index < 110; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+
+    const stats = store.stats();
+    assert.equal(stats.admittedToDisk, 10, "every undeclared arrival went straight to disk");
+    assert.equal(stats.admittedOutsideWindow, 10);
+    assert.equal(stats.admittedInsideWindow, 4);
+    assert.equal(stats.spills, 0, "and nothing had to be pushed out to make room");
+
+    // The declared pieces are still in memory, and every piece reads back as
+    // itself from whichever tier holds it.
+    assert.equal(stats.resident, capacity);
+    for (const index of [0, 1, 2, 3, 100, 105, 109]) {
+      const bytes = await get(store, index);
+      assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
+    }
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("before any reader has declared anything, an arriving piece still goes to memory", async () => {
+  const { store, directory } = await makeStore(4);
+  try {
+    // No window declared: there is no basis for calling a piece unwanted, so
+    // the store behaves as it always did. This is the initial download, and the
+    // warm-up fetches of the header and the tail.
+    for (let index = 0; index < 8; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+    const stats = store.stats();
+    assert.equal(stats.admittedToDisk, 0, "nothing was refused memory on a guess");
+    assert.equal(stats.admittedOutsideWindow, 8);
+    assert.ok(stats.spills > 0, "the store filled and evicted, as it did before");
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("the store asks for what its readers declared, and for a whole window at least", async () => {
+  const { store, directory } = await makeStore(64);
+  try {
+    // With nobody reading there is no demand to speak of, so the store asks for
+    // what it is already allowed and the first revision after a read begins
+    // brings it down.
+    const idle = store.wantedBytes;
+    assert.equal(idle, store.stats().budgetBytes);
+
+    // Two readers of one file — picture and sound — overlapping by
+    // construction. The ask is their union, not their sum.
+    store.protectRange("video", 10, 29);
+    store.protectRange("audio", 25, 44);
+    assert.equal(store.wantedBytes, 35 * PIECE, "10..44 is thirty-five pieces, not forty");
+
+    // One reader with a window wider than the union of nothing else: the ask
+    // never falls below a single window, or that reader's read cannot complete
+    // at all — every resident piece ends up pinned and the read returns zero
+    // bytes.
+    store.releaseProtection("audio");
+    store.releaseProtection("video");
+    store.protectRange("video", 0, 49);
+    assert.equal(store.wantedBytes, 50 * PIECE);
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a block is re-used instead of a new one being allocated for every piece", async () => {
+  const capacity = 4;
+  const { store, directory } = await makeStore(capacity);
+  try {
+    // Twenty pieces through a store that may hold four. Before 2026-09-02 that
+    // was twenty allocations of a piece each, every one of them released only
+    // when the collector got to it — 7575 of them in 44 minutes in the field,
+    // and 1.86 GB held while the store's own accounting said 352 MB.
+    for (let index = 0; index < 20; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+
+    const stats = store.stats();
+    assert.ok(
+      stats.blocksAllocated <= capacity,
+      `the pool never exceeds the allowance: ${stats.blocksAllocated} blocks for ${capacity} slots`
+    );
+    assert.equal(stats.committedBytes, stats.blocksAllocated * PIECE);
+    assert.equal(stats.returnedWhilePinned, 0);
+    assert.ok(stats.reuseGapMs !== null, "blocks were taken from the free list, not freshly made");
+
+    // And every piece still reads back as itself: a re-used block must not
+    // carry the last piece's bytes into the next one.
+    for (let index = 0; index < 20; index += 1) {
+      const bytes = await get(store, index);
+      assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
+    }
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a spare block is given up once it has sat longer than the store's own working rhythm", async () => {
+  const { store, directory } = await makeStore(8);
+  try {
+    for (let index = 0; index < 12; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+    // The allowance falls: pieces are written out and their blocks fall spare.
+    store.reviseGrowthCeiling(2 * PIECE);
+    const spare = store.stats().blocksFree;
+
+    // Nothing is given up while the blocks are younger than the longest wait
+    // this store has actually seen between a block falling free and being
+    // wanted again.
+    assert.equal(store.sweepFreeBlocks(Date.now()), 0, "a block in use moments ago is not spare");
+    assert.equal(store.stats().blocksFree, spare);
+
+    // An hour later they plainly are.
+    const released = store.sweepFreeBlocks(Date.now() + 3_600_000);
+    assert.equal(released, spare);
+    assert.equal(store.stats().blocksFree, 0);
+    assert.equal(store.stats().blocksReleased, released);
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("evicting a piece the disk already holds costs no second write", async () => {
+  const { store, directory } = await makeStore(2);
+  try {
+    // Three pieces through two slots: piece 0 is written out.
+    for (let index = 0; index < 3; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+    const written = store.stats().spills;
+    assert.ok(written > 0);
+    assert.equal(store.stats().spillsSkipped, 0, "the first write of a piece is a real one");
+
+    // Read it back — it returns to memory and the copy stays on disk. Evicting
+    // it again writes bytes that are already there, byte for byte, because only
+    // `put` removes the disk copy and no `put` has happened.
+    assert.ok((await get(store, 0)).equals(pieceOf(0)));
+    for (let index = 10; index < 13; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+    assert.ok(store.stats().spillsSkipped > 0, "the second write of the same bytes is skipped");
+
+    // And the piece still comes back correctly from the disk copy.
+    assert.ok((await get(store, 0)).equals(pieceOf(0)));
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a store whose readers have gone asks for nothing, one that never had them keeps its opening", async () => {
+  const { store, directory } = await makeStore(16);
+  try {
+    // Never had a reader: this is the initial download and the warm-up fetches
+    // of the header and the tail, with a read on its way.
+    const opening = store.wantedBytes;
+    assert.equal(opening, store.stats().budgetBytes);
+
+    store.protectRange("video", 0, 9);
+    assert.equal(store.wantedBytes, 10 * PIECE);
+
+    // The read ends. Its torrent sits until the pool's idle timer removes it,
+    // and that timer needs a refcount of zero and can be a quarter of an hour
+    // away. Holding the pieces for a reader that has gone is memory taken from
+    // the machine for nothing.
+    store.releaseProtection("video");
+    assert.ok(store.wantedBytes < opening, "a store with no readers left asks for nothing");
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("the allowance is never cut below one reader's whole window", async () => {
+  const { store, directory } = await makeStore(16);
+  try {
+    store.protectRange("video", 0, 9);
+    // The machine says this store may have two pieces. Obeying that would leave
+    // it unable to finish the read it is serving: every resident piece pinned,
+    // zero bytes returned, and ffmpeg taking that for the end of the file —
+    // which killed every encoder on that file in the field on 2026-08-15.
+    const revised = store.reviseGrowthCeiling(2 * PIECE);
+    assert.equal(revised.ceilingBytes, 10 * PIECE, "one whole window is the floor");
+    assert.equal(revised.belowAWindow, true, "and the store says the share was smaller than that");
+
+    // With no reader there is no window to protect and the share is obeyed.
+    store.releaseProtection("video");
+    const obeyed = store.reviseGrowthCeiling(2 * PIECE);
+    assert.equal(obeyed.ceilingBytes, 2 * PIECE);
+    assert.equal(obeyed.belowAWindow, false);
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

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"
   );