@torrent-tv/proxy 2.69.2 → 2.70.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2.70.0
+
+- **New**: The piece store keeps a pool of memory blocks instead of allocating one per piece. A block is one piece's worth of memory; it is taken from the free list, and put back there when its piece is written out. Field 2026-09-02: 7575 allocations of 4 MiB in 44 minutes, each released only when the collector reached it, which is why the process held 1.86 GB while the store's own accounting said 352 MB. A block goes back for re-use only AFTER the spill write has finished, because that write reads out of it; a block whose piece is re-put while a reader holds it is given up rather than recycled, and a counter says if one ever is not.
+- **Fix**: The store's allowance could only ever fall. `#capacity` was computed once in the constructor and used as an upper bound on every revision, so a torrent opened while the machine was full kept a small allowance for its whole life however much memory was freed afterwards. The field is gone; the opening figure is now only where the store starts.
+- **Fix**: `AVAILABLE_MEMORY_SHARE` (a quarter), `MIN_BUDGET_BYTES` (64 MB) and `MEMORY_BUDGET_CEILING_BYTES` (512 MB) are removed. All three trace to one observation of one host on 2026-08-03 and none was derived. The budget is now the smaller of what the readers have declared — the union of their windows, since picture and sound overlap — and what the machine allows, which is `MemAvailable` plus what the stores already hold, less what other processes have recently been seen to need. That last figure starts at zero and grows only on evidence: the fall in available memory between two readings, beyond what the stores themselves took.
+- **Fix**: A piece no reader has declared, arriving at a store with no room, goes straight to disk instead of pushing out a piece a reader is about to read. It costs the same one write it would have cost when the next arrival evicted it. Before the first read nothing is declared and nothing is refused memory on a guess.
+- **Fix**: Evicting a piece the disk already holds costs no second write. `#revive` reads a piece back and leaves the copy on disk, and only `put` removes it, so a piece revived and not re-put is identical to what is already written. There were 7575 revivals in that one session (roadmap item 66: 14.4 GB written in a single viewing).
+- **Fix**: A store whose readers have GONE asks for nothing, where before it kept asking for what it held. 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. A store that has never had a reader is a different case and keeps its opening share.
+- **Fix**: A store is never cut below one reader's whole window, whatever the machine's share says. Obeying a smaller share would leave it unable to finish the read it is serving: every resident piece pinned, zero bytes returned, ffmpeg taking that for the end of the file — which killed every encoder on that file on 2026-08-15. The line says when the share was smaller than the window.
+- **Chore**: What other processes need is a window of the last sixty observations, not a high-water. A single spike would otherwise squeeze the stores for the life of the process, which is the same mistake an all-time maximum makes of the block re-use gap.
+- **New**: A spare block is given up once it has sat unused longer than the store's own working rhythm — the longest wait, over recent work, between a block falling free and being wanted again. Measured, not chosen: while a film is being watched a block is taken again within milliseconds, because one is taken for every piece that arrives.
+- **New**: The store line says how many blocks of memory exist and how many are spare, how long a block waits before it is wanted again, how many were given back, how many pieces were admitted that were in nobody's window, and how many evictions needed no write. `committed` now means what the process holds — the blocks — rather than the pieces in them.
+- **Chore**: Thirteen checks across `test/piece-lru.test.js`, `test/piece-store-eviction.test.js` and `test/memory-budget.test.js`, including that a re-used block never carries the previous piece's bytes into the next one.
+
 ## 2.69.2
 
 - **New**: The piece store says WHY it spills, which no reading has ever answered. A session on 2026-09-02 did 6565 spills and 7575 revivals in 44 minutes with only 53.6 % of reads served from memory, and nothing recorded whether that was an eviction order fighting the read order or a working set that simply does not fit. Three figures now settle it, on one line per store: what the live readers between them 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 revived piece had been on disk before it was wanted back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.69.2",
+  "version": "2.70.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/piece-store/piece-lru.js

@@ -248,6 +248,36 @@ export class PieceLru {
     };
   }
 
+  /**
+   * Whether a reader is holding this piece right now.
+   *
+   * Asked before a block is put back for re-use: a pinned piece has a view onto
+   * its memory somewhere, and handing that memory to another piece would let
+   * the holder read bytes that are not its own.
+   *
+   * @param {number} index
+   * @returns {boolean}
+   */
+  isPinned(index) {
+    return this.#pins.has(index);
+  }
+
+  /**
+   * Whether any live reader has declared it will want this piece.
+   *
+   * Asked on admission, not only on eviction: a piece nobody has declared is
+   * being downloaded ahead of every reader, and putting it in memory means
+   * pushing out one that IS declared — which is then read back from disk
+   * moments later. Measured 2026-09-02: 6565 spills and 7575 revivals in 44
+   * minutes with 53.6 % of reads served from memory (roadmap item 9).
+   *
+   * @param {number} index
+   * @returns {boolean}
+   */
+  wants(index) {
+    return this.#isProtected(index);
+  }
+
   /**
    * Pieces from `index` to the nearest declared window, zero inside one and -1
    * when nothing is declared.

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

@@ -68,31 +68,134 @@ export function findSharedStore(torrent) {
   return null;
 }
 
-const MEMORY_BUDGET_CEILING_BYTES = 512 * 1024 * 1024;
-const AVAILABLE_MEMORY_SHARE = 0.25;
+/**
+ * The largest fall in the machine's available memory that this process has
+ * seen and did not cause itself.
+ *
+ * What has to be left for everything else on the machine. It cannot be a share
+ * of what is free — a share is a number chosen out of nothing, which is what
+ * `AVAILABLE_MEMORY_SHARE = 0.25`, `MIN_BUDGET_BYTES` and
+ * `MEMORY_BUDGET_CEILING_BYTES` were until 2026-09-02, all three traceable to
+ * one observation of one host on 2026-08-03. It is measured instead: between
+ * two readings, how much available memory went away beyond what the stores
+ * themselves took. On the field host that quantity is large — while the proxy
+ * held 76-133 MB overnight the machine's available memory fell from 2378 MB to
+ * 306 MB and came back — and on a quiet host it stays near zero, which is the
+ * right answer there.
+ *
+ * Starts at zero: nothing is reserved until somebody else has been seen to
+ * need it.
+ */
+const otherDemand = { falls: [], lastAvailableBytes: 0, lastStoreBytes: 0 };
+
+/**
+ * How many observations of other processes' demand are kept.
+ *
+ * A window rather than a high-water, and for the reason the block re-use gap is
+ * one too: a single spike would otherwise stand for the life of the process and
+ * squeeze the stores against something that happened once, hours ago.
+ */
+const OTHER_DEMAND_SAMPLES = 60;
+
+/**
+ * Note what the machine had, and how much of the change was not ours.
+ *
+ * @param {number} availableBytes
+ * @param {number} storeBytes - What the live stores hold right now.
+ * @returns {number} The reserve, in bytes.
+ */
+export function noteMachineMemory(availableBytes, storeBytes) {
+  if (otherDemand.lastAvailableBytes > 0) {
+    const fell = otherDemand.lastAvailableBytes - availableBytes;
+    const ours = storeBytes - otherDemand.lastStoreBytes;
+    otherDemand.falls.push(Math.max(0, fell - ours));
+    if (otherDemand.falls.length > OTHER_DEMAND_SAMPLES) {
+      otherDemand.falls.shift();
+    }
+  }
+  otherDemand.lastAvailableBytes = availableBytes;
+  otherDemand.lastStoreBytes = storeBytes;
+  return machineReserveBytes();
+}
 
-export function totalStoreBudgetBytes(availableBytes) {
-  const share = Math.floor(Math.max(availableBytes, 0) * AVAILABLE_MEMORY_SHARE);
-  return Math.max(MIN_BUDGET_BYTES, Math.min(MEMORY_BUDGET_CEILING_BYTES, share));
+/** What has recently been observed to be needed by everything that is not us. */
+export function machineReserveBytes() {
+  return otherDemand.falls.length === 0 ? 0 : Math.max(...otherDemand.falls);
 }
 
-export function budgetForNewStore(availableBytes, storeCount) {
-  const total = totalStoreBudgetBytes(availableBytes);
-  const shares = Math.max(1, Math.floor(storeCount));
-  return Math.max(MIN_BUDGET_BYTES, Math.floor(total / shares));
+/** Forget what other processes have needed. For tests, which share a module. */
+export function forgetMachineMemory() {
+  otherDemand.falls = [];
+  otherDemand.lastAvailableBytes = 0;
+  otherDemand.lastStoreBytes = 0;
+}
+
+/**
+ * How much memory the stores may hold between them.
+ *
+ * `MemAvailable` is what could be allocated on top of what is already held, so
+ * the stores' own bytes are added back: the pair is the ceiling the stores
+ * could reach. The reserve is what has been seen to be needed elsewhere.
+ *
+ * @param {number} availableBytes
+ * @param {number} storeBytes
+ * @param {number} reserveBytes
+ * @returns {number}
+ */
+export function machineAllowanceBytes(availableBytes, storeBytes, reserveBytes) {
+  return Math.max(0, Math.max(availableBytes, 0) + Math.max(storeBytes, 0) - Math.max(reserveBytes, 0));
+}
+
+/**
+ * Divide what the machine allows between the stores, by what each is asking
+ * for.
+ *
+ * A store asks for the pieces its readers have declared. When everyone's ask
+ * fits, everyone gets it and the machine's limit never binds — which is the
+ * usual case, since two readers of one film declare 32-192 MB against gigabytes
+ * of free memory. When the asks do not fit, each store is cut in proportion to
+ * what it asked, so a store wanting little is not cut to make room for one
+ * wanting much.
+ *
+ * @param {number[]} wantedBytes - What each store is asking for, in order.
+ * @param {number} allowanceBytes
+ * @returns {number[]} What each store may hold, in the same order.
+ */
+export function divideAllowance(wantedBytes, allowanceBytes) {
+  const total = wantedBytes.reduce((sum, want) => sum + Math.max(0, want), 0);
+  if (total <= allowanceBytes || total === 0) {
+    return wantedBytes.map((want) => Math.max(0, want));
+  }
+  return wantedBytes.map((want) => Math.floor(allowanceBytes * (Math.max(0, want) / total)));
 }
 
 export function reviseStoreBudgets() {
-  const share = budgetForNewStore(availableMemorySync(), liveStores.size);
+  const stores = [...liveStores];
+  const held = stores.reduce((sum, store) => sum + store.residentBytes, 0);
+  const available = availableMemorySync();
+  const reserve = noteMachineMemory(available, held);
+  const allowance = machineAllowanceBytes(available, held, reserve);
+  const shares = divideAllowance(stores.map((store) => store.wantedBytes), allowance);
   const revised = [];
-  for (const store of liveStores) {
-    revised.push(store.reviseGrowthCeiling(share));
+  for (const [position, store] of stores.entries()) {
+    revised.push(store.reviseGrowthCeiling(shares[position]));
   }
   return revised;
 }
 
 function defaultMemoryBytes() {
-  return budgetForNewStore(availableMemorySync(), liveStores.size + 1);
+  const stores = [...liveStores];
+  const held = stores.reduce((sum, store) => sum + store.residentBytes, 0);
+  const available = availableMemorySync();
+  const allowance = machineAllowanceBytes(available, held, machineReserveBytes());
+  // A store being created has no readers, so it has no demand to state and no
+  // basis for asking for more or less than the others. It opens on an equal
+  // share and the first revision — within a minute, and within seconds of a
+  // read starting — replaces that with what its readers actually declare.
+  // Deliberately not the whole allowance: on a machine with gigabytes free that
+  // would let a torrent nobody is reading yet fill memory before the first
+  // revision arrives.
+  return Math.floor(allowance / (stores.length + 1));
 }
 
 function availableMemorySync() {
@@ -108,8 +211,12 @@ function availableMemorySync() {
 }
 
 /**
- * How many piece buffers this thread has let go of, and how many the collector
- * has actually taken back.
+ * How many blocks of piece memory this thread has let go of, and how many the
+ * collector has actually taken back.
+ *
+ * Since the store keeps a pool, one block serves many pieces, so this counts
+ * blocks and not pieces — and a healthy store allocates only as many as its
+ * allowance permits, so both numbers are now small and nearly equal.
  *
  * The one reading that separates the two explanations of the 700 MB nobody can
  * account for (roadmap item 2, field 2026-08-31): if the two numbers track each
@@ -139,7 +246,6 @@ export function pieceBufferCollection() {
   return { released: released.count, collected: released.collected };
 }
 
-const MIN_BUDGET_BYTES = 64 * 1024 * 1024;
 const MIN_RESIDENT_PIECES = 2;
 /**
  * How long a claim may go without ANYTHING moving before it gives up.
@@ -159,6 +265,13 @@ const PINNED_WAIT_MS = 5_000;
  */
 const REVIVAL_AGE_SAMPLES = 200;
 
+/**
+ * How many block re-use gaps are kept. The same window as the revival ages, and
+ * for the same reason: what is wanted is the rhythm of recent work, not a
+ * history of it.
+ */
+const REUSE_GAP_SAMPLES = 200;
+
 /**
  * The middle value of a sample, or null when there is nothing to take a middle
  * of. Null rather than zero: no revivals and instant revivals are different
@@ -183,7 +296,6 @@ export class SharedPieceStore {
   #chunkLength;
   #lastChunkLength;
   #lastChunkIndex;
-  #capacity;
   #growthCeiling;
   /** Piece index → SharedArrayBuffer of that piece */
   #buffers = new Map();
@@ -224,8 +336,52 @@ export class SharedPieceStore {
     // (roadmap item 9).
     evictedProtected: 0,
     evictedDistanceSum: 0,
-    evictedWithDistance: 0
+    evictedWithDistance: 0,
+    // Where an arriving piece went. A piece nobody has declared is being
+    // downloaded ahead of every reader; putting it in memory pushes out one
+    // that IS declared, which is then read back from disk moments later
+    // (roadmap item 9).
+    admittedInsideWindow: 0,
+    admittedOutsideWindow: 0,
+    admittedToDisk: 0,
+    /** Blocks given back to the operating system. */
+    blocksReleased: 0,
+    /**
+     * A block put back for re-use while a reader still held the piece. Zero by
+     * construction — a pinned piece is never evicted, and a re-put of a pinned
+     * one drops its block instead of recycling it. Counted because if it ever
+     * stops being zero, a consumer is reading another piece's bytes, and that
+     * is invisible from anywhere else.
+     */
+    returnedWhilePinned: 0,
+    /** Spills that found the disk already holding identical bytes. */
+    spillsSkipped: 0
   };
+  /**
+   * Blocks that hold no piece, most recently freed last.
+   *
+   * A block is one piece's worth of memory. Allocating a new one for every
+   * piece meant 7575 allocations of 4 MiB in 44 minutes on 2026-09-02, each
+   * released only when the collector got to it — which is why the process held
+   * 1.86 GB while its own accounting said 352 MB. Blocks are taken from here
+   * and put back here instead (roadmap item 2).
+   *
+   * @type {{ buffer: SharedArrayBuffer, freedAt: number }[]}
+   */
+  #freeBlocks = [];
+  /** Blocks that exist at all: free plus holding a piece. */
+  #blocksAllocated = 0;
+  /** Whether a reader has ever declared a window here. See `wantedBytes`. */
+  #everHadReader = false;
+  /**
+   * How long a block sat free before it was taken again, in milliseconds.
+   * Bounded, because what is wanted is the longest gap of RECENT work: an
+   * all-time maximum would be raised by one long pause and then never let a
+   * block go again.
+   *
+   * @type {number[]}
+   */
+  #reuseGaps = [];
   /** Piece index → when it was written out, for the age it comes back at. */
   #spilledAt = new Map();
   /**
@@ -251,10 +407,11 @@ export class SharedPieceStore {
     const memoryBytes = Number.isFinite(options.memoryBytes) && options.memoryBytes > 0
       ? options.memoryBytes
       : defaultMemoryBytes();
-    this.#capacity = Math.max(MIN_RESIDENT_PIECES, Math.floor(memoryBytes / chunkLength));
-
-    this.#growthCeiling = this.#capacity;
-    this.#lru = new PieceLru(this.#capacity);
+    // Only where this store STARTS. It is not kept, so it cannot come back as a
+    // cap on the revision the way `#capacity` did.
+    const openingCeiling = Math.max(MIN_RESIDENT_PIECES, Math.floor(memoryBytes / chunkLength));
+    this.#growthCeiling = openingCeiling;
+    this.#lru = new PieceLru(openingCeiling);
     this.#name = options.name ?? "pieces";
     // `options.disk` exists so a test can hold a write open or make one fail on
     // purpose. Four of the defects fixed here live in what happens when the
@@ -277,8 +434,11 @@ export class SharedPieceStore {
       resident,
       capacity: this.#growthCeiling,
       residentBytes,
-      allocatedSlots: resident,
-      committedBytes: residentBytes,
+      allocatedSlots: this.#blocksAllocated,
+      // What the process HOLDS, which with a pool is the blocks that exist —
+      // not the pieces in them. Holding and using are different quantities and
+      // the difference is the point of the reading.
+      committedBytes: this.#blocksAllocated * this.#chunkLength,
       budgetBytes: this.#growthCeiling * this.#chunkLength,
       pinned: this.#lru.pinnedCount,
       // Slots claimed and not yet filled. Reported because a reservation that
@@ -292,6 +452,14 @@ export class SharedPieceStore {
       // however the eviction is ordered, and that is the difference between a
       // policy to fix and arithmetic to accept (roadmap item 9).
       demand: this.#lru.demand(),
+      // What the process actually holds for this store, which is not the same
+      // as what it is using: blocks are kept for re-use. The difference is the
+      // spare, and it is the whole of the question whether consumption only
+      // grows (roadmap item 2).
+      blocksAllocated: this.#blocksAllocated,
+      blocksFree: this.#freeBlocks.length,
+      blockBytes: this.#blocksAllocated * this.#chunkLength,
+      reuseGapMs: this.#reuseGapCeilingMs(),
       revivalAgeMedianMs: median(this.#revivalAges),
       revivalAgeSamples: this.#revivalAges.length,
       revivedWithinFiveSeconds: this.#revivalAges.filter((age) => age <= 5_000).length,
@@ -299,12 +467,66 @@ export class SharedPieceStore {
     };
   }
 
+  /** What this store holds right now, in bytes. */
+  get residentBytes() {
+    return this.#buffers.size * this.#chunkLength;
+  }
+
+  /**
+   * What this store is asking to be allowed to hold, in bytes.
+   *
+   * The union of its readers' declared windows — what they have said they will
+   * need — never below the widest single window, because a store that cannot
+   * hold one reader's window cannot complete that reader's read at all: every
+   * resident piece ends up pinned, the read returns zero bytes and ffmpeg takes
+   * that for the end of the file (field 2026-08-15, roadmap item 9).
+   *
+   * With no reader declaring anything there is no demand to speak of, so the
+   * store asks for what the machine allows and the first revision after a read
+   * begins brings it down to what that read needs.
+   */
+  get wantedBytes() {
+    const demand = this.#lru.demand();
+    if (demand.readers > 0) {
+      this.#everHadReader = true;
+      const pieces = Math.max(MIN_RESIDENT_PIECES, demand.unionPieces, demand.widestPieces);
+      return pieces * this.#chunkLength;
+    }
+    // Readers that have GONE are not the same as readers that have not arrived.
+    // A store whose readers ended has nothing to hold pieces for — its torrent
+    // sits until the pool's idle timer removes it, which needs a refcount of
+    // zero and can be a quarter of an hour away — so it asks for nothing and
+    // its memory goes back to the machine now. A store that has never had a
+    // reader is being filled for one that is on its way, and asks for what it
+    // was opened with until the first read says what it needs.
+    return this.#everHadReader
+      ? MIN_RESIDENT_PIECES * this.#chunkLength
+      : this.#growthCeiling * this.#chunkLength;
+  }
+
   reviseGrowthCeiling(allowedBytes) {
+    // No cap at what the machine could spare when this store was CREATED.
+    // `#capacity` was computed once in the constructor and used as an upper
+    // bound here, so the allowance could only ever fall: a torrent opened while
+    // the machine was full kept a small allowance for its whole life, however
+    // much memory was freed afterwards (roadmap item 2, 2026-09-02).
     const wanted = Math.floor(Number(allowedBytes) / this.#chunkLength);
-    this.#growthCeiling = Math.min(
-      this.#capacity,
-      Math.max(MIN_RESIDENT_PIECES, Number.isFinite(wanted) ? wanted : this.#capacity)
+    // Never below one reader's whole window while a reader exists, even when
+    // the machine's share says less. A store that cannot hold the window of the
+    // read it is serving cannot complete that read at all: every resident piece
+    // ends up pinned, the read returns zero bytes and ffmpeg takes that for the
+    // end of the file, which killed every encoder on that file in the field on
+    // 2026-08-15. Exceeding the share is the lesser failure, and the line below
+    // says when it happens.
+    const demand = this.#lru.demand();
+    this.#growthCeiling = Math.max(
+      MIN_RESIDENT_PIECES,
+      demand.readers > 0 ? demand.widestPieces : MIN_RESIDENT_PIECES,
+      Number.isFinite(wanted) ? wanted : MIN_RESIDENT_PIECES
     );
+    const belowAWindow = demand.readers > 0
+      && Number.isFinite(wanted)
+      && wanted < demand.widestPieces;
     // The LRU is told too. It was constructed with the store's original
     // capacity and never revised, so `isFull()` answered against a number that
     // had not been the limit for some time — dormant only because nothing calls
@@ -336,11 +558,17 @@ export class SharedPieceStore {
         this.#counters.spillFailures += 1;
       });
     }
+    // Blocks the store is no longer using and has waited long enough to give
+    // up. The allowance falling is the moment to ask, because that is when the
+    // machine has been shown to need the memory.
+    const releasedBlocks = this.sweepFreeBlocks();
     return {
       name: this.#name,
       ceilingBytes: this.#growthCeiling * this.#chunkLength,
-      committedBytes: this.#buffers.size * this.#chunkLength,
-      evicted
+      committedBytes: this.#blocksAllocated * this.#chunkLength,
+      evicted,
+      releasedBlocks,
+      belowAWindow
     };
   }
 
@@ -469,16 +697,39 @@ export class SharedPieceStore {
    * @returns {Promise<void>}
    */
   #spill(index, buffer) {
+    // The disk may already hold these very bytes. `#revive` reads a piece back
+    // into memory and leaves the copy on disk, and only `put` removes it — so a
+    // piece that was revived and not re-put is identical to what is already
+    // written, and writing it again is work for nothing. There were 7575
+    // revivals in one session on 2026-09-02, and every later eviction of one of
+    // them wrote a second time (roadmap item 66: 14.4 GB written in a single
+    // viewing).
+    if (this.#disk.has(index)) {
+      this.#counters.spills += 1;
+      this.#counters.spillsSkipped += 1;
+      this.#spilledAt.set(index, Date.now());
+      this.#returnBlock(buffer);
+      this.#noteProgress();
+      return Promise.resolve();
+    }
+
     const bytes = Buffer.from(buffer, 0, this.#lengthOf(index));
     const spill = this.#disk.write(index, bytes).then(
       () => {
         this.#counters.spills += 1;
         this.#spilledAt.set(index, Date.now());
         this.#evicting.delete(index);
+        // Only now. The write reads out of this block, so a block handed to
+        // another piece before the write finished would put that piece's bytes
+        // into this piece's place in the file.
+        this.#returnBlock(buffer);
         this.#noteProgress();
       },
       (error) => {
         this.#evicting.delete(index);
+        // The block is no longer holding anything either way; keeping it out of
+        // the pool because the write failed would lose it for good.
+        this.#returnBlock(buffer);
         this.#noteProgress();
         throw error;
       }
@@ -493,6 +744,53 @@ export class SharedPieceStore {
     this.#wake();
   }
 
+  /**
+   * Whether admitting one more piece would need something evicted first.
+   *
+   * Reservations count: a slot claimed and not yet filled is as taken as a
+   * resident piece.
+   *
+   * @returns {boolean}
+   */
+  #isFullNow() {
+    return this.#buffers.size + this.#outstandingPieces >= this.#growthCeiling;
+  }
+
+  /**
+   * Write an arriving piece straight to disk, without it ever occupying memory.
+   *
+   * Registered in `#evicting` like a spill, so a `get` for this index waits for
+   * the write instead of finding the piece on neither tier. Deliberately NOT
+   * recorded in `#spilledAt`: that clock measures how long an EVICTED piece
+   * stayed away, and a piece that was never resident has no such age.
+   *
+   * @param {number} index
+   * @param {Uint8Array} bytes
+   * @returns {Promise<void>}
+   */
+  #writeThrough(index, bytes) {
+    // Copied, not viewed. `DiskTier.write` opens the file before it reads the
+    // bytes, so a view onto the caller's buffer could be written to in between
+    // and the file would get the wrong data. The spill path may pass a view
+    // because that memory is ours; this buffer belongs to the torrent client.
+    // It costs nothing extra: the piece was being copied into a shared buffer
+    // on this path before, and now it is copied here instead.
+    const copy = Buffer.from(bytes.subarray(0, Math.min(bytes.length, this.#lengthOf(index))));
+    const write = this.#disk.write(index, copy).then(
+      () => {
+        this.#evicting.delete(index);
+        this.#noteProgress();
+      },
+      (error) => {
+        this.#evicting.delete(index);
+        this.#noteProgress();
+        throw error;
+      }
+    );
+    this.#evicting.set(index, write);
+    return write;
+  }
+
   /**
    * Record how long a piece stayed on disk before it was wanted again.
    *
@@ -629,8 +927,16 @@ export class SharedPieceStore {
         this.#counters.fromMemory += 1;
         return already;
       }
-      const target = this.#watchForCollection(new SharedArrayBuffer(this.#lengthOf(index)));
-      await this.#disk.read(index, Buffer.from(target));
+      const target = this.#takeBlock();
+      try {
+        // Only this piece's own length: the block is a full piece long and the
+        // last piece of a file is shorter, so reading the whole block would ask
+        // the file for bytes past its end.
+        await this.#disk.read(index, Buffer.from(target, 0, this.#lengthOf(index)));
+      } catch (error) {
+        this.#returnBlock(target);
+        throw error;
+      }
       this.#registerPiece(index, target);
       this.#counters.fromDisk += 1;
       this.#counters.revivals += 1;
@@ -641,6 +947,121 @@ export class SharedPieceStore {
     }
   }
 
+  /**
+   * A block to hold one piece: the most recently freed one, or a new one.
+   *
+   * Every block is a full piece long, whatever piece will live in it. The last
+   * piece of a file is shorter, and it occupies a full block with only its own
+   * bytes meaningful — `#lengthOf` is what decides how much is ever read out.
+   * Uniform blocks are what makes them interchangeable at all.
+   *
+   * Most recently freed first, deliberately: a few blocks then carry the whole
+   * of a busy store's traffic and the rest age out of use, which is what makes
+   * {@link SharedPieceStore#sweepFreeBlocks} able to tell a spare block from a
+   * working one.
+   *
+   * @returns {SharedArrayBuffer}
+   */
+  #takeBlock() {
+    const spare = this.#freeBlocks.pop();
+    if (spare !== undefined) {
+      this.#noteReuseGap(Date.now() - spare.freedAt);
+      return spare.buffer;
+    }
+    this.#blocksAllocated += 1;
+    return this.#watchForCollection(new SharedArrayBuffer(this.#chunkLength));
+  }
+
+  /**
+   * Put a block back for re-use, or give it up.
+   *
+   * Given up when the allowance has fallen below the number of blocks that
+   * exist: keeping it would hold memory the machine has just been shown to
+   * need. Otherwise it waits in the free list for the next piece.
+   *
+   * @param {SharedArrayBuffer | undefined} buffer
+   * @returns {void}
+   */
+  #returnBlock(buffer) {
+    if (buffer === undefined) {
+      return;
+    }
+    if (this.#closed || this.#blocksAllocated > this.#growthCeiling) {
+      // Never below zero: `close` gives up every block at once, and a spill
+      // that was already in flight resolves afterwards and arrives here.
+      if (this.#blocksAllocated > 0) {
+        this.#blocksAllocated -= 1;
+        this.#counters.blocksReleased += 1;
+      }
+      return;
+    }
+    this.#freeBlocks.push({ buffer, freedAt: Date.now() });
+  }
+
+  /**
+   * Record how long a block waited to be used again.
+   *
+   * @param {number} gapMs
+   * @returns {void}
+   */
+  #noteReuseGap(gapMs) {
+    this.#reuseGaps.push(Math.max(0, gapMs));
+    if (this.#reuseGaps.length > REUSE_GAP_SAMPLES) {
+      this.#reuseGaps.shift();
+    }
+  }
+
+  /**
+   * The longest a block has recently waited before being wanted again, or null
+   * when no block has yet been re-used.
+   *
+   * This is the store's own working rhythm, measured rather than chosen: while
+   * a film is being watched a block is taken again within milliseconds, because
+   * one is taken for every piece that arrives. A block that has been sitting
+   * longer than the longest of those waits is not part of the work.
+   *
+   * @returns {number | null}
+   */
+  #reuseGapCeilingMs() {
+    if (this.#reuseGaps.length === 0) {
+      return null;
+    }
+    return Math.max(...this.#reuseGaps);
+  }
+
+  /**
+   * Give up blocks that have sat unused longer than this store's own working
+   * rhythm.
+   *
+   * The case it is for: a torrent whose peers have gone. Its readers are still
+   * attached, so nothing removes the torrent — the pool's idle timer needs a
+   * refcount of zero and never starts. Its allowance falls to what those
+   * readers declared, the pieces beyond it are written out, and their blocks
+   * would otherwise wait in the free list for peers that may not return.
+   *
+   * @param {number} [now]
+   * @returns {number} Blocks given up.
+   */
+  sweepFreeBlocks(now = Date.now()) {
+    const ceiling = this.#reuseGapCeilingMs();
+    if (ceiling === null) {
+      return 0;
+    }
+    const keeping = [];
+    let released = 0;
+    for (const spare of this.#freeBlocks) {
+      if (now - spare.freedAt <= ceiling) {
+        keeping.push(spare);
+        continue;
+      }
+      this.#blocksAllocated -= 1;
+      this.#counters.blocksReleased += 1;
+      released += 1;
+    }
+    this.#freeBlocks = keeping;
+    return released;
+  }
+
   /**
    * Count this buffer as one this thread will have to let go of, and notice
    * when the collector takes it. See {@link pieceBufferCollection}.
@@ -663,14 +1084,14 @@ export class SharedPieceStore {
    */
   #copyIntoNewBuffer(index, bytes) {
     const length = this.#lengthOf(index);
-    const sab = this.#watchForCollection(new SharedArrayBuffer(length));
-    const view = Buffer.from(sab);
+    const block = this.#takeBlock();
+    const view = Buffer.from(block, 0, length);
     if (bytes.copy) {
       bytes.copy(view, 0, 0, length);
     } else {
       view.set(bytes.subarray(0, length), 0);
     }
-    return sab;
+    return block;
   }
 
   /**
@@ -704,13 +1125,46 @@ export class SharedPieceStore {
       // needed and none is claimed. A fresh buffer rather than a write into the
       // old one, so a reader holding the old reference cannot see a torn write.
       if (this.#buffers.has(index)) {
+        const previous = this.#buffers.get(index);
+        // A fresh block rather than a write into the old one, so a reader
+        // holding the old reference cannot see a torn write.
         this.#buffers.set(index, this.#copyIntoNewBuffer(index, bytes));
         this.#lru.touch(index);
+        // And the old block goes back for re-use only if nobody is reading it.
+        // A pinned piece has a view onto its memory somewhere; that block is
+        // given up instead, and the pool allocates another when it needs one.
+        if (this.#lru.isPinned(index)) {
+          if (this.#blocksAllocated > 0) {
+            this.#blocksAllocated -= 1;
+            this.#counters.blocksReleased += 1;
+          }
+        } else {
+          this.#returnBlock(previous);
+        }
         await this.#forgetOnDisk(index);
         this.#noteProgress();
         return;
       }
 
+      const declared = this.#lru.wants(index);
+      if (declared) {
+        this.#counters.admittedInsideWindow += 1;
+      } else {
+        this.#counters.admittedOutsideWindow += 1;
+      }
+
+      // A piece no reader has declared, arriving at a store with no room, goes
+      // straight to disk. It costs the same one write it would have cost when
+      // the next arrival evicted it, and it saves pushing out a piece a reader
+      // is about to read. Only when SOMETHING is declared: before the first
+      // read there is no basis for calling a piece unwanted.
+      if (!declared && this.#lru.protectedCount > 0 && this.#isFullNow()) {
+        this.#counters.admittedToDisk += 1;
+        await this.#writeThrough(index, bytes);
+        this.#noteProgress();
+        return;
+      }
+
       const release = await this.#claimSlot();
       try {
         this.#registerPiece(index, this.#copyIntoNewBuffer(index, bytes));
@@ -806,6 +1260,9 @@ export class SharedPieceStore {
     liveStores.delete(this);
     this.#buffers.clear();
     this.#spilledAt.clear();
+    this.#counters.blocksReleased += this.#blocksAllocated;
+    this.#blocksAllocated = 0;
+    this.#freeBlocks = [];
     // Whoever is waiting for a slot is woken and finds the store closed, which
     // is an error they can report. Left asleep they simply never returned.
     this.#wake();
@@ -817,6 +1274,9 @@ export class SharedPieceStore {
     liveStores.delete(this);
     this.#buffers.clear();
     this.#spilledAt.clear();
+    this.#counters.blocksReleased += this.#blocksAllocated;
+    this.#blocksAllocated = 0;
+    this.#freeBlocks = [];
     this.#wake();
     this.#disk.destroy().then(() => callback(null), (error) => callback(error));
   }

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,11 +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}/` +
-      `${stats.evictedProtected}/${stats.demand?.unionPieces ?? 0}`;
+      `${stats.evictedProtected}/${stats.demand?.unionPieces ?? 0}/${stats.admittedToDisk}/` +
+      `${stats.blocksAllocated}/${stats.blocksFree}/${stats.blocksReleased}`;
     if (lastReported.get(stats.name) === signature) {
       continue;
     }
@@ -581,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}` +
@@ -615,19 +641,34 @@ setInterval(() => {
         (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)`)
+            `${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}
  */
@@ -639,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-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 });
+  }
+});