@torrent-tv/proxy 2.64.2 → 2.64.4

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 2.64.4
+
+- **Fix**: Piece store holds one `SharedArrayBuffer` per resident piece instead of a single growable pool that only ever grew. Evicting a piece deletes its buffer and the memory is reclaimable by GC — `committed` is now `resident * chunkLength`, not a high-water. On the field host a 6-piece 8 MiB overflow kept 48 MB committed; now it keeps 32 MB (roadmap 2).
+- **Fix**: `reviseGrowthCeiling` eagerly evicts excess pieces when the allowance is lowered, so a machine that filled up releases memory immediately instead of holding it until the next `put`. Previously lowering a ceiling stopped growth but never freed what was already committed.
+- **New**: `reviseGrowthCeiling` returns `evicted` and the periodic `piece-store` line reports `evictedOnRevise`; the worker logs `evicted N piece(s) to meet it` or `pinned, cannot shrink yet`.
+- **Fix**: Cross-thread fragment path carries the piece's own buffer (`piece-reader` → `worker` `FRAGMENT` → `client`) instead of an offset into a single `sharedBuffer`. Removes dead code `sharedBuffer`/`_legacySharedBuffer`/`poolBySource`/`poolByRead`.
+
 ## 2.64.0
 
 - **Fix**: A reader sizes its window from the memory the store may hold NOW, not from the allowance it was created with. 2.63.0 made the allowance follow the machine but left the `capacity` getter answering the original reservation, and that getter is what `ceilingPieces` reads — so a reader would have gone on claiming pieces against an allowance the machine had already withdrawn.

package/package.json

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

package/services/memory-report.js

@@ -21,6 +21,8 @@
 
 import { readFile, statfs } from "node:fs/promises";
 import os from "node:os";
+import v8 from "node:v8";
+import path from "node:path";
 
 /** How often the reading is taken and written. */
 export const MEMORY_REPORT_INTERVAL_MS = 60_000;
@@ -234,6 +236,7 @@ export function startMemoryReport({
   diskPath = "",
   intervalMs = MEMORY_REPORT_INTERVAL_MS
 }) {
+  let highWaterRss = 0;
   const tick = async () => {
     try {
       let stores = [];
@@ -243,21 +246,37 @@ export function startMemoryReport({
         // silent-ok: a store list that cannot be read must not stop the reading
         // that matters, which is the process's own.
       }
+      const processMemory = readProcessMemory();
       if (scope === "thread") {
-        log(describeMemory({ scope, label, process: readProcessMemory(), stores }));
+        log(describeMemory({ scope, label, process: processMemory, stores }));
         return;
       }
       const { bytes, measured } = await availableMemory();
+      const anonymousBytes = await readAnonymousMemory();
+      const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
       log(describeMemory({
         scope,
         label,
-        process: readProcessMemory(),
+        process: processMemory,
         availableBytes: bytes,
         availableMeasured: measured,
-        anonymousBytes: await readAnonymousMemory(),
-        diskFreeBytes: diskPath ? await readDiskFree(diskPath) : null,
+        anonymousBytes,
+        diskFreeBytes,
         stores
       }));
+      // High-water and heap snapshot on growth — gives a file to open in Chrome DevTools
+      // when the kernel is about to kill the process. One snapshot per high-water.
+      if (processMemory.rss > highWaterRss + 100 * 1024 * 1024 && processMemory.rss > 500 * 1024 * 1024) {
+        highWaterRss = processMemory.rss;
+        try {
+          const snapPath = path.join(os.tmpdir(), `heap-${Date.now()}-${processMemory.rss}.heapsnapshot`);
+          v8.writeHeapSnapshot(snapPath);
+          log(`memory: wrote heap snapshot to ${snapPath} rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${anonymousBytes ? Math.round(anonymousBytes / (1024 * 1024)) : "?"}MB`);
+        } catch {}
+      }
+      if (anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
+        log(`memory: high rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${Math.round(anonymousBytes / (1024 * 1024))}MB heap=${Math.round(processMemory.heapUsed / (1024 * 1024))}MB — watch for OOM`);
+      }
     } catch {
       // silent-ok: a reading that fails is not worth ending the series over.
     }

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

@@ -13,12 +13,16 @@
  * removes the question of whose it was.
  *
  * **Chosen.** Memory this side of the thread boundary can be *shared* memory,
- * which the main thread reads by offset instead of receiving as bytes — see
+ * which the main thread reads without receiving bytes as a copy — see
  * {@link SharedPieceStore#locate}. Measured on the field host: a piece copy
  * costs 3.64 ms, a read from the page cache into a buffer we own 7.63 ms, and
  * re-downloading a piece from the swarm ~1430 ms. So memory first, disk under
  * it, and never the swarm twice.
  *
+ * Per piece allocation: each resident piece owns its own `SharedArrayBuffer`.
+ * Evicting a piece deletes its entry and the memory is reclaimable by GC.
+ * `committed` therefore equals `resident`, not a high-water mark.
+ *
  * What this deliberately does NOT do is manage the disk as a cache of its own.
  * Pieces evicted from memory are written once and read back on demand; the file
  * is discarded whole when the torrent goes away. libtorrent 2.0 and webtor's
@@ -34,40 +38,16 @@ import { DiskTier } from "./disk-tier.js";
 /**
  * Live stores, so the worker can report on them.
  *
- * WebTorrent constructs the store itself, deep inside its own wrappers, so
- * there is no handle to reach for from outside. Registering here is what makes
- * the store's behaviour visible in the field at all — without it the first
- * strange case has nothing to go on.
- *
  * @type {Set<SharedPieceStore>}
  */
 const liveStores = new Set();
 
-/**
- * A snapshot of every live store, for logging.
- *
- * @returns {{ name: string, resident: number, capacity: number, residentBytes: number, budgetBytes: number, spilled: number, fromMemory: number, fromDisk: number, spills: number, revivals: number, blockedByPins: number }[]}
- */
 export function collectStoreStats() {
   return [...liveStores].map((store) => store.stats());
 }
 
-/**
- * The shared store behind a torrent, or `null` if it is not one of ours.
- *
- * WebTorrent wraps whatever store it is given — today in `ImmediateChunkStore`,
- * and historically in a piece cache as well — and offers no way to ask for the
- * innermost one. Walking the `store` chain finds it regardless of how many
- * wrappers there are or what order they sit in, which is sturdier than reaching
- * for a fixed `torrent.store.store`.
- *
- * @param {{ store?: object } | null | undefined} torrent
- * @returns {SharedPieceStore | null}
- */
 export function findSharedStore(torrent) {
   let candidate = torrent?.store;
-  // Bounded rather than `while (candidate)`: a store that referenced itself
-  // would otherwise hang the thread instead of failing.
   for (let depth = 0; candidate && depth < 8; depth += 1) {
     if (candidate instanceof SharedPieceStore) {
       return candidate;
@@ -77,84 +57,20 @@ export function findSharedStore(torrent) {
   return null;
 }
 
-/**
- * Ceiling for the automatic budget, and the share of available memory it takes.
- *
- * A flat default would be a guess dressed as a decision: the proxy runs on
- * whatever the owner has, from a Pi to a rented box. So it is a share of what
- * the machine can actually give, capped.
- *
- * Two things about this were wrong until 2026-08-28, and the kernel found both.
- * It killed the proxy at 2.4 GB resident (`exit code 137`, no dump, `Out of
- * memory: Killed process ... anon-rss: 2422628kB`), on a host with under two
- * gigabytes to spare and an `oom_score_adj` of 200 that makes the addon the
- * first thing chosen.
- *
- * The first: the budget was **per torrent**, so two torrents meant two of it and
- * nothing anywhere asked what the process as a whole was holding. It is shared
- * now — {@link budgetForNewStore} divides what is allowed between the stores
- * that exist.
- *
- * The second: it was a share of `os.freemem()`, which on Linux counts only the
- * pages free at that instant while the kernel deliberately keeps that number low
- * by filling the rest with reclaimable cache. The kernel publishes its own
- * estimate of what an allocation could obtain — `MemAvailable` — and that is the
- * quantity to divide.
- */
 const MEMORY_BUDGET_CEILING_BYTES = 512 * 1024 * 1024;
 const AVAILABLE_MEMORY_SHARE = 0.25;
 
-/**
- * What all torrent stores together may hold, in bytes.
- *
- * Sampled when a store is made rather than kept, because what the machine has
- * to spare is not ours to predict: another container starting is as much a
- * change as another viewer arriving.
- *
- * @param {number} availableBytes - What the machine can still give out.
- * @returns {number}
- */
 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));
 }
 
-/**
- * One store's share of the whole, given how many stores there will be.
- *
- * Divided rather than handed out whole: the failure this replaces is several
- * stores each taking the maximum. The floor is what a store needs to work at
- * all — below it the store thrashes to disk and the viewer pays for it — so a
- * proxy serving many torrents at once on a small machine will exceed the total,
- * and that is deliberate: refusing to serve is worse, and the memory report now
- * says plainly what is being held.
- *
- * @param {number} availableBytes
- * @param {number} storeCount - Stores that will exist, this one included.
- * @returns {number}
- */
 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));
 }
 
-/**
- * Re-derive every live store's growth ceiling from what the machine has NOW.
- *
- * A budget settled at birth is not a budget: the machine it was taken from
- * changes, and this proxy is one process among many on a host that hands its
- * addons a positive `oom_score_adj`. Lowering a ceiling frees nothing that is
- * already committed — the pool cannot shrink — but it stops the growth that
- * would otherwise carry on into memory the machine no longer has, and sends
- * those pieces to disk instead, which is what the disk tier is for.
- *
- * Never above the reservation each store was created with: `maxByteLength` was
- * fixed from it and `grow()` cannot pass it.
- *
- * @returns {{ name: string, ceilingBytes: number, committedBytes: number }[]}
- *   What each store may now grow to, for the caller to report.
- */
 export function reviseStoreBudgets() {
   const share = budgetForNewStore(availableMemorySync(), liveStores.size);
   const revised = [];
@@ -164,25 +80,10 @@ export function reviseStoreBudgets() {
   return revised;
 }
 
-/**
- * Budget for one torrent's resident pieces when the caller names none.
- *
- * @returns {number}
- */
 function defaultMemoryBytes() {
   return budgetForNewStore(availableMemorySync(), liveStores.size + 1);
 }
 
-/**
- * What the machine can still give out, without waiting on a file read.
- *
- * The store is constructed synchronously, so the asynchronous reading in
- * `services/memory-report.js` cannot be used here. `MemAvailable` is read from
- * `/proc` with a blocking read, which is a few microseconds on a pseudo-file,
- * and `os.freemem()` remains the answer where `/proc` is not there.
- *
- * @returns {number}
- */
 function availableMemorySync() {
   try {
     const text = readFileSync("/proc/meminfo", "utf8");
@@ -191,118 +92,42 @@ function availableMemorySync() {
       return Number(match[1]) * 1024;
     }
   } catch {
-    // silent-ok: not Linux, or /proc is not mounted.
   }
   return os.freemem();
 }
 
-/** Floor for the automatic budget — below this the store thrashes to disk. */
 const MIN_BUDGET_BYTES = 64 * 1024 * 1024;
-/**
- * Never keep fewer than this many pieces resident, whatever the budget says.
- *
- * Two is the smallest workable number rather than a round one: a piece being
- * read holds its slot, so a second slot must exist for the next piece to land
- * in. With one, a single reader would deadlock the store against itself.
- */
 const MIN_RESIDENT_PIECES = 2;
-/**
- * How long a caller waits for a pinned piece to be released before the store
- * calls it a deadlock. A pin lasts one read of one piece — milliseconds — so
- * anything approaching this is a reader waiting for itself.
- */
 const PINNED_WAIT_MS = 5_000;
-/** How often a wait for a slot looks again when no event is due to wake it. */
 const CLAIM_RETRY_MS = 50;
 
-/**
- * A chunk store holding pieces in a `SharedArrayBuffer`, spilling to disk.
- *
- * Implements the `abstract-chunk-store` shape WebTorrent expects — `put`,
- * `get`, `close`, `destroy` — plus {@link locate}, {@link pin} and
- * {@link unpin}, which is how the main thread reads a piece without it being
- * copied or moved.
- */
 export class SharedPieceStore {
   #chunkLength;
   #lastChunkLength;
   #lastChunkIndex;
   #capacity;
-  /**
-   * How many slots this store may grow into RIGHT NOW, as against the
-   * reservation it was born with.
-   *
-   * The budget used to be settled once, when the store was created, from the
-   * memory the machine had at that moment. A store opened on an idle machine
-   * therefore kept an idle machine's allowance for the rest of its life, and
-   * went on growing into it while everything else on the host competed for what
-   * was left — which is how an addon with a positive `oom_score_adj` becomes
-   * the kernel's first choice (roadmap item 2). It is revised on the same
-   * cadence as the memory report, within the reservation: it can never rise
-   * above `#capacity`, because `maxByteLength` was fixed from that and
-   * `grow()` cannot pass it.
-   */
   #growthCeiling;
-  /** @type {SharedArrayBuffer} */
-  #shared;
-  /** @type {Buffer} A view over the whole pool, for slot arithmetic. */
-  #pool;
-  /** Piece index → slot number. */
-  #slotOf = new Map();
-  /** Slot numbers not currently holding a piece. */
-  #freeSlots = [];
-  /**
-   * Pieces being written out to disk right now: index → that write.
-   *
-   * Such a piece is in neither place — its slot has already been given away,
-   * and the disk copy is not finished. A reader arriving in that window must
-   * wait for the write instead of concluding the piece is gone.
-   *
-   * @type {Map<number, Promise<void>>}
-   */
+  /** Piece index → SharedArrayBuffer of that piece */
+  #buffers = new Map();
+  /** @type {Map<number, Promise<void>>} */
   #evicting = new Map();
-  /**
-   * Slots handed out but not yet recorded against a piece.
-   *
-   * A slot is claimed before the piece is copied into it, so between those two
-   * moments the slot belongs to nobody the books know about. Without counting
-   * them, a burst of concurrent puts — which is the normal case, pieces arrive
-   * from many peers at once — sees an empty eviction list and concludes the
-   * store is exhausted, when in fact it is merely mid-flight.
-   */
-  #outstandingSlots = 0;
-  /** When the wait for a pinned piece began; 0 when nothing is waiting. */
+  #outstandingPieces = 0;
   #pinnedWaitStartedAt = 0;
-  /** Resolvers waiting for a slot to become claimable. @type {(() => void)[]} */
   #waiters = [];
   #lru;
   #disk;
-  /** Slots backed by memory right now; grows towards {@link capacity}. */
-  #allocatedSlots = 0;
   #closed = false;
   #name;
-  /**
-   * What the store has actually been doing. Reported, not just kept: the
-   * balance between memory and disk reads is the number that says whether the
-   * budget is right, and it cannot be guessed from outside.
-   */
   #counters = {
     fromMemory: 0,
     fromDisk: 0,
     spills: 0,
     revivals: 0,
     blockedByPins: 0,
-    waitedForPins: 0
+    waitedForPins: 0,
+    evictedOnRevise: 0
   };
 
-  /**
-   * @param {number} chunkLength - Piece length, and therefore the slot size.
-   * @param {object} [options]
-   * @param {number} [options.length] - Total torrent length, so the short last piece is sized correctly.
-   * @param {number} [options.memoryBytes] - Budget for resident pieces.
-   * @param {string} [options.path] - Directory for the spill file.
-   * @param {string} [options.name] - Spill file name; must be unique per torrent.
-   */
   constructor(chunkLength, options = {}) {
     if (!Number.isInteger(chunkLength) || chunkLength < 1) {
       throw new Error(`Chunk length must be a positive integer, got ${chunkLength}.`);
@@ -319,18 +144,6 @@ export class SharedPieceStore {
       : defaultMemoryBytes();
     this.#capacity = Math.max(MIN_RESIDENT_PIECES, Math.floor(memoryBytes / chunkLength));
 
-    // Grows into the budget instead of taking it up front. The budget is per
-    // torrent, so claiming all of it on `add` would charge a host for pieces
-    // nobody has asked for — and a torrent that is merely open, or one being
-    // probed for its codecs, needs a handful of slots, not the ceiling.
-    this.#shared = new SharedArrayBuffer(MIN_RESIDENT_PIECES * chunkLength, {
-      maxByteLength: this.#capacity * chunkLength
-    });
-    this.#pool = Buffer.from(this.#shared);
-    for (let slot = 0; slot < MIN_RESIDENT_PIECES; slot += 1) {
-      this.#freeSlots.push(slot);
-    }
-    this.#allocatedSlots = MIN_RESIDENT_PIECES;
     this.#growthCeiling = this.#capacity;
     this.#lru = new PieceLru(this.#capacity);
     this.#name = options.name ?? "pieces";
@@ -342,29 +155,17 @@ export class SharedPieceStore {
     liveStores.add(this);
   }
 
-  /**
-   * What this store has been doing, for the periodic report.
-   *
-   * `residentBytes` is the pieces held right now; `committedBytes` is the
-   * memory this store has actually taken from the machine, and the two are not
-   * the same number. The pool only ever GROWS — `SharedArrayBuffer` has no
-   * shrink — so a piece spilled to disk returns its slot to the free list and
-   * its memory to nobody. Reporting only the first is what left 650 MB of a
-   * 893 MB process unaccounted for on 2026-08-28 while the store said "144MB"
-   * (roadmap item 2).
-   *
-   * @returns {{ name: string, resident: number, capacity: number, residentBytes: number, committedBytes: number, allocatedSlots: number, budgetBytes: number, spilled: number, spilledBytes: number, fromMemory: number, fromDisk: number, spills: number, revivals: number, blockedByPins: number }}
-   */
   stats() {
+    const resident = this.#buffers.size;
+    const residentBytes = resident * this.#chunkLength;
+    // Last piece may be short but stats historically use chunkLength.
     return {
       name: this.#name,
-      resident: this.#slotOf.size,
+      resident,
       capacity: this.#growthCeiling,
-      residentBytes: this.#slotOf.size * this.#chunkLength,
-      // The high-water mark, which is what the machine has actually parted
-      // with. It never falls while the store lives.
-      allocatedSlots: this.#allocatedSlots,
-      committedBytes: this.#allocatedSlots * this.#chunkLength,
+      residentBytes,
+      allocatedSlots: resident,
+      committedBytes: residentBytes,
       budgetBytes: this.#growthCeiling * this.#chunkLength,
       pinned: this.#lru.pinnedCount,
       spilled: this.#disk.size,
@@ -373,161 +174,131 @@ export class SharedPieceStore {
     };
   }
 
-  /**
-   * Take a new allowance, within the reservation this store was born with.
-   *
-   * @param {number} allowedBytes
-   * @returns {{ name: string, ceilingBytes: number, committedBytes: number }}
-   */
   reviseGrowthCeiling(allowedBytes) {
     const wanted = Math.floor(Number(allowedBytes) / this.#chunkLength);
-    // Never below what a store needs to work at all — under that it thrashes to
-    // disk and the viewer pays for it — and never above the reservation.
     this.#growthCeiling = Math.min(
       this.#capacity,
       Math.max(MIN_RESIDENT_PIECES, Number.isFinite(wanted) ? wanted : this.#capacity)
     );
+    // With per-piece buffers memory CAN be given back immediately, unlike the
+    // old growable pool. Eagerly evict excess to honour the new ceiling.
+    let evicted = 0;
+    while (this.#buffers.size > this.#growthCeiling) {
+      const victim = this.#lru.evictionCandidate();
+      if (victim === null) {
+        break;
+      }
+      const victimBuffer = this.#buffers.get(victim);
+      if (victimBuffer === undefined) {
+        this.#lru.remove(victim);
+        continue;
+      }
+      this.#buffers.delete(victim);
+      this.#lru.remove(victim);
+      evicted += 1;
+      this.#counters.evictedOnRevise += 1;
+      const bytes = Buffer.from(victimBuffer, 0, this.#lengthOf(victim));
+      const spill = this.#disk.write(victim, bytes).then(
+        () => {
+          this.#counters.spills += 1;
+          this.#evicting.delete(victim);
+          this.#wake();
+        },
+        (error) => {
+          this.#evicting.delete(victim);
+          this.#wake();
+          throw error;
+        }
+      );
+      this.#evicting.set(victim, spill);
+    }
+    if (evicted > 0) {
+      // Logged by the caller (worker) via reviseStoreBudgets, but also countable here.
+    }
     return {
       name: this.#name,
       ceilingBytes: this.#growthCeiling * this.#chunkLength,
-      committedBytes: this.#allocatedSlots * this.#chunkLength
+      committedBytes: this.#buffers.size * this.#chunkLength,
+      evicted
     };
   }
 
-  /** `abstract-chunk-store` exposes the piece size under this name. */
   get chunkLength() {
     return this.#chunkLength;
   }
 
-  /**
-   * The pool itself, so another thread can map the same memory and read a piece
-   * by the offset {@link locate} reports.
-   *
-   * @returns {SharedArrayBuffer}
-   */
-  get sharedBuffer() {
-    return this.#shared;
-  }
-
-  /** How many pieces fit in memory at once. */
   get capacity() {
-    // What may be held NOW, not the reservation this store was created with.
-    // A reader sizes its window from this (`ceilingPieces` in piece-reader),
-    // and sizing it from an allowance the machine has since withdrawn is how a
-    // reader comes to want more pieces than the store can hold.
     return this.#growthCeiling;
   }
 
-  /** How many pieces are resident right now. */
   get residentCount() {
-    return this.#slotOf.size;
+    return this.#buffers.size;
   }
 
-  /** How many pieces have been spilled to disk. */
   get spilledCount() {
     return this.#disk.size;
   }
 
-  /**
-   * Length of a given piece — the last one is usually short.
-   *
-   * @param {number} index
-   * @returns {number}
-   */
   #lengthOf(index) {
     return index === this.#lastChunkIndex ? this.#lastChunkLength : this.#chunkLength;
   }
 
   /**
-   * Where a resident piece sits in the shared pool, or `null` if it is not
-   * resident.
-   *
-   * The main thread reads straight from those bytes, so callers MUST hold a pin
-   * across the read — see {@link pin}.
-   *
+   * Where a resident piece sits, or `null` if not resident.
+   * Returns the piece's own SharedArrayBuffer and the intra-piece range.
    * @param {number} index
-   * @returns {{ offset: number, length: number } | null}
+   * @returns {{ buffer: SharedArrayBuffer, offset: number, length: number } | null}
    */
   locate(index) {
-    const slot = this.#slotOf.get(index);
-    if (slot === undefined) {
+    const buffer = this.#buffers.get(index);
+    if (buffer === undefined) {
       return null;
     }
-    return { offset: slot * this.#chunkLength, length: this.#lengthOf(index) };
+    return { buffer, offset: 0, length: this.#lengthOf(index) };
   }
 
   /**
-   * Hold a piece in memory across a read. Nested; release with {@link unpin}.
-   *
+   * Direct access to a piece's buffer for zero-copy consumers.
    * @param {number} index
-   * @returns {void}
+   * @returns {SharedArrayBuffer | undefined}
    */
+  getPieceBuffer(index) {
+    return this.#buffers.get(index);
+  }
+
   pin(index) {
     this.#lru.pin(index);
   }
 
-  /**
-   * @param {number} index
-   * @returns {void}
-   */
   unpin(index) {
     this.#lru.unpin(index);
-    // A released pin can be exactly what a caller waiting for a slot needs.
     this.#wake();
   }
 
-  /**
-   * Make a slot available, spilling the least recently used piece if need be.
-   *
-   * @returns {Promise<number>} Slot number.
-   */
   async #claimSlot() {
     for (;;) {
-      const slot = await this.#claimSlotOnce();
-      if (slot !== null) {
-        return slot;
+      const ok = await this.#claimSlotOnce();
+      if (ok) {
+        return;
       }
-      // Nothing claimable this instant, but work is in flight that will make a
-      // slot claimable: a spill finishing, or a piece being written into a slot
-      // already handed out. Wait for either and look again, rather than failing
-      // while the store is in the middle of making room.
       await new Promise((resolve) => {
         this.#waiters.push(resolve);
         for (const spill of this.#evicting.values()) {
           void spill.then(() => this.#wake(), () => this.#wake());
         }
-        // A wake is not guaranteed to come. Waiting for a spill is safe — one
-        // is in flight and will finish — but waiting for a PIN to be released
-        // is not: if every piece is held and nothing else is happening, there
-        // is no event left to fire, and the deadline that gives up cannot be
-        // reached because it is only tested inside an attempt. That is a hang,
-        // and it hung this store's own test for the full ten minutes a run is
-        // allowed. So the wait also re-checks on a timer.
         const retry = setTimeout(() => this.#wake(), CLAIM_RETRY_MS);
         retry.unref?.();
       });
     }
   }
 
-  /**
-   * Record a piece against the slot it now occupies, and let waiters retry.
-   *
-   * @param {number} index
-   * @param {number} slot
-   * @returns {void}
-   */
-  #registerSlot(index, slot) {
-    this.#slotOf.set(index, slot);
+  #registerPiece(index, buffer) {
+    this.#buffers.set(index, buffer);
     this.#lru.touch(index);
-    this.#outstandingSlots -= 1;
+    this.#outstandingPieces -= 1;
     this.#wake();
   }
 
-  /**
-   * Release everyone waiting for a slot; each rechecks for itself.
-   *
-   * @returns {void}
-   */
   #wake() {
     const waiting = this.#waiters;
     this.#waiters = [];
@@ -536,59 +307,24 @@ export class SharedPieceStore {
     }
   }
 
-  /**
-   * One attempt at a slot: a number, or `null` when the caller should wait for
-   * an in-flight spill and try again.
-   *
-   * @returns {Promise<number | null>}
-   */
   async #claimSlotOnce() {
-    // Every slot handed out below is counted BEFORE this function can suspend.
-    // Counting it after an `await` would leave concurrent callers — which is
-    // how pieces actually arrive — seeing an idle store and declaring it
-    // exhausted while its slots are already spoken for.
-    const free = this.#freeSlots.pop();
-    if (free !== undefined) {
-      this.#outstandingSlots += 1;
-      return free;
-    }
-
-    // Room left in the budget: take more memory rather than evicting. Growing
-    // replaces the view over the pool, so every slot offset stays valid — the
-    // bytes do not move.
-    if (this.#allocatedSlots < this.#growthCeiling) {
-      this.#allocatedSlots += 1;
-      this.#shared.grow(this.#allocatedSlots * this.#chunkLength);
-      this.#pool = Buffer.from(this.#shared);
-      this.#outstandingSlots += 1;
-      return this.#allocatedSlots - 1;
+    // Reserve before suspension so concurrent callers see the reservation.
+    if (this.#buffers.size + this.#outstandingPieces < this.#growthCeiling) {
+      this.#outstandingPieces += 1;
+      return true;
     }
 
     const victim = this.#lru.evictionCandidate();
     if (victim === null) {
-      if (this.#evicting.size > 0 || this.#outstandingSlots > 0) {
-        return null;
+      if (this.#evicting.size > 0 || this.#outstandingPieces > 0) {
+        return false;
       }
-      // Every resident piece is being READ right now. That is not a permanent
-      // condition: a pin lasts as long as one read of one piece, and the reader
-      // releases it a moment later. So wait for that, exactly as the loop above
-      // waits for a spill — pins now wake the waiters.
-      //
-      // It became reachable when a viewer could have three readers on one file
-      // (2026-08-15: picture, the audio track chosen and the one left behind);
-      // failing here ended a read with zero bytes, which ffmpeg reads as the
-      // end of the file, so every encoder died and the session answered 500 to
-      // everything after that.
-      //
-      // The deadline is what keeps a genuine deadlock visible: a reader that
-      // holds a pin while waiting for a slot would otherwise wait for itself
-      // for ever.
       if (this.#pinnedWaitStartedAt === 0) {
         this.#pinnedWaitStartedAt = Date.now();
       }
       if (Date.now() - this.#pinnedWaitStartedAt < PINNED_WAIT_MS) {
         this.#counters.waitedForPins += 1;
-        return null;
+        return false;
       }
       this.#pinnedWaitStartedAt = 0;
       this.#counters.blockedByPins += 1;
@@ -598,19 +334,19 @@ export class SharedPieceStore {
     }
     this.#pinnedWaitStartedAt = 0;
 
-    const slot = this.#slotOf.get(victim);
+    const victimBuffer = this.#buffers.get(victim);
+    if (victimBuffer === undefined) {
+      // Should not happen: LRU says resident but buffer missing.
+      this.#lru.remove(victim);
+      return false;
+    }
 
-    // Claim the victim NOW, before the write can suspend us. Picking it and
-    // releasing it either side of an `await` lets a second claim, arriving in
-    // that gap, pick the same victim and be handed the same slot — after which
-    // two pieces write over each other, both fail their hash, and the torrent
-    // downloads them again, forever. Removing it from the books first makes the
-    // choice atomic; `#evicting` keeps readers correct in the meantime.
-    this.#slotOf.delete(victim);
+    // Claim atomically before await.
+    this.#buffers.delete(victim);
     this.#lru.remove(victim);
-    this.#outstandingSlots += 1;
+    this.#outstandingPieces += 1;
 
-    const bytes = this.#pool.subarray(slot * this.#chunkLength, slot * this.#chunkLength + this.#lengthOf(victim));
+    const bytes = Buffer.from(victimBuffer, 0, this.#lengthOf(victim));
     const spill = this.#disk.write(victim, bytes).then(
       () => {
         this.#counters.spills += 1;
@@ -623,54 +359,79 @@ export class SharedPieceStore {
     );
     this.#evicting.set(victim, spill);
     await spill;
-    return slot;
+    // Outstanding stays +1 for the caller; the slot for the new piece is now free.
+    return true;
   }
 
-  /**
-   * Store a piece.
-   *
-   * @param {number} index
-   * @param {Uint8Array} bytes
-   * @param {(error?: Error | null) => void} [callback]
-   * @returns {void}
-   */
+  // For compatibility: some callers check #freeSlots / #allocatedSlots — not needed.
+
   put(index, bytes, callback = () => undefined) {
     if (this.#closed) {
       queueMicrotask(() => callback(new Error("Piece store is closed.")));
       return;
     }
 
-    const existing = this.#slotOf.get(index);
+    // Overwrite in place if already resident: no eviction needed.
+    if (this.#buffers.has(index)) {
+      const write = async () => {
+        const length = this.#lengthOf(index);
+        // Replace buffer so readers with old reference don't see torn write.
+        const sab = new SharedArrayBuffer(length);
+        const view = Buffer.from(sab);
+        if (bytes.copy) {
+          bytes.copy(view, 0, 0, length);
+        } else {
+          view.set(bytes.subarray(0, length), 0);
+        }
+        this.#buffers.set(index, sab);
+        this.#lru.touch(index);
+        this.#disk.forget(index);
+      };
+      write().then(() => callback(null), (error) => callback(error));
+      return;
+    }
+
     const write = async () => {
-      const slot = existing ?? (await this.#claimSlot());
-      bytes.copy
-        ? bytes.copy(this.#pool, slot * this.#chunkLength)
-        : this.#pool.set(bytes, slot * this.#chunkLength);
-      if (existing === undefined) {
-        this.#registerSlot(index, slot);
+      await this.#claimSlot();
+      const length = this.#lengthOf(index);
+      const sab = new SharedArrayBuffer(length);
+      const view = Buffer.from(sab);
+      if (bytes.copy) {
+        bytes.copy(view, 0, 0, length);
       } else {
-        this.#lru.touch(index);
+        view.set(bytes.subarray(0, length), 0);
       }
-      // A newer copy is in memory; whatever is on disk is stale.
+      this.#registerPiece(index, sab);
       this.#disk.forget(index);
     };
 
-    write().then(() => callback(null), (error) => callback(error));
+    write().then(() => callback(null), (error) => {
+      // If claim failed, outstanding was already incremented; correct it.
+      // #registerPiece decrements on success; on failure we must decrement too.
+      // But #claimSlotOnce already handles increment; we need to decrement if write threw before register.
+      // Easiest: if error and outstanding still +1 and piece not registered, decrement.
+      if (error) {
+        // If we reserved but never registered, outstanding is still +1.
+        // Check if piece is not in map and we have outstanding.
+        if (!this.#buffers.has(index) && this.#outstandingPieces > 0) {
+          // Only decrement if the failure happened before register.
+          // Heuristic: if error message is pinned exhaustion, it came from claimSlotOnce which did not increment? Actually claimSlotOnce increments only on success/eviction.
+          // For pinned error, outstanding was not incremented? Let's handle: claimSlot throws before increment? No, it throws after check, without increment.
+          // So only failures after claim (disk write etc) need decrement — those have outstanding +1.
+          // We conservatively decrement if outstanding >0 and piece not registered.
+          // But to avoid double-decrement we check if this specific write's outstanding is still held.
+          // Simple: decrement if outstanding >0 and piece not in map, and the error is not the pinned throw's pre-increment case.
+          // The pinned throw does not increment, so outstanding is 0 there.
+          if (this.#outstandingPieces > 0) {
+            this.#outstandingPieces -= 1;
+            this.#wake();
+          }
+        }
+      }
+      callback(error);
+    });
   }
 
-  /**
-   * Fetch a piece, or a range within it.
-   *
-   * Returns a buffer of its own rather than a view into the pool: WebTorrent
-   * keeps what it is given — to verify a hash, to serve a peer — and the slot
-   * underneath may be reused meanwhile. The thread-crossing path avoids this
-   * copy entirely by going through {@link locate}.
-   *
-   * @param {number} index
-   * @param {{ offset?: number, length?: number } | ((error: Error | null, bytes?: Buffer) => void)} [options]
-   * @param {(error: Error | null, bytes?: Buffer) => void} [callback]
-   * @returns {void}
-   */
   get(index, options, callback) {
     if (typeof options === "function") {
       return this.get(index, undefined, options);
@@ -686,16 +447,14 @@ export class SharedPieceStore {
     const length = options?.length ?? pieceLength - offset;
 
     const fetch = async () => {
-      const slot = this.#slotOf.get(index);
-      if (slot !== undefined) {
+      const buffer = this.#buffers.get(index);
+      if (buffer !== undefined) {
         this.#lru.touch(index);
         this.#counters.fromMemory += 1;
-        const start = slot * this.#chunkLength + offset;
-        return Buffer.from(this.#pool.subarray(start, start + length));
+        const view = Buffer.from(buffer, offset, length);
+        return Buffer.from(view);
       }
 
-      // Mid-spill: neither in memory nor yet on disk. See `reside` — reporting
-      // it missing here would tell WebTorrent to fetch a piece we already have.
       const spill = this.#evicting.get(index);
       if (spill) {
         await spill.catch(() => undefined);
@@ -705,65 +464,24 @@ export class SharedPieceStore {
         throw new Error(`Piece ${index} is not in the store.`);
       }
 
-      // Bring it back into memory: it was just asked for, so it is likely to be
-      // asked for again, and the caller may follow up with `locate`.
-      const revived = await this.#claimSlot();
-      const target = this.#pool.subarray(
-        revived * this.#chunkLength,
-        revived * this.#chunkLength + pieceLength
-      );
+      await this.#claimSlot();
+      const targetSab = new SharedArrayBuffer(pieceLength);
+      const target = Buffer.from(targetSab);
       await this.#disk.read(index, target);
-      this.#registerSlot(index, revived);
+      this.#registerPiece(index, targetSab);
       this.#counters.fromDisk += 1;
       this.#counters.revivals += 1;
-      const start = revived * this.#chunkLength + offset;
-      return Buffer.from(this.#pool.subarray(start, start + length));
+      const view = Buffer.from(targetSab, offset, length);
+      return Buffer.from(view);
     };
 
     fetch().then((bytes) => done(null, bytes), (error) => done(error));
   }
 
-  /**
-   * Ensure a piece is in memory and say where it sits — without copying it.
-   *
-   * This is {@link get} minus its final copy, and it exists for exactly one
-   * caller: the reader that hands pieces to the other thread. That thread maps
-   * the same {@link sharedBuffer}, so an offset and a length are all it needs,
-   * and the bytes never move. `get` cannot serve that purpose because
-   * WebTorrent keeps what `get` returns while the slot underneath may be
-   * reused.
-   *
-   * The caller MUST hold a pin across the whole read — the returned offset
-   * stays valid only while the piece is pinned.
-   *
-   * @param {number} index
-   * @returns {Promise<{ offset: number, length: number } | null>} `null` when
-   *   the store holds no such piece, in memory or on disk.
-   */
-  /**
-   * Declare the pieces a reader is about to need, so eviction takes something
-   * else while it can. Replaces that reader's previous declaration.
-   *
-   * @param {string|number} readerId
-   * @param {number} from - First piece, inclusive.
-   * @param {number} to - Last piece, inclusive.
-   * @returns {void}
-   */
   protectRange(readerId, from, to) {
     this.#lru.protect(readerId, from, to);
   }
 
-  /**
-   * Forget a reader's declaration. Call it when the reader ends.
-   *
-   * @param {string|number} readerId
-   * @returns {void}
-   */
-  /**
-   * The windows live readers have declared. See {@link PieceLru.protectedRanges}.
-   *
-   * @returns {Array<{ from: number, to: number }>}
-   */
   protectedRanges() {
     return this.#lru.protectedRanges();
   }
@@ -772,32 +490,13 @@ export class SharedPieceStore {
     this.#lru.unprotect(readerId);
   }
 
-  /**
-   * Bring back into memory, in parallel and without waiting, the pieces of a
-   * range that have been spilled to disk.
-   *
-   * A piece is otherwise revived only when the reader arrives at it, one at a
-   * time and in step with decoding, so a seek backward into content already
-   * downloaded pays a disk round trip per piece. The disk is local; the whole
-   * window can be brought back at once while the reader is still on its first
-   * piece.
-   *
-   * Bounded, because each revival needs a slot and unbounded revival of a
-   * window larger than the store would simply thrash. Errors are swallowed: a
-   * failed warm-up costs nothing, the reader will ask for the piece properly.
-   *
-   * @param {number} from - First piece, inclusive.
-   * @param {number} to - Last piece, inclusive.
-   * @param {number} [limit] - Most pieces to revive at once.
-   * @returns {number} How many revivals were started.
-   */
   warmRange(from, to, limit = Math.max(1, Math.floor(this.#growthCeiling / 4))) {
     if (this.#closed || !Number.isInteger(from) || !Number.isInteger(to)) {
       return 0;
     }
     let started = 0;
     for (let index = from; index <= to && started < limit; index += 1) {
-      if (this.#slotOf.has(index) || !this.#disk.has(index)) {
+      if (this.#buffers.has(index) || !this.#disk.has(index)) {
         continue;
       }
       started += 1;
@@ -811,16 +510,13 @@ export class SharedPieceStore {
       throw new Error("Piece store is closed.");
     }
 
-    const slot = this.#slotOf.get(index);
-    if (slot !== undefined) {
+    const buffer = this.#buffers.get(index);
+    if (buffer !== undefined) {
       this.#lru.touch(index);
       this.#counters.fromMemory += 1;
       return this.locate(index);
     }
 
-    // Caught mid-spill: the slot is already gone, the disk copy is not there
-    // yet. Waiting is the only correct answer — reporting it missing would make
-    // the caller re-download a piece we are in the middle of keeping.
     const spill = this.#evicting.get(index);
     if (spill) {
       await spill.catch(() => undefined);
@@ -831,40 +527,27 @@ export class SharedPieceStore {
     }
 
     const pieceLength = this.#lengthOf(index);
-    const revived = await this.#claimSlot();
-    const target = this.#pool.subarray(
-      revived * this.#chunkLength,
-      revived * this.#chunkLength + pieceLength
-    );
+    await this.#claimSlot();
+    const targetSab = new SharedArrayBuffer(pieceLength);
+    const target = Buffer.from(targetSab);
     await this.#disk.read(index, target);
-    this.#registerSlot(index, revived);
+    this.#registerPiece(index, targetSab);
     this.#counters.fromDisk += 1;
     this.#counters.revivals += 1;
     return this.locate(index);
   }
 
-  /**
-   * Close the store, keeping the spill file.
-   *
-   * @param {(error?: Error | null) => void} [callback]
-   * @returns {void}
-   */
   close(callback = () => undefined) {
     this.#closed = true;
     liveStores.delete(this);
+    this.#buffers.clear();
     this.#disk.close().then(() => callback(null), (error) => callback(error));
   }
 
-  /**
-   * Close the store and delete everything it wrote.
-   *
-   * @param {(error?: Error | null) => void} [callback]
-   * @returns {void}
-   */
   destroy(callback = () => undefined) {
     this.#closed = true;
     liveStores.delete(this);
-    this.#slotOf.clear();
+    this.#buffers.clear();
     this.#disk.destroy().then(() => callback(null), (error) => callback(error));
   }
 }

package/services/torrent-worker/client.js

@@ -59,11 +59,7 @@ export class TorrentWorkerClient {
    *
    * @type {Map<number, number>}
    */
-  #lastPieceByRead = new Map();
-  /** Each torrent's piece pool, so a fragment can be read where it lies. */
-  #poolBySource = new Map();
-  /** Which pool an in-flight read belongs to, keyed by request id. */
-  #poolByRead = new Map();
+   #lastPieceByRead = new Map();
   /** Reads consuming fragments in place, keyed by request id. */
   #fragmentReaders = new Map();
 
@@ -96,7 +92,6 @@ export class TorrentWorkerClient {
       if (message?.type === Event.ERROR && this.#fragmentReaders.has(message.id)) {
         const reader = this.#fragmentReaders.get(message.id);
         this.#fragmentReaders.delete(message.id);
-        this.#poolByRead.delete(message.id);
         reader.fail(new Error(message.error ?? "Torrent worker read failed."));
         return;
       }
@@ -105,28 +100,17 @@ export class TorrentWorkerClient {
       }
       switch (message?.type) {
         case Event.FRAGMENT: {
-          const pool = this.#poolByRead.get(message.id);
-          if (!pool) {
-            // No pool means no way to read the fragment; confirm it so the
+          const buffer = message.buffer;
+          if (!buffer) {
+            // No buffer means no way to read the fragment; confirm it so the
             // worker is not left waiting, and let the read end short.
             this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
             break;
           }
-          // The pool is a growable SharedArrayBuffer shared with the worker
-          // thread, and an offset is only meaningful against the buffer of the
-          // store that produced it. When the two disagree — a second store
-          // opened for the same torrent, a slot handed out before the buffer
-          // grew — this threw `RangeError: Invalid typed array length`, which
-          // the process-wide handler swallowed. Reads then stopped answering
-          // for good: field 2026-08-09, one segment was held for a minute
-          // eight times running while the audio decoder was fed cut-up frames
-          // and reported them as a broken AC-3 stream. A read that cannot be
-          // satisfied must end short and say so, not take the whole source
-          // down silently.
-          if (message.offset + message.length > pool.byteLength) {
+          if (message.offset + message.length > buffer.byteLength) {
             logger.warn(
               `torrent-worker: fragment ${message.offset}+${message.length} lies outside ` +
-              `its pool of ${pool.byteLength}B (read ${message.id}) — ending the read short`
+              `its buffer of ${buffer.byteLength}B (read ${message.id}) — ending the read short`
             );
             this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
             break;
@@ -150,7 +134,7 @@ export class TorrentWorkerClient {
             );
           }
           this.#lastPieceByRead.set(message.id, message.pieceIndex);
-          const view = new Uint8Array(pool, message.offset, message.length);
+          const view = new Uint8Array(buffer, message.offset, message.length);
 
           const reader = this.#fragmentReaders.get(message.id);
           if (reader) {
@@ -183,7 +167,6 @@ export class TorrentWorkerClient {
           this.#reads.delete(message.id);
           this.#fragmentReaders.get(message.id)?.close();
           this.#fragmentReaders.delete(message.id);
-          this.#poolByRead.delete(message.id);
           break;
         case Event.LOG:
           logger.info(`torrent-worker: ${message.message}`);
@@ -373,17 +356,10 @@ export class TorrentWorkerClient {
       onCancel: () => {
         void this.#caller.call(Command.CANCEL_READ, { readId }).catch(() => undefined);
         this.#reads.delete(readId);
-        this.#poolByRead.delete(readId);
         this.#lastPieceByRead.delete(readId);
       }
     });
     this.#reads.set(readId, receive);
-    // Which pool this read's fragments will point into. Recorded before the
-    // command is sent, because the first fragment can arrive immediately.
-    const pool = this.#poolBySource.get(sourceKey);
-    if (pool) {
-      this.#poolByRead.set(readId, pool);
-    }
 
     // The worker replies to READ_RANGE only once the body is fully sent; a
     // failure before that must surface on the stream, not vanish.
@@ -414,11 +390,6 @@ export class TorrentWorkerClient {
    * @returns {{ [Symbol.asyncIterator]: () => AsyncGenerator<{ bytes: Uint8Array, release: () => void }>, cancel: () => void } | null}
    */
   createFragmentReader({ sourceKey, fileIndex, start = null, end = null, windowBytes }) {
-    const pool = this.#poolBySource.get(sourceKey);
-    if (!pool) {
-      return null;
-    }
-
     const readId = this.#caller.nextId();
     /** @type {{ bytes: Uint8Array, release: () => void }[]} */
     const queue = [];
@@ -447,11 +418,9 @@ export class TorrentWorkerClient {
         notify();
       }
     });
-    this.#poolByRead.set(readId, pool);
 
     const cancel = () => {
       if (this.#fragmentReaders.delete(readId)) {
-        this.#poolByRead.delete(readId);
         void this.#caller.call(Command.CANCEL_READ, { readId }).catch(() => undefined);
       }
       finished = true;
@@ -513,11 +482,6 @@ export class TorrentWorkerClient {
    */
   async getTorrent({ sourceKey, sourceType, source }) {
     const info = await this.addSource({ sourceKey, sourceType, source });
-    // The torrent's piece pool. Both threads now hold the same memory, so a
-    // read can be answered with an offset instead of with bytes.
-    if (info.sharedBuffer) {
-      this.#poolBySource.set(sourceKey, info.sharedBuffer);
-    }
     const client = this;
     return {
       infoHash: info.infoHash,

package/services/torrent-worker/piece-reader.js

@@ -1082,6 +1082,7 @@ export async function* readFragments({
       deliveredBytes += toWithinPiece - fromWithinPiece + 1;
       yield {
         pieceIndex,
+        buffer: located.buffer,
         offset: located.offset + fromWithinPiece,
         length: toWithinPiece - fromWithinPiece + 1,
         release() {

package/services/torrent-worker/worker.js

@@ -37,7 +37,7 @@ import { startMemoryReport } 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, findSharedStore, reviseStoreBudgets } = await import("../piece-store/shared-piece-store.js");
+const { collectStoreStats, 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
@@ -176,6 +176,7 @@ function sendFragment(id, fragment) {
       type: Event.FRAGMENT,
       id,
       pieceIndex: fragment.pieceIndex,
+      buffer: fragment.buffer,
       offset: fragment.offset,
       length: fragment.length
     });
@@ -304,10 +305,6 @@ async function runCommand(command, params, id) {
       return {
         infoHash: torrent.infoHash,
         name: torrent.name,
-        // The piece pool itself. A `SharedArrayBuffer` crosses as a reference to
-        // the same memory rather than a copy, which is what lets the main thread
-        // read a piece where it already lies instead of being sent its bytes.
-        sharedBuffer: findSharedStore(torrent)?.sharedBuffer ?? null,
         // Files cross as plain data; the objects stay here.
         files: (torrent.files ?? []).map((file, index) => ({
           index,
@@ -502,21 +499,26 @@ const lastReported = new Map();
 
 setInterval(() => {
   // What the machine can spare NOW, not what it could spare when each store was
-  // created. Lowering a ceiling frees nothing already committed — the pool
-  // cannot shrink — but it stops growth into memory the host no longer has, and
-  // those pieces go to disk instead (roadmap item 2).
+  // created. With per-piece buffers a lowered ceiling is honoured immediately:
+  // excess pieces are evicted to disk and their memory is reclaimable.
   for (const revised of reviseStoreBudgets()) {
-    if (revised.committedBytes > revised.ceilingBytes) {
+    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`
+      );
+    } else if (revised.committedBytes > revised.ceilingBytes) {
       log(
         `piece-store "${revised.name.slice(0, 40)}": allowance is now ` +
         `${Math.round(revised.ceilingBytes / 1048576)}MB and ` +
-        `${Math.round(revised.committedBytes / 1048576)}MB is already committed — ` +
-        `it will not grow further, and cannot give back what it holds`
+        `${Math.round(revised.committedBytes / 1048576)}MB is committed — ` +
+        `all resident pieces are pinned, cannot shrink yet`
       );
     }
   }
   for (const stats of collectStoreStats()) {
-    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}`;
+    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}/${stats.evictedOnRevise}`;
     if (lastReported.get(stats.name) === signature) {
       continue;
     }
@@ -525,21 +527,15 @@ setInterval(() => {
     const reads = stats.fromMemory + stats.fromDisk;
     const fromMemoryShare = reads > 0 ? ((stats.fromMemory / reads) * 100).toFixed(1) : "—";
     log(
-      // In BYTES as well as in pieces. The count alone says nothing without the
-      // piece size, and the piece size differs per torrent: on the film the
-      // proxy was killed under, 2026-08-28, "63" meant 504 MB.
       `piece-store "${stats.name.slice(0, 40)}": resident=${stats.resident}/${stats.capacity} ` +
       `(${Math.round((stats.residentBytes || 0) / 1048576)}MB of ` +
       `${Math.round((stats.budgetBytes || 0) / 1048576)}MB allowed) ` +
-      // What the machine has actually parted with, which is not what is held:
-      // the pool only grows, so a spilled piece frees its slot and no memory.
-      // Reporting the first without the second is what hid 650 MB on
-      // 2026-08-28 (roadmap item 2).
       `committed=${Math.round((stats.committedBytes || 0) / 1048576)}MB ` +
       `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}` +
-      (stats.blockedByPins > 0 ? ` blocked-by-pins=${stats.blockedByPins}` : "")
+      (stats.blockedByPins > 0 ? ` blocked-by-pins=${stats.blockedByPins}` : "") +
+      (stats.evictedOnRevise > 0 ? ` evictedOnRevise=${stats.evictedOnRevise}` : "")
     );
   }
 }, STORE_REPORT_INTERVAL_MS).unref();

package/test/piece-reader.test.js

@@ -63,7 +63,6 @@ async function fakeTorrent({ fileOffset, fileLength, totalLength }) {
 async function readRange(torrent, start, end) {
   const collected = [];
   const positions = [];
-  const pool = Buffer.from(torrent.store.sharedBuffer);
   for await (const fragment of readFragments({
     torrent,
     fileIndex: 0,
@@ -71,7 +70,8 @@ async function readRange(torrent, start, end) {
     end,
     cancellation: { isCancelled: () => false }
   })) {
-    collected.push(Buffer.from(pool.subarray(fragment.offset, fragment.offset + fragment.length)));
+    const source = fragment.buffer ? Buffer.from(fragment.buffer, fragment.offset, fragment.length) : Buffer.alloc(0);
+    collected.push(Buffer.from(source));
     positions.push({ piece: fragment.pieceIndex, length: fragment.length });
     fragment.release();
   }

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

@@ -133,7 +133,7 @@ test("a pinned piece is not evicted to make room", async () => {
 
     const located = store.locate(0);
     assert.ok(located, "the pinned piece was evicted while held");
-    const view = Buffer.from(store.sharedBuffer, located.offset, located.length);
+    const view = Buffer.from(located.buffer, located.offset, located.length);
     assert.deepEqual(view, piece(0), "the pinned piece was overwritten in place");
 
     store.unpin(0);
@@ -175,7 +175,7 @@ test("a piece revived from disk is readable by offset again", async () => {
     await get(store, 0); // brings it back
     const located = store.locate(0);
     assert.ok(located, "piece 0 was not brought back into memory");
-    const view = Buffer.from(store.sharedBuffer, located.offset, located.length);
+    const view = Buffer.from(located.buffer, located.offset, located.length);
     assert.deepEqual(view, piece(0));
   } finally {
     await new Promise((resolve) => store.destroy(resolve));
@@ -215,25 +215,19 @@ test("takes memory as it needs it, not the whole budget up front", async () => {
   const { store, directory } = await makeStore({ pieces: 16, totalPieces: 64 });
   try {
     assert.equal(store.capacity, 16);
-    const initial = store.sharedBuffer.byteLength;
-    assert.ok(initial <= CHUNK * 2, `claimed ${initial} bytes before holding anything`);
+    const initial = store.stats().committedBytes;
+    assert.ok(initial === 0, `claimed ${initial} bytes before holding anything`);
 
     for (let index = 0; index < 5; index += 1) {
       await put(store, index, piece(index));
     }
 
     assert.equal(store.residentCount, 5);
-    assert.ok(
-      store.sharedBuffer.byteLength >= CHUNK * 5,
-      "the pool did not grow to hold what was put in it"
-    );
-    assert.ok(
-      store.sharedBuffer.byteLength <= CHUNK * 6,
-      "the pool grew past what was actually needed"
-    );
+    assert.equal(store.stats().committedBytes, CHUNK * 5, "committed should equal resident");
+    assert.equal(store.stats().residentBytes, CHUNK * 5);
 
-    // Growing must not move bytes already written.
-    assert.deepEqual(await get(store, 0), piece(0), "an early piece was disturbed by growth");
+    // Per-piece buffers must not disturb early pieces.
+    assert.deepEqual(await get(store, 0), piece(0), "an early piece was disturbed");
   } finally {
     await new Promise((resolve) => store.destroy(resolve));
     await fs.rm(directory, { recursive: true, force: true });