@torrent-tv/proxy 2.82.0 → 2.83.1

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

@@ -265,3 +265,117 @@ test("the spill ceiling is what the disk's owner said, divided between the store
     await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
   }
 });
+
+test("what lies behind every reader goes without waiting for the disk to be short", async () => {
+  // THE SECOND RULE. The ceiling is a share of free space, and on a roomy host
+  // that is tens of gigabytes against a measured growth of 14 400 MB in one
+  // viewing — so the ceiling alone never binds and nothing is removed until the
+  // torrent itself goes. A piece behind every read head has been read.
+  const { store, directory } = await makeStore(1000 * PIECE);
+  try {
+    for (const index of [0, 1, 2, 3, 4, 5]) {
+      await store.write(index, pieceOf(index));
+    }
+
+    const removed = store.forgetBehind([3, 4]);
+    await store.settled();
+
+    assert.equal(removed, 3, "the three behind the earliest reader should have gone");
+    assert.deepEqual([0, 1, 2].map((index) => store.has(index)), [false, false, false]);
+    assert.deepEqual([3, 4, 5].map((index) => store.has(index)), [true, true, true]);
+    assert.equal(store.stats().behind, 3);
+  } finally {
+    await store.destroy();
+    await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("with no reader at all, nothing is thrown away", async () => {
+  // A store between reads is not a store nobody wants. What empties it whole is
+  // the torrent going idle, which removes the store and its directory.
+  const { store, directory } = await makeStore(1000 * PIECE);
+  try {
+    for (const index of [0, 1, 2]) {
+      await store.write(index, pieceOf(index));
+    }
+    assert.equal(store.forgetBehind([]), 0);
+    assert.equal(store.size, 3);
+  } finally {
+    await store.destroy();
+    await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("a piece being read is not taken even when it is behind everybody", async () => {
+  const { store, directory } = await makeStore(1000 * PIECE);
+  try {
+    await store.write(0, pieceOf(0));
+    await store.write(5, pieceOf(5));
+    const reading = store.read(0, Buffer.alloc(PIECE));
+    const removed = store.forgetBehind([5]);
+    await reading;
+    await store.settled();
+
+    assert.equal(removed, 0, "a piece under a reader was thrown away");
+    assert.equal(store.has(0), true);
+  } finally {
+    await store.destroy();
+    await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("when there is no room, what is behind the readers goes before what is ahead", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "piece-disk-heads-"));
+  const clock = { at: 1000 };
+  // The reader stands on #5. #4 is behind it and was touched LAST, so under the
+  // old rule — least recently used — it would have been the safest piece there.
+  const store = new PieceDiskStore({
+    directory,
+    name: "pieces",
+    chunkLength: PIECE,
+    allowanceBytes: 3 * PIECE,
+    now: () => clock.at,
+    readHeads: () => [5]
+  });
+  try {
+    for (const index of [8, 7, 4]) {
+      clock.at += 100;
+      await store.write(index, pieceOf(index));
+    }
+    clock.at += 100;
+    await store.write(9, pieceOf(9));
+    await store.settled();
+
+    assert.equal(store.has(4), false, "the piece behind the reader was kept because it was touched last");
+    assert.deepEqual([7, 8, 9].map((index) => store.has(index)), [true, true, true]);
+  } finally {
+    await store.destroy();
+    await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("a store takes up the pieces a previous life left in its directory", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "adopt-"));
+  try {
+    const first = new PieceDiskStore({ directory: root, name: "film.pieces", chunkLength: 1024 });
+    await first.write(7, Buffer.alloc(1024, 7));
+    await first.write(9, Buffer.alloc(1024, 9));
+    await first.close();
+
+    // A torrent torn down and added again gets a NEW store over the same
+    // directory. Before 2026-09-11 its index started empty, so every piece it
+    // in fact had read as missing and the film was downloaded a second time
+    // while the first copy sat beside it.
+    const second = new PieceDiskStore({ directory: root, name: "film.pieces", chunkLength: 1024 });
+    assert.equal(second.size, 2, "the pieces already on disk were not taken up");
+    assert.equal(second.bytes, 2048, "nor were their bytes counted");
+    assert.ok(second.has(7) && second.has(9));
+
+    const target = Buffer.alloc(1024);
+    await second.read(7, target);
+    assert.ok(target.equals(Buffer.alloc(1024, 7)), "and they read back as themselves");
+    await second.destroy();
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});

package/test/piece-from-whole-file.test.js

@@ -0,0 +1,129 @@
+/**
+ * @file A piece read out of the files it was assembled into.
+ *
+ * Without this a whole file is a second copy of bytes the piece store also
+ * holds, and neither copy can be dropped. With it the spilled copy is a
+ * duplicate and can go — one episode on the field host of 2026-09-11 was
+ * 1417 MB of segments beside 1424 MB of spilled pieces — and a torrent can be
+ * destroyed and added again without fetching a byte.
+ */
+
+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 { pieceFromWholeFiles, pieceIsInWholeFiles } from "../services/files/piece-from-whole-file.js";
+
+const PIECE = 16;
+
+/**
+ * Two files laid end to end, as a torrent lays them out, with a piece straddling
+ * the boundary between them.
+ *
+ * @returns {Promise<{ root: string, files: object[], length: number, bytes: Buffer }>}
+ */
+async function twoFiles() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "piece-of-whole-"));
+  const first = Buffer.alloc(20, 1);
+  const second = Buffer.alloc(24, 2);
+  await fs.writeFile(path.join(root, "0"), first);
+  await fs.writeFile(path.join(root, "1"), second);
+  return {
+    root,
+    files: [
+      { offset: 0, length: first.length },
+      { offset: first.length, length: second.length }
+    ],
+    length: first.length + second.length,
+    bytes: Buffer.concat([first, second])
+  };
+}
+
+/**
+ * @param {string} root
+ * @param {number[]} whole - Which file indexes this proxy holds whole.
+ * @returns {(fileIndex: number) => { path: string, length: number } | null}
+ */
+const holds = (root, whole) => (fileIndex) =>
+  whole.includes(fileIndex) ? { path: path.join(root, String(fileIndex)), length: 0 } : null;
+
+test("a piece inside one file comes back byte for byte", async () => {
+  const { root, files, length, bytes } = await twoFiles();
+  try {
+    const piece = await pieceFromWholeFiles({
+      index: 0,
+      pieceLength: PIECE,
+      length,
+      files,
+      wholeFileAt: holds(root, [0, 1])
+    });
+    assert.deepEqual(piece, bytes.subarray(0, PIECE));
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("a piece straddling two files is stitched from both", async () => {
+  const { root, files, length, bytes } = await twoFiles();
+  try {
+    // Piece 1 covers bytes 16..31: four from the first file, twelve from the
+    // second.
+    const piece = await pieceFromWholeFiles({
+      index: 1,
+      pieceLength: PIECE,
+      length,
+      files,
+      wholeFileAt: holds(root, [0, 1])
+    });
+    assert.deepEqual(piece, bytes.subarray(PIECE, PIECE * 2));
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("the last piece is read to the end of the torrent and no further", async () => {
+  const { root, files, length, bytes } = await twoFiles();
+  try {
+    // 44 bytes in pieces of 16: the last piece is 12 long.
+    const piece = await pieceFromWholeFiles({
+      index: 2,
+      pieceLength: PIECE,
+      length,
+      files,
+      wholeFileAt: holds(root, [0, 1])
+    });
+    assert.equal(piece.length, 12);
+    assert.deepEqual(piece, bytes.subarray(32));
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("a piece any part of which is not held whole is refused, not half read", async () => {
+  const { root, files, length } = await twoFiles();
+  try {
+    // Only the first file is here; piece 1 straddles both. Half a piece is
+    // worse than none: the layer above would hash it and mark it bad.
+    const piece = await pieceFromWholeFiles({
+      index: 1,
+      pieceLength: PIECE,
+      length,
+      files,
+      wholeFileAt: holds(root, [0])
+    });
+    assert.equal(piece, null);
+    assert.equal(
+      pieceIsInWholeFiles({ index: 1, pieceLength: PIECE, length, files, wholeFileAt: holds(root, [0]) }),
+      false
+    );
+    // And one wholly inside the file that IS held is both readable and known to
+    // be a duplicate of what is on the spill.
+    assert.equal(
+      pieceIsInWholeFiles({ index: 0, pieceLength: PIECE, length, files, wholeFileAt: holds(root, [0]) }),
+      true
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});

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

@@ -177,7 +177,13 @@ test("the store says why it spills: what is asked of it, what it had to take, ho
     // eviction on ADMISSION — `asked.spills` above is zero, where before it all
     // six arrivals displaced a nearer piece and were read back moments later.
     assert.ok(after.fromDisk > 0, "the pieces that went to disk were read back from it");
-    assert.ok(after.revivals > 0, "reading one back brings it into memory");
+    // Through the reader's own entry point, which is the one that populates
+    // memory. `get` is the torrent client's, and since 2026-09-11 it answers
+    // from disk without taking a block: a peer asks for kilobytes of a piece
+    // that is megabytes, and reviving the whole of it for that was how an
+    // upload capped at 512 KB/s produced 49 696 revivals in one session.
+    await store.reside(9);
+    assert.ok(store.stats().revivals > 0, "a read for playback brings the piece into memory");
     // No age to report, and that is right rather than missing: an age measures
     // how long an EVICTED piece stayed away, and these were never resident —
     // they were written on arrival and read back once.
@@ -252,11 +258,12 @@ test("before any reader has declared anything, an arriving piece still goes to m
 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.
+    // With nobody reading, the store asks for a floor — one window's worth,
+    // and until it has been asked for anything, the minimum. It does NOT ask
+    // for everything it is allowed: pieces arriving for a reader still on its
+    // way have the disk.
     const idle = store.wantedBytes;
-    assert.equal(idle, store.stats().budgetBytes);
+    assert.ok(idle > 0 && idle < store.stats().budgetBytes, "an idle store asks for a floor, not its whole allowance");
 
     // Two readers of one file — picture and sound — overlapping by
     // construction. The ask is their union, not their sum.
@@ -375,10 +382,11 @@ test("evicting a piece the disk already holds costs no second write", async () =
     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.
+    // Read it back for playback — 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)));
+    await store.reside(0);
     for (let index = 10; index < 13; index += 1) {
       await put(store, index, pieceOf(index));
     }
@@ -396,19 +404,24 @@ test("a store whose readers have gone asks for nothing, one that never had them
   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.
+    // of the header and the tail, with a read on its way. Those pieces have the
+    // disk, so the store asks for the minimum rather than for its opening
+    // allowance — a torrent nobody has read yet held 4180 MB of a machine's
+    // memory on 2026-09-11 while the film being watched was allowed 12 MB.
     const opening = store.wantedBytes;
-    assert.equal(opening, store.stats().budgetBytes);
+    assert.ok(opening < store.stats().budgetBytes, "a store nobody has read keeps the minimum");
 
     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.
+    // The read ends, and the store keeps room for ONE window — what the next
+    // read will ask for within seconds. Falling to the minimum here is what
+    // left a store at three blocks when the viewer switched files on
+    // 2026-09-11, with the allowance re-derived a minute later and a claim
+    // giving up after five seconds.
     store.releaseProtection("video");
-    assert.ok(store.wantedBytes < opening, "a store with no readers left asks for nothing");
+    assert.equal(store.wantedBytes, 10 * PIECE, "the floor between readers is the widest window seen");
+    assert.ok(store.wantedBytes > opening, "which is more than a store nobody has read keeps");
   } finally {
     store.destroy(() => undefined);
     await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });

package/test/piece-store-never-refuses.test.js

@@ -0,0 +1,153 @@
+/**
+ * @file A store that is short of memory must inconvenience a read, never end a
+ * torrent.
+ *
+ * The field failure of 2026-09-11, in one sentence: the store could not hand
+ * out a block, threw, the throw travelled out through the torrent client's own
+ * write callback, and the client destroyed the torrent. For the rest of the
+ * process every read of that film answered `File 1 not found in
+ * torrent:d4022ff4…`, `/stats` reported `peers=0 connected of 1186 known`, and
+ * the viewer could not open anything until the addon was restarted.
+ *
+ * Three properties hold it shut, and each is checked here on its own:
+ *
+ *  1. an arriving piece is never refused — it has the disk;
+ *  2. a read on the torrent client's own path takes no block at all, so an
+ *     upload can neither wait for memory nor be refused it;
+ *  3. a store between readers keeps room for one window, because that is what
+ *     the next read asks for and the allowance is otherwise re-derived a
+ *     minute later — twelve times slower than a claim gives up.
+ */
+
+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 { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
+
+const PIECE = 1024;
+
+/**
+ * @param {SharedPieceStore} store
+ * @param {number} index
+ * @returns {Promise<void>}
+ */
+const put = (store, index) =>
+  new Promise((resolve, reject) => {
+    store.put(index, Buffer.alloc(PIECE, index % 251), (error) => (error ? reject(error) : resolve()));
+  });
+
+/**
+ * @param {SharedPieceStore} store
+ * @param {number} index
+ * @param {{ offset: number, length: number }} range
+ * @returns {Promise<Buffer>}
+ */
+const get = (store, index, range) =>
+  new Promise((resolve, reject) => {
+    store.get(index, range, (error, bytes) => (error ? reject(error) : resolve(bytes)));
+  });
+
+/**
+ * @returns {Promise<string>}
+ */
+const directory = () => fs.mkdtemp(path.join(os.tmpdir(), "never-refuses-"));
+
+test("a piece is never refused for want of memory", async () => {
+  const root = await directory();
+  // Every block held by a piece that may not leave. The ceiling never falls
+  // below two, so this is how a store with nothing to give is reached: what
+  // held the blocks in the field was two writes on their way to disk, and a pin
+  // reaches the same state deterministically.
+  //
+  // This one takes the store's own patience to run — it must be seen to give
+  // up and keep the piece anyway.
+  const store = new SharedPieceStore(PIECE, {
+    length: PIECE * 8,
+    memoryBytes: PIECE * 2,
+    path: root,
+    name: "no-block-to-be-had"
+  });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+    store.pin(0);
+    store.pin(1);
+
+    await put(store, 3);
+    const stats = store.stats();
+    assert.equal(stats.spilled, 1, "the piece is on disk");
+    assert.equal(store.locate(3), null, "and not in memory, since no block could be had for it");
+    assert.equal(stats.resident, 2, "the pinned pieces were not taken from under their reader");
+    assert.ok(
+      stats.admittedWithoutSlot >= 1,
+      "and the store says so, rather than the torrent client saying it with a destroyed torrent"
+    );
+    const bytes = await get(store, 3, { offset: 0, length: PIECE });
+    assert.equal(bytes.length, PIECE, "and it reads back");
+    assert.equal(bytes[0], 3 % 251, "with its own contents");
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a read for the torrent client takes no block and only its own range", async () => {
+  const root = await directory();
+  const store = new SharedPieceStore(PIECE, {
+    length: PIECE * 8,
+    memoryBytes: PIECE,
+    path: root,
+    name: "ranged-read"
+  });
+  try {
+    // Two fit; the third displaces the oldest, which goes to disk.
+    await put(store, 0);
+    await put(store, 1);
+    await put(store, 2);
+    const before = store.stats();
+    assert.equal(before.spilled, 1, "the first piece is on disk");
+
+    const wanted = 16;
+    const bytes = await get(store, 0, { offset: PIECE - wanted, length: wanted });
+    assert.equal(bytes.length, wanted, "only what was asked for comes back");
+    assert.equal(bytes[0], 0, "and it is that piece's own bytes");
+
+    const after = store.stats();
+    assert.equal(
+      after.blocksAllocated,
+      before.blocksAllocated,
+      "and answering it took no block: a peer asks for kilobytes and a piece here is megabytes"
+    );
+    assert.equal(after.resident, before.resident, "nothing was revived for it");
+    assert.equal(after.fromDisk, before.fromDisk + 1, "and the read is counted as coming from disk");
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a store between readers keeps room for one window", async () => {
+  const root = await directory();
+  const store = new SharedPieceStore(PIECE, {
+    length: PIECE * 200,
+    memoryBytes: PIECE * 64,
+    path: root,
+    name: "between-readers"
+  });
+  try {
+    store.protectRange("read-1", 10, 21, 100);
+    const asked = store.wantedBytes;
+    assert.ok(asked >= PIECE * 12, "with a reader, the window it declared is asked for");
+
+    store.releaseProtection("read-1");
+    assert.ok(
+      store.wantedBytes >= PIECE * 12,
+      "and with the reader gone the floor is still one window — the next read asks for the same again"
+    );
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -129,10 +129,12 @@ const get = (store, index) =>
  *
  * @param {() => boolean} holds
  * @param {string} what
+ * @param {number} [limit] - A backstop, never the measurement: one of the
+ *   conditions here is the store's own patience, which is itself five seconds.
  * @returns {Promise<void>}
  */
-async function until(holds, what) {
-  const deadline = Date.now() + 5_000;
+async function until(holds, what, limit = 5_000) {
+  const deadline = Date.now() + limit;
   while (!holds()) {
     if (Date.now() > deadline) {
       throw new Error(`timed out waiting until ${what}`);
@@ -196,10 +198,21 @@ test("a claim that cannot be met ends in an error, not in waiting for ever", { t
     // other is pinned. The old rule waited while anything was nominally in
     // flight, which here is for ever.
     store.pin(1);
-    await assert.rejects(() => put(store, 3), /nothing moved/);
+    // The claim gives up within its own patience — that is the property. What
+    // the caller does with the refusal is its own business, and since
+    // 2026-09-11 an arriving piece answers it by taking the disk instead of
+    // failing the torrent client's write.
+    const arriving = put(store, 3);
+    await until(
+      () => store.stats().blockedByPins > 0,
+      "the claim gave up rather than waiting for ever",
+      20_000
+    );
 
     store.unpin(1);
     disk.releaseWrites();
+    await arriving;
+    disk.releaseWrites();
     await spilling;
   } finally {
     disk.releaseWrites();

package/test/probe-wedge-certainty.test.js

@@ -12,7 +12,7 @@ test("a seen-counter bounded lag is not a wedge, however long it lasts", () => {
     stuckForMs: 3400,
     longestHealthySeenGapMs: 3500
   });
-  assert.equal(verdict.certain, false);
+  assert.equal(verdict.isCertain, false);
 });
 
 test("a seen-counter frozen past this connection's own worst legitimate gap is a wedge", () => {
@@ -23,7 +23,7 @@ test("a seen-counter frozen past this connection's own worst legitimate gap is a
     stuckForMs: 90_000,
     longestHealthySeenGapMs: 3500
   });
-  assert.equal(verdict.certain, true);
+  assert.equal(verdict.isCertain, true);
 });
 
 test("with no healthy history yet, one probe interval is still required", () => {
@@ -31,7 +31,7 @@ test("with no healthy history yet, one probe interval is still required", () =>
     stuckForMs: PROBE_INTERVAL_MS - 1,
     longestHealthySeenGapMs: 0
   });
-  assert.equal(verdict.certain, false);
+  assert.equal(verdict.isCertain, false);
   assert.equal(verdict.needMs, PROBE_INTERVAL_MS);
 });
 

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

@@ -151,11 +151,16 @@ test("refuses to make room when every resident piece is being read", async () =>
     store.pin(0);
     store.pin(1);
 
-    await assert.rejects(
-      () => put(store, 2, piece(2)),
-      /pinned/,
-      "the store took memory from under a reader instead of refusing"
-    );
+    // The pinned pieces stay where they are, and the arrival is kept anyway —
+    // on the disk, which is what it has. Refusing it was how a store short of
+    // memory ended a torrent: the refusal travelled out through the torrent
+    // client's own write callback and the client destroyed the torrent
+    // (field 2026-09-11).
+    await put(store, 2, piece(2));
+    assert.ok(store.locate(0), "the pinned piece was taken from under its reader");
+    assert.ok(store.locate(1), "the pinned piece was taken from under its reader");
+    assert.equal(store.locate(2), null, "and the arrival did not displace either of them");
+    assert.ok((await get(store, 2)).equals(piece(2)), "the arrival is kept, and reads back");
   } finally {
     store.unpin(0);
     store.unpin(1);
@@ -172,7 +177,7 @@ test("a piece revived from disk is readable by offset again", async () => {
     await put(store, 2, piece(2)); // pushes piece 0 out to disk
     assert.equal(store.locate(0), null, "piece 0 should have left memory");
 
-    await get(store, 0); // brings it back
+    await store.reside(0); // brings it back, which is what a playback read does
     const located = store.locate(0);
     assert.ok(located, "piece 0 was not brought back into memory");
     const view = Buffer.from(located.buffer, located.offset, located.length);
@@ -248,11 +253,18 @@ test("counts where reads were served from, so the budget can be judged", async (
     const stats = store.stats();
     assert.equal(stats.fromMemory, 2, "memory reads miscounted");
     assert.equal(stats.fromDisk, 1, "disk reads miscounted");
-    // Two: piece 0 goes out to make room for piece 2, then piece 1 goes out to
-    // make room for piece 0 coming back. Reviving costs a spill of its own, and
-    // that is worth seeing in the figures rather than hiding.
-    assert.equal(stats.spills, 2, "spills miscounted");
-    assert.equal(stats.revivals, 1, "revivals miscounted");
+    // One: piece 0 goes out to make room for piece 2. The read that follows is
+    // the torrent client's, and since 2026-09-11 it is answered from the disk
+    // copy without taking a block — so nothing has to be written out for it and
+    // nothing is revived. A read for PLAYBACK still populates memory, and pays
+    // for it with a spill; that is the next assertion.
+    assert.equal(stats.spills, 1, "spills miscounted");
+    assert.equal(stats.revivals, 0, "the client's own read does not revive");
+
+    await store.reside(0);
+    const afterPlayback = store.stats();
+    assert.equal(afterPlayback.revivals, 1, "a read for playback revives");
+    assert.equal(afterPlayback.spills, 2, "and pays for its block with a spill");
     assert.equal(stats.blockedByPins, 0);
     assert.equal(stats.capacity, 2);
   } finally {
@@ -268,9 +280,11 @@ test("counts a refusal caused by pinned pieces", async () => {
     await put(store, 1, piece(1));
     store.pin(0);
     store.pin(1);
-    await assert.rejects(() => put(store, 2, piece(2)));
+    await put(store, 2, piece(2));
 
-    assert.equal(store.stats().blockedByPins, 1, "a refusal went unrecorded");
+    const stats = store.stats();
+    assert.equal(stats.blockedByPins, 1, "the store not being able to give a block went unrecorded");
+    assert.equal(stats.admittedWithoutSlot, 1, "and what it did instead went unrecorded");
   } finally {
     store.unpin(0);
     store.unpin(1);

package/test/stream-route.test.js

@@ -10,6 +10,9 @@
 
 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 { handleStreamGet } from "../routes/stream/get.js";
 
 /**
@@ -143,3 +146,41 @@ test("a ranged GET is reported as a real read position", async () => {
 
   assert.deepEqual(state.prioritized, [{ byteStart: 4_390_000_000, wholeFileRead: false }]);
 });
+
+test("a file downloaded whole is served from disk without touching the torrent", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "stream-whole-"));
+  const where = path.join(root, "0");
+  const bytes = Buffer.from("a film that is a file now", "utf8");
+  await fs.writeFile(where, bytes);
+  try {
+    const { req, reply, sent, deps } = harness({ method: "GET", range: "bytes=2-6" });
+    let asked = false;
+    deps.torrentPool.getTorrent = async () => {
+      asked = true;
+      throw new Error("the torrent was asked for, which is what this avoids");
+    };
+    deps.torrentPool.wholeFiles = new Map([
+      ["abc/0", { path: where, length: bytes.length, name: "film.mkv" }]
+    ]);
+    // The source key IS the identity — `torrent:<infohash>` — and it is all the
+    // route needs to find the file.
+    deps.sourceRegistry = { get: () => ({ sourceType: "torrent", source: "magnet:?xt=urn:btih:abc" }) };
+    req.query = { sourceKey: "torrent:abc", fileIndex: "0" };
+
+    await handleStreamGet(req, reply, deps);
+
+    assert.equal(asked, false, "the torrent was asked for");
+    assert.equal(sent.code, 206);
+    assert.equal(sent.headers["content-range"], `bytes 2-6/${bytes.length}`);
+    assert.equal(sent.headers["content-length"], "5");
+  } finally {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+  }
+});
+
+test("a file this proxy does not have whole still goes to the torrent", async () => {
+  const { req, reply, state, deps } = harness({ method: "GET", range: "bytes=0-99" });
+  deps.torrentPool.wholeFiles = new Map([["other/7", { path: "/nowhere", length: 1, name: "x" }]]);
+  await handleStreamGet(req, reply, deps);
+  assert.equal(state.claims, 1, "the ordinary path was not taken");
+});