@torrent-tv/proxy 2.64.5 → 2.64.7

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 2.64.7
+
+- **Fix**: A file opened at a position starts its SOUND at that position. The audio rendition's start is worked out from the picture's read head less the buffer the viewer reports holding — sound, because a read head is the furthest request of any viewer and the picture sits behind it by however deep that buffer is. At a cold open there is no report yet, and the fallback subtracted the WHOLE 120 s look-ahead from a buffer that does not exist: field 2026-08-31, a page opened at 588 s started its sound at 460 s, 131 seconds of film nobody would hear, and the segment the viewer needed took 38.8 s to appear against the picture's 8.4 s — the audio encoder healthy at 2.3-3.1x throughout, simply given a running start it did not need. The reading now says WHICH of its three sources answered (`viewerPositionSource`): a seek and a served segment are request edges and keep the subtraction, while the opening position is not an edge — nothing has been asked for since the session was made, and a browser that has just opened holds nothing by construction (`research/cold-open-audio-start-2026-08-31.md`).
+- **Fix**: The first encode run is positioned from the position the viewer ASKED for, not from the figure rounded to ten seconds. That rounding exists to answer one question — whether two viewers share a session — and `Math.round` can move a position FORWARD: 588 s became 590 s, which falls in segment #85 while the viewer at 588 s is inside #84. The player asked for a segment behind the run, the run was restarted onto it, and the 4.5 s it had already produced were thrown away.
+
+## 2.64.6
+
+- **New**: The torrent worker reads its own memory once a SECOND, and writes a line only when something moved. A minute cannot see what kills it: three times — 2026-08-30 14:00 and 23:19, 2026-08-31 13:27 — the worker's own line read `heap=28-36MB`, and by the sample after next the thread had been terminated for reaching its heap ceiling, with the whole rise fitting inside a single sixty-second gap. The reading and the line are now separate cadences: taken every second, written when the heap has moved by 25 MB or when a quiet minute is up, so a healthy session costs the same one line a minute it costs today and a runaway is a curve rather than a step.
+- **New**: A heap snapshot of the WORKER's own isolate, on every new high-water above 400 MB, into the state directory, three kept. Every snapshot ever written by this proxy has been of the MAIN isolate — `v8.writeHeapSnapshot` snapshots the thread that calls it, and the main thread's heap is 26 MB while the one that dies climbs to 2240 MB. So the isolate that has died three times has never once been looked at, and the question "what is holding this memory" has had no way to be answered. Deliberately NOT taken as the ceiling is approached: a snapshot is about the size of the heap it is of, so asking for one at 1.9 GB on a machine with 600 MB left is a way to cause the kill being studied — and at one reading a second no 400 MB step is ever missed. `stateDir` now travels to the worker for this, because a worker cannot change the process's working directory and had no way to choose where a file lands.
+- **New**: The memory line says the heap ceiling beside the heap — `heap=1800MB/1904MB of 2240MB allowed`. That ceiling is what the runtime terminates a thread for reaching, it is inherited from the main isolate by a worker created without `resourceLimits`, and without it the log said "30MB" with no way to tell how far that was from the end.
+
+- **Fix**: Room for a piece in the store is an owned reservation, released in a `finally`, instead of a number one function increments and another decrements. Every consequence of the old pairing was a defect, and all of them are gone with it: a failure between `#claimSlot` and `#registerPiece` — a disk read that throws — lost a slot for the life of the process, because there was no `try/finally` anywhere on that path; `put`'s error path tried to correct that by guessing, and its own comments said so ("Heuristic:", "We conservatively decrement"), so it could take back a reservation belonging to a different claim in flight and let the store admit past its allowance until the next minute's revision evicted the excess. `stats()` now reports `outstanding`, and the periodic `piece-store` line prints it when it is not zero: a reservation that never comes back is invisible until the store cannot admit anything, and by then the reason is long gone.
+- **Fix**: A claim waits on PROGRESS, not on activity. The five-second "every resident piece is pinned" error was skipped entirely while a spill was in flight or any reservation was held, so ONE lost reservation from the defect above made that error permanently unreachable and a read retried every 50 ms for the rest of the process's life — never completing, never failing, and never saying anything. The clock now restarts when something actually moves (a piece admitted, a spill finished, a pin released) and the error is raised when nothing has moved for five seconds, whatever is nominally in flight.
+- **Fix**: The wait between attempts allocates once instead of once per pending spill. It attached a fresh pair of handlers to EVERY spill in flight on EVERY attempt and left an uncancelled timer behind each time, so a claim that could not be satisfied allocated in proportion to attempts times spills. One idempotent handler now, its timer cleared when it is woken, and a settling spill wakes the store itself — which is where that belonged, and which `#claimSlotOnce`'s own spills were not doing at all.
+- **Fix**: Closing or destroying the store wakes whoever is waiting for room, and a claim checks for a closed store on every attempt. Callers inside `#claimSlot` were simply left asleep for ever.
+- **Fix**: A piece handed back to memory while its own spill is still being written no longer reappears on disk. `DiskTier.write` records the index when it COMPLETES, and `put` called `forget` before that, so the completing write put the stale copy back and a later read returned bytes from before the rewrite. `put` now waits for that piece's spill to finish before forgetting it.
+- **Fix**: A spill that fails while the allowance is being lowered is counted (`spill-failures` in the store's line) instead of thrown into nothing. Nobody awaits those spills, so the rethrow was an unhandled rejection, and an unhandled rejection in the torrent worker ends the thread — a second way to lose the torrent client on top of the one being investigated.
+- **Fix**: Two concurrent revivals of the same piece no longer each allocate and register a buffer for it, leaving whoever holds the first reading memory the store has stopped tracking. The second finds the piece already back and uses it.
+- **Fix**: `PieceLru` follows the store's live allowance. It was built with the capacity the store was created with and never revised, so `isFull()` answered against a number that had stopped being the limit — dormant only because nothing calls it today.
+- **Chore**: The store accepts an injected disk tier so a test can hold a write open or make one fail on purpose. Four of the defects above live in what happens when the disk does not answer at once, and none of them was reachable from outside before (`test/piece-store-reservations.test.js`).
+
+All eight were found by reading the file after the torrent worker was killed by its own JS heap limit on 2026-08-31 (`research/worker-heap-oom-2026-08-31.md`, §5). None of them is proven to be that growth; they are what the reading found, and each is a defect in its own right.
+
 ## 2.64.5
 
 - **Fix**: A rung measured at 0.007x is no longer kept just because it is on screen. The `playingHeight` exemption is now checked after the `measured < 1` withdrawal, so a 4K HEVC transcode at 0.007x on a CM4 (field 2026-08-31, 0.1x at 23:45 and 0.007x at 06:57, 0.04s buffered) is withdrawn and the offer can become empty instead of stalling the viewer with no way to downgrade. `ownHeight` is kept only for a copied source (`!transcodeVideo`), not for a re-encode already running at 0.18x.

package/package.json

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

package/server.js

@@ -116,7 +116,7 @@ export async function startProxyServer({
   // idled. Serving a segment shared that thread, so reading an already-finished
   // 10 MB file took 12-23 s against 125 ms to hand it to the channel. The
   // adapter keeps TorrentPool's interface, so nothing downstream changed.
-  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, onSubtitleCues });
+  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, stateDir, onSubtitleCues });
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });

package/services/hls-session-manager.js

@@ -1257,6 +1257,34 @@ function headsOf(session) {
   return session.consumerHeads;
 }
 
+/**
+ * WHICH of the three readings answered, which is a different question from what
+ * the answer was.
+ *
+ * It matters for one thing: `openedAt` is not a request edge. The other two are
+ * — a seek and a requested segment are both places a viewer has moved to while
+ * holding a buffer, so the picture is behind them by however deep that buffer
+ * is. `openedAt` is where a session was created and nothing has been asked for
+ * since, so the picture is exactly there and there is nothing to subtract.
+ * Reading the number without knowing which of the three it was is what started
+ * a cold open's audio two minutes early on 2026-08-31.
+ *
+ * @param {{ seeked?: number, lastRequestedStart?: number | null, openedAt?: number }} readings
+ * @returns {"seeked" | "requested" | "opened" | "none"}
+ */
+export function viewerPositionSource({ seeked, lastRequestedStart, openedAt }) {
+  if (Number.isFinite(seeked) && seeked > 0) {
+    return "seeked";
+  }
+  if (Number.isFinite(lastRequestedStart) && lastRequestedStart > 0) {
+    return "requested";
+  }
+  if (Number.isFinite(openedAt) && openedAt > 0) {
+    return "opened";
+  }
+  return "none";
+}
+
 export function resolveViewerPosition({ seeked, lastRequestedStart, openedAt }) {
   if (Number.isFinite(seeked) && seeked > 0) {
     return seeked;
@@ -2408,8 +2436,19 @@ export class HlsSessionManager {
     // asked for #152, and 45 s later the browser gave up with "no data arrived
     // from the proxy" while the transcode ran happily at 9.9x through the
     // opening credits.
-    const firstIndex = normalizedStartPosition > 0
-      ? this.#segmentIndexForTime(session, normalizedStartPosition)
+    // From what the viewer ASKED for, not from the rounded figure. The rounding
+    // exists to answer one question — is this the same session as somebody
+    // else's — and it is the wrong number for this one, because `Math.round`
+    // can move the position FORWARD: 588s became 590s, which falls in segment
+    // #85 while the viewer at 588s is inside #84. The player then asked for a
+    // segment behind the run, the run was restarted onto it, and the 4.5s it
+    // had produced were thrown away (field 2026-08-31,
+    // `research/cold-open-audio-start-2026-08-31.md`).
+    const requestedStart = Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
+      ? startPositionSeconds
+      : 0;
+    const firstIndex = requestedStart > 0
+      ? this.#segmentIndexForTime(session, requestedStart)
       : 0;
     await this.#startEncodeRun(session, firstIndex);
 
@@ -7824,10 +7863,40 @@ export class HlsSessionManager {
       // would start the run where no request can ever reach it.
       return Math.max(0, Math.min(earliestStated, readHead) - this.segmentDurationSec);
     }
+    if (this.#viewerPositionSourceOf(watching) === "opened") {
+      // The session has not started. Nobody has seeked, nobody has asked for a
+      // segment, and nobody has reported anything — so the read head is not a
+      // request edge at all, it is where the viewer opened, and a browser that
+      // has just opened holds no buffer by construction. Subtracting one here
+      // is not erring "early, the cheap direction": it is the whole of the
+      // start-up cost. Field 2026-08-31: a page opened at 588s started its
+      // sound at 460s, 131 seconds of film nobody would hear, and the segment
+      // the viewer needed took 38.8s to appear against the picture's 8.4s
+      // (`research/cold-open-audio-start-2026-08-31.md`).
+      return Math.max(0, readHead - this.segmentDurationSec);
+    }
     const buffered = deepestBuffer === null ? LOOKAHEAD_PAUSE_SECONDS : deepestBuffer;
     return Math.max(0, readHead - buffered - this.segmentDurationSec);
   }
 
+  /**
+   * Which reading gave this session's viewer position — see
+   * {@link viewerPositionSource}.
+   *
+   * @param {HlsSession} session
+   * @returns {"seeked" | "requested" | "opened" | "none"}
+   */
+  #viewerPositionSourceOf(session) {
+    const lastRequestedStart = Number.isInteger(session.lastRequestedSegment) && session.lastRequestedSegment > 0
+      ? this.#segmentStartTime(session, session.lastRequestedSegment)
+      : null;
+    return viewerPositionSource({
+      seeked: session.viewerPositionSeconds,
+      lastRequestedStart,
+      openedAt: session.progress?.startPositionSeconds
+    });
+  }
+
   #viewerPositionOf(session) {
     const lastRequestedStart = Number.isInteger(session.lastRequestedSegment) && session.lastRequestedSegment > 0
       ? this.#segmentStartTime(session, session.lastRequestedSegment)

package/services/memory-report.js

@@ -19,7 +19,7 @@
  * runtime already maintains.
  */
 
-import { readFile, statfs } from "node:fs/promises";
+import { readdir, readFile, rm, statfs } from "node:fs/promises";
 import os from "node:os";
 import v8 from "node:v8";
 import path from "node:path";
@@ -27,6 +27,18 @@ import path from "node:path";
 /** How often the reading is taken and written. */
 export const MEMORY_REPORT_INTERVAL_MS = 60_000;
 
+/**
+ * How often the torrent worker takes its own reading.
+ *
+ * A minute cannot see what killed it. Three times — 2026-08-30 14:00 and 23:19,
+ * 2026-08-31 13:27 — the worker's heap read 28-36 MB in one sample and the
+ * thread was dead by the sample after next, with the whole rise from 30 MB to
+ * the 2240 MB heap limit fitting inside a single gap. A second is short enough
+ * that the rise is a curve rather than a step, and the line is only WRITTEN when
+ * something moved, so a quiet session costs what it costs today.
+ */
+export const WORKER_MEMORY_SAMPLE_MS = 1_000;
+
 /**
  * What the process is holding, from the runtime's own counters.
  *
@@ -36,16 +48,30 @@ export const MEMORY_REPORT_INTERVAL_MS = 60_000;
  * since torrent pieces sit in a `SharedArrayBuffer` and segment bodies pass
  * through buffers.
  *
- * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }}
+ * `heapLimit` is this isolate's own ceiling, and it belongs beside the heap
+ * figures because it is what the runtime kills the thread for reaching — a
+ * worker created without `resourceLimits` inherits the main isolate's, 2240 MB
+ * on the addon host. Without it the log said 30 MB and gave no idea how far
+ * that was from the end.
+ *
+ * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number, heapLimit: number }}
  */
 export function readProcessMemory() {
   const usage = process.memoryUsage();
+  let heapLimit = 0;
+  try {
+    heapLimit = v8.getHeapStatistics().heap_size_limit ?? 0;
+  } catch {
+    // silent-ok: a missing ceiling leaves the term out, it does not cost the
+    // reading beside it.
+  }
   return {
     rss: usage.rss,
     heapUsed: usage.heapUsed,
     heapTotal: usage.heapTotal,
     external: usage.external,
-    arrayBuffers: usage.arrayBuffers ?? 0
+    arrayBuffers: usage.arrayBuffers ?? 0,
+    heapLimit
   };
 }
 
@@ -198,7 +224,8 @@ export function describeMemory({
       `committed ${megabytes(storeCommitted)} of ${megabytes(storeBudget)} allowed, ` +
       `${megabytes(storeSpilled)} spilled to disk`;
   const isolate =
-    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
+    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)}` +
+    `${usage.heapLimit ? ` of ${megabytes(usage.heapLimit)} allowed` : ""} ` +
     `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}`;
   if (scope === "thread") {
     return `memory (${label || "thread"}): ${isolate}; ${storesPart}`;
@@ -213,6 +240,39 @@ export function describeMemory({
   );
 }
 
+/**
+ * Whether this reading is worth writing down, and why.
+ *
+ * A series taken every second and printed every second is unreadable, and one
+ * printed every minute cannot see a rise that takes forty seconds. So the
+ * cadence of the READING and the cadence of the LINE are separate: the figure
+ * is taken often, and written when it has moved or when the quiet interval has
+ * passed. Pure, so the rule can be pinned without a clock.
+ *
+ * @param {Object} state
+ * @param {number} state.watchedBytes - The figure this scope is watching.
+ * @param {number} state.lastWrittenBytes
+ * @param {number} state.sinceWrittenMs
+ * @param {number} state.changeBytes - Movement that earns a line of its own.
+ * @param {number} state.quietMs - How long silence may last regardless.
+ * @returns {boolean}
+ */
+export function readingIsWorthWriting({
+  watchedBytes,
+  lastWrittenBytes,
+  sinceWrittenMs,
+  changeBytes,
+  quietMs
+}) {
+  if (quietMs <= 0 || sinceWrittenMs >= quietMs) {
+    return true;
+  }
+  if (changeBytes <= 0) {
+    return false;
+  }
+  return Math.abs(watchedBytes - lastWrittenBytes) >= changeBytes;
+}
+
 /**
  * Report memory on a timer until stopped.
  *
@@ -225,7 +285,17 @@ export function describeMemory({
  * @param {string} [options.label] - Which thread the isolate figures are of.
  * @param {string} [options.diskPath] - Where pieces spill, for the free-space
  *   reading. Omitted, the disk term is left out rather than guessed.
- * @param {number} [options.intervalMs]
+ * @param {number} [options.intervalMs] - How often the figure is READ.
+ * @param {number} [options.quietMs] - How long the line may stay silent while
+ *   nothing moves. Zero writes every reading, which is what the process scope
+ *   has always done.
+ * @param {number} [options.changeBytes] - Movement that earns a line before the
+ *   quiet interval is up.
+ * @param {string} [options.snapshotDir] - Where heap snapshots are written.
+ *   Defaults to the temporary directory, as the process scope always did.
+ * @param {number} [options.snapshotFloorBytes]
+ * @param {number} [options.snapshotGrowthBytes]
+ * @param {number} [options.keepSnapshots] - Newest to keep; zero keeps all.
  * @returns {{ stop: () => void }}
  */
 export function startMemoryReport({
@@ -234,9 +304,62 @@ export function startMemoryReport({
   scope = "process",
   label = "",
   diskPath = "",
-  intervalMs = MEMORY_REPORT_INTERVAL_MS
+  intervalMs = MEMORY_REPORT_INTERVAL_MS,
+  quietMs = 0,
+  changeBytes = 0,
+  snapshotDir = "",
+  snapshotFloorBytes = 500 * 1024 * 1024,
+  snapshotGrowthBytes = 100 * 1024 * 1024,
+  keepSnapshots = 0
 }) {
-  let highWaterRss = 0;
+  let highWater = 0;
+  let lastWrittenBytes = 0;
+  let lastWrittenAt = 0;
+  // The process watches what the kernel kills it for; a thread watches what the
+  // runtime kills IT for, which is its own heap and not the process's resident
+  // memory — the main isolate sat at 26 MB while the worker's heap climbed to
+  // its 2240 MB ceiling.
+  const watchedOf = (memory) => (scope === "thread" ? memory.heapTotal : memory.rss);
+  const slug = (label || scope).replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+  const directory = snapshotDir || os.tmpdir();
+
+  /**
+   * @param {number} watchedBytes
+   * @param {string} why
+   * @returns {Promise<void>}
+   */
+  const takeSnapshot = async (watchedBytes, why) => {
+    let snapPath = "";
+    try {
+      snapPath = path.join(directory, `heap-${slug}-${Date.now()}-${watchedBytes}.heapsnapshot`);
+      // Synchronous and proportional to the heap, so it stops this thread for
+      // as long as it takes to write. That is the price of the only reading
+      // that names what is holding the memory, and it is why it is bounded by
+      // a floor, by a growth step and by how many are kept.
+      v8.writeHeapSnapshot(snapPath);
+      log(`memory: wrote heap snapshot of the ${label || scope} to ${snapPath} (${megabytes(watchedBytes)}, ${why})`);
+    } catch {
+      // silent-ok: no snapshot is worse than a snapshot, and much better than
+      // ending the series that leads to the next one.
+      return;
+    }
+    if (keepSnapshots <= 0) {
+      return;
+    }
+    try {
+      const prefix = `heap-${slug}-`;
+      const mine = (await readdir(directory))
+        .filter((name) => name.startsWith(prefix) && name.endsWith(".heapsnapshot"))
+        .sort();
+      for (const name of mine.slice(0, Math.max(0, mine.length - keepSnapshots))) {
+        await rm(path.join(directory, name), { force: true });
+      }
+    } catch {
+      // silent-ok: a snapshot that could not be pruned is a disk-space problem
+      // for later, not a reason to lose the one just written.
+    }
+  };
+
   const tick = async () => {
     try {
       let stores = [];
@@ -247,35 +370,57 @@ export function startMemoryReport({
         // that matters, which is the process's own.
       }
       const processMemory = readProcessMemory();
+      const watched = watchedOf(processMemory);
+      const now = Date.now();
+      const write = readingIsWorthWriting({
+        watchedBytes: watched,
+        lastWrittenBytes,
+        sinceWrittenMs: lastWrittenAt === 0 ? Number.POSITIVE_INFINITY : now - lastWrittenAt,
+        changeBytes,
+        quietMs
+      });
+
+      let anonymousBytes = null;
       if (scope === "thread") {
-        log(describeMemory({ scope, label, process: processMemory, stores }));
-        return;
+        if (write) {
+          log(describeMemory({ scope, label, process: processMemory, stores }));
+        }
+      } else {
+        const { bytes, measured } = await availableMemory();
+        anonymousBytes = await readAnonymousMemory();
+        const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
+        if (write) {
+          log(describeMemory({
+            scope,
+            label,
+            process: processMemory,
+            availableBytes: bytes,
+            availableMeasured: measured,
+            anonymousBytes,
+            diskFreeBytes,
+            stores
+          }));
+        }
+      }
+      if (write) {
+        lastWrittenBytes = watched;
+        lastWrittenAt = now;
       }
-      const { bytes, measured } = await availableMemory();
-      const anonymousBytes = await readAnonymousMemory();
-      const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
-      log(describeMemory({
-        scope,
-        label,
-        process: processMemory,
-        availableBytes: bytes,
-        availableMeasured: measured,
-        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 {}
+
+      // A snapshot per high-water, so there is a file to open when the growth
+      // has to be named rather than described.
+      //
+      // Deliberately NOT one taken as the ceiling is approached: a snapshot is
+      // written by the isolate itself and is about the size of its heap, so
+      // asking for one at 1.9 GB on a machine with 600 MB left is a good way to
+      // cause the kill being studied. Whatever holds 1.6 GB is the same thing
+      // that holds 2.2 GB, and at one reading a second no step is ever missed.
+      if (watched > highWater + snapshotGrowthBytes && watched > snapshotFloorBytes) {
+        highWater = watched;
+        await takeSnapshot(watched, "a new high-water");
       }
-      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`);
+      if (scope !== "thread" && anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
+        log(`memory: high rss=${megabytes(processMemory.rss)} anon=${megabytes(anonymousBytes)} heap=${megabytes(processMemory.heapUsed)} — watch for OOM`);
       }
     } catch {
       // silent-ok: a reading that fails is not worth ending the series over.

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

@@ -64,6 +64,22 @@ export class PieceLru {
     return this.#capacity;
   }
 
+  /**
+   * Follow the store's live allowance, which moves with the machine's free
+   * memory. Without this the capacity stayed at whatever the store was created
+   * with, and {@link PieceLru#isFull} answered against a number that had not
+   * been the limit for some time.
+   *
+   * @param {number} capacity
+   * @returns {void}
+   */
+  setCapacity(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      return;
+    }
+    this.#capacity = capacity;
+  }
+
   /**
    * How many pieces are currently held by a reader.
    *