@torrent-tv/proxy 2.69.1 → 2.70.0

package/services/torrent-worker/worker.js

@@ -39,7 +39,8 @@ import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../memory-report.js"
 // 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, pieceBufferCollection, reviseStoreBudgets } = await import("../piece-store/shared-piece-store.js");
+const { collectStoreStats, machineReserveBytes, pieceBufferCollection, reviseStoreBudgets } =
+  await import("../piece-store/shared-piece-store.js");
 
 // Resolved before the client exists, because the client builds its DHT in its
 // own constructor and the addresses have to be in hand by then. Awaiting here
@@ -541,6 +542,9 @@ startMemoryReport({
 
 const STORE_REPORT_INTERVAL_MS = 60_000;
 
+/** Last reported reserve, so an unchanged one stays silent. */
+let lastReserveBytes = 0;
+
 /** Last reported figures per store, so unchanged ones stay silent. */
 const lastReported = new Map();
 
@@ -548,12 +552,24 @@ setInterval(() => {
   // What the machine can spare NOW, not what it could spare when each store was
   // created. With per-piece buffers a lowered ceiling is honoured immediately:
   // excess pieces are evicted to disk and their memory is reclaimable.
+  // What the machine has been seen to need for everything that is not us. It
+  // starts at nothing and grows only on evidence, so it is worth saying when it
+  // moves — it is the one term of the budget that comes from observation of
+  // other processes rather than from our own readers.
+  const reserveBefore = machineReserveBytes();
   for (const revised of reviseStoreBudgets()) {
     if (revised.evicted > 0) {
       log(
         `piece-store "${revised.name.slice(0, 40)}": allowance is now ` +
-        `${Math.round(revised.ceilingBytes / 1048576)}MB, evicted ${revised.evicted} piece(s) to meet it — ` +
-        `now ${Math.round(revised.committedBytes / 1048576)}MB committed`
+        `${Math.round(revised.ceilingBytes / 1048576)}MB, evicted ${revised.evicted} piece(s) to meet it` +
+        (revised.releasedBlocks > 0 ? `, gave back ${revised.releasedBlocks} block(s) of memory` : "") +
+        ` — now ${Math.round(revised.committedBytes / 1048576)}MB committed`
+      );
+    } else if (revised.belowAWindow) {
+      log(
+        `piece-store "${revised.name.slice(0, 40)}": the machine's share is smaller than one ` +
+        `reader's window, so the allowance is held at ${Math.round(revised.ceilingBytes / 1048576)}MB ` +
+        "anyway — a store that cannot hold the window of the read it is serving cannot finish that read"
       );
     } else if (revised.committedBytes > revised.ceilingBytes) {
       log(
@@ -564,8 +580,20 @@ setInterval(() => {
       );
     }
   }
+  const reserveNow = machineReserveBytes();
+  if (reserveNow !== reserveBefore || reserveNow !== lastReserveBytes) {
+    lastReserveBytes = reserveNow;
+    log(
+      `piece-store: leaving ${Math.round(reserveNow / 1048576)}MB for everything else on this ` +
+      "machine — the largest fall in available memory this process has seen and did not cause"
+    );
+  }
   for (const stats of collectStoreStats()) {
-    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}/${stats.evictedOnRevise}/${stats.spillFailures}`;
+    const signature =
+      `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/` +
+      `${stats.blockedByPins}/${stats.evictedOnRevise}/${stats.spillFailures}/` +
+      `${stats.evictedProtected}/${stats.demand?.unionPieces ?? 0}/${stats.admittedToDisk}/` +
+      `${stats.blocksAllocated}/${stats.blocksFree}/${stats.blocksReleased}`;
     if (lastReported.get(stats.name) === signature) {
       continue;
     }
@@ -578,6 +606,7 @@ setInterval(() => {
       `(${Math.round((stats.residentBytes || 0) / 1048576)}MB of ` +
       `${Math.round((stats.budgetBytes || 0) / 1048576)}MB allowed) ` +
       `committed=${Math.round((stats.committedBytes || 0) / 1048576)}MB ` +
+      `blocks=${stats.blocksAllocated} (${stats.blocksFree} spare) ` +
       `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}` +
@@ -586,16 +615,60 @@ setInterval(() => {
       (stats.spillFailures > 0 ? ` spill-failures=${stats.spillFailures}` : "") +
       (stats.outstanding > 0 ? ` outstanding=${stats.outstanding}` : "")
     );
+    // Why it spills, on its own line because it is a different question from
+    // how much it holds. Three facts, and between them they say whether the
+    // thrashing is a policy to fix or arithmetic to accept: what the readers
+    // together are asking to keep against what the store may hold; how many
+    // evictions had to take a piece a reader had declared it wants; and how
+    // long a piece stayed on disk before it was wanted back. On 2026-09-02 a
+    // session did 6565 spills and 7575 revivals with 53.6% of reads served
+    // from memory, and nothing recorded which of the three was the cause
+    // (roadmap item 9).
+    const demand = stats.demand;
+    if (demand && demand.readers > 0) {
+      const age = stats.revivalAgeMedianMs;
+      log(
+        `piece-store "${stats.name.slice(0, 40)}" demand: ${demand.readers} reader(s) want ` +
+        `${demand.unionPieces} piece(s) of ${demand.capacity} the store may hold ` +
+        `(widest window ${demand.widestPieces})` +
+        (stats.evictedProtected > 0
+          ? `; ${stats.evictedProtected} of ${stats.spills} eviction(s) took a piece a reader had declared`
+          : "; no eviction has taken a declared piece") +
+        (stats.evictedWithDistance > 0
+          ? `, a victim lay ${(stats.evictedDistanceSum / stats.evictedWithDistance).toFixed(1)} ` +
+            "piece(s) from the nearest window on average"
+          : "") +
+        (age === null
+          ? "; nothing has come back from disk yet"
+          : `; a revived piece had been on disk ${(age / 1000).toFixed(1)}s (median of ` +
+            `${stats.revivalAgeSamples}, ${stats.revivedWithinFiveSeconds} of them within 5s)`) +
+        `; of ${stats.admittedInsideWindow + stats.admittedOutsideWindow} piece(s) admitted ` +
+        `${stats.admittedOutsideWindow} were in nobody's window, ${stats.admittedToDisk} of those ` +
+        "went straight to disk" +
+        `; ${stats.blocksAllocated} block(s) of memory exist, ${stats.blocksFree} of them spare` +
+        (stats.reuseGapMs === null
+          ? ", none re-used yet"
+          : `, a block waits up to ${(stats.reuseGapMs / 1000).toFixed(1)}s before it is wanted again`) +
+        `, ${stats.blocksReleased} given back` +
+        (stats.spillsSkipped > 0
+          ? `; ${stats.spillsSkipped} of ${stats.spills} eviction(s) needed no write, the disk already had them`
+          : "") +
+        (stats.returnedWhilePinned > 0
+          ? `; ${stats.returnedWhilePinned} BLOCK(S) WERE RECYCLED WHILE STILL BEING READ`
+          : "")
+      );
+    }
   }
 }, STORE_REPORT_INTERVAL_MS).unref();
 
 /**
- * The piece buffers this thread has let go of against the ones it still holds.
+ * The blocks of piece memory this thread has allocated against the pieces the
+ * stores hold in them.
  *
  * Not per store: the collector is per thread, and the question is about the
- * thread. A gap that keeps widening means a reference of ours outlives the
- * piece; a gap that does not means whatever grows is below us, in the
- * allocator or in buffers the collector has not reached.
+ * thread. With a pool one block serves many pieces, so a number of allocations
+ * that keeps climbing while the stores hold a steady number of pieces means
+ * blocks are being made and thrown away instead of re-used.
  *
  * @returns {string}
  */
@@ -607,8 +680,8 @@ function describePieceBuffers() {
   const alive = collection.released - collection.collected;
   const held = collectStoreStats().reduce((sum, stats) => sum + (stats.resident || 0), 0);
   return (
-    `piece buffers ${collection.released} let go, ${collection.collected} collected, ` +
-    `${alive} still alive against ${held} the store holds`
+    `memory blocks ${collection.released} allocated, ${collection.collected} collected, ` +
+    `${alive} still alive against ${held} piece(s) the stores hold`
   );
 }
 

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-lru.test.js

@@ -189,3 +189,66 @@ test("the capacity follows the store's live allowance", () => {
   lru.setCapacity(0);
   assert.equal(lru.capacity, 2, "a capacity below one is refused, not obeyed");
 });
+
+test("the demand is the union of the readers' windows, not their sum", () => {
+  const lru = new PieceLru(88);
+  // Two readers of one file — picture and sound — overlap by construction.
+  // Summing them would say the store is short when it is not.
+  lru.protect("video", 100, 149);
+  lru.protect("audio", 130, 179);
+
+  const demand = lru.demand();
+  assert.equal(demand.readers, 2);
+  assert.equal(demand.unionPieces, 80, "100..179 is eighty pieces, not a hundred");
+  assert.equal(demand.widestPieces, 50);
+  assert.equal(demand.capacity, 88);
+
+  lru.protect("second-viewer", 900, 979);
+  assert.equal(lru.demand().unionPieces, 160, "windows that do not touch add up");
+
+  lru.unprotect("second-viewer");
+  lru.unprotect("audio");
+  lru.unprotect("video");
+  assert.deepEqual(
+    lru.demand(),
+    { readers: 0, unionPieces: 0, widestPieces: 0, capacity: 88 },
+    "no reader asking for anything is not the same as asking for one piece"
+  );
+});
+
+test("an eviction says whether it had to take a piece a reader declared", () => {
+  const lru = new PieceLru(3);
+  lru.touch(10);
+  lru.touch(11);
+  lru.touch(12);
+  lru.protect("video", 11, 12);
+
+  const spare = lru.evictionChoice();
+  assert.equal(spare.index, 10, "the piece outside every window goes first");
+  assert.equal(spare.protectionYielded, false);
+  assert.equal(spare.distance, 1, "one piece away from the window at 11");
+
+  // Nothing spare left: both survivors are inside the declared window.
+  lru.remove(10);
+  const forced = lru.evictionChoice();
+  assert.equal(forced.index, 11);
+  assert.equal(forced.protectionYielded, true, "the store is holding less than it is asked to");
+  assert.equal(forced.distance, 0, "inside a window");
+
+  assert.equal(lru.evictionCandidate(), 11, "the older answer is the same choice");
+});
+
+test("with nothing declared there is no distance to report", () => {
+  const lru = new PieceLru(2);
+  lru.touch(7);
+  const choice = lru.evictionChoice();
+  assert.equal(choice.index, 7);
+  assert.equal(choice.distance, -1, "-1 is absence, and 0 would read as inside a window");
+
+  lru.pin(7);
+  assert.deepEqual(
+    lru.evictionChoice(),
+    { index: null, protectionYielded: false, distance: -1 },
+    "a pinned piece is never a candidate, and says so without a distance"
+  );
+});

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

@@ -132,3 +132,272 @@ test("pinned pieces are never evicted, and the pin count is reported", async ()
     await fs.rm(directory, { recursive: true, force: true });
   }
 });
+
+test("the store says why it spills: what is asked of it, what it had to take, how soon it came back", async () => {
+  const capacity = 4;
+  const { store, directory } = await makeStore(capacity);
+  try {
+    // A reader declaring more than the store may hold. This is the shape the
+    // field session of 2026-09-02 is suspected of — 88 slots against an
+    // encoder running 120-380 s ahead of a viewer, half the reads missing —
+    // and nothing recorded it (roadmap item 9).
+    store.protectRange("video", 0, 9);
+    for (let index = 0; index < 10; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+
+    const asked = store.stats();
+    assert.equal(asked.demand.readers, 1);
+    assert.equal(asked.demand.unionPieces, 10);
+    assert.equal(asked.demand.capacity, capacity);
+    assert.ok(
+      asked.demand.unionPieces > asked.demand.capacity,
+      "a reader asking for more than the store holds is arithmetic, not a policy fault"
+    );
+    assert.ok(
+      asked.evictedProtected > 0,
+      "every eviction here had to take a piece the reader had declared"
+    );
+
+    // Read back the pieces that were spilled: each one comes home, and the
+    // store says how long it had been away.
+    for (let index = 0; index < 10; index += 1) {
+      const bytes = await get(store, index);
+      assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
+    }
+
+    const after = store.stats();
+    assert.ok(after.revivalAgeSamples > 0, "pieces came back and their age was recorded");
+    assert.equal(typeof after.revivalAgeMedianMs, "number");
+    assert.ok(
+      after.revivedWithinFiveSeconds > 0,
+      "a piece wanted again seconds after it left should not have left"
+    );
+
+    store.releaseProtection("video");
+    assert.equal(store.stats().demand.readers, 0, "a reader that ends stops being counted");
+  } finally {
+    store.destroy(() => undefined);
+    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 });
+  }
+});