@torrent-tv/proxy 2.91.0 → 2.92.0

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

@@ -21,84 +21,14 @@
  */
 
 import { pieceStoreOf } from "../piece-store-of.js";
-import { bytesOf, Urgency, urgencyName } from "../demand/index.js";
+import { urgencyName } from "../demand/index.js";
 import { demandFor } from "../download/registry.js";
 import { logger } from "../../../utils/logger.js";
-import {
-  askFastestWiresFor,
-  canPlaceRequests,
-  describePieceTail,
-  duplicateTailFor
-} from "./fastest-wires.js";
 import { minimumBufferFrom, requiredSpeedFrom } from "../supply-margin.js";
 
 /** Only waits at least this long are reported; sequential reading stays silent. */
 const PIECE_WAIT_LOG_MS = 1_000;
 
-/** Distinguishes concurrent readers to the piece store. Never reused. */
-let readerSequence = 0;
-
-/**
- * How far ahead of the read head pieces are asked for.
- *
- * A read is open-ended — ffmpeg opens its input as `bytes <position>-<EOF>` and
- * keeps it for the whole film — so taking the requested range literally asks
- * for everything from the seek point to the end of the file at once. That is
- * what a seek used to do: the swarm was told the entire tail was wanted, went
- * at it from its first missing piece, and the one piece the decoder was blocked
- * on arrived only when the sequential scan reached it. Measured on a 4.7 GB
- * film: a seek to 89.1% took 93 s and pulled 2.47 GB.
- *
- * So the reader asks for a window and moves it as it goes. The size is a
- * compromise the caller cannot yet express: the right unit is seconds of
- * playback (duration and size are both known — to the transcode session, not to
- * this thread), and 32 MB is about 34 s of a 1080p film but only a few seconds
- * of a disc remux. Sizing it from the real byte rate is a follow-up; what
- * matters here is that it is bounded and moving rather than "to the end".
- */
-const READ_WINDOW_BYTES = 32 * 1024 * 1024;
-
-/**
- * The pieces a reader at `pieceIndex` wants next, clamped to its own range.
- *
- * @param {{ pieceIndex: number, lastPiece: number, windowPieces: number }} params
- * @returns {{ from: number, to: number }}
- */
-export function readWindowFor({ pieceIndex, lastPiece, windowPieces }) {
-  const span = Math.max(1, windowPieces);
-  return { from: pieceIndex, to: Math.min(lastPiece, pieceIndex + span - 1) };
-}
-
-/**
- * How wide the window should be after a piece that made the reader wait — or
- * did not.
- *
- * The swarm's surplus is what pays for this. Measured 2026-08-17 on the field
- * torrent: 5.1-5.9 MB/s delivered against a film consumed at about 1 MB/s, and
- * the reader still blocked 47 times in two minutes, median 1.5 s, worst 4.5 s.
- * A fivefold surplus never became distance ahead of the head, because the
- * window is a fixed number of seconds of playback and everything past it is
- * ordinary background fill at no priority.
- *
- * So the window follows the evidence: every wait that mattered widens it by a
- * piece, every piece that was already there narrows it back toward the size the
- * caller asked for. Nothing here is chosen — the wait is measured, the
- * threshold is the one that already defines "a wait worth recording", and the
- * ceiling is this reader's share of the store's memory, so widening can never
- * cost more than the store can hold.
- *
- * @param {{ current: number, base: number, ceiling: number, waitedMs: number, waitThresholdMs: number }} params
- * @returns {number}
- */
-export function nextWindowPieces({ current, base, ceiling, waitedMs, waitThresholdMs }) {
-  const floor = Math.max(1, Math.floor(base));
-  const top = Math.max(floor, Math.floor(ceiling));
-  const now = Math.min(top, Math.max(floor, Math.floor(current)));
-  if (waitedMs >= waitThresholdMs) {
-    return Math.min(top, now + 1);
-  }
-  return Math.max(floor, now - 1);
-}
 
 /**
  * Who is working on the piece a reader is blocked on, right now.
@@ -147,12 +77,14 @@ export function pieceSupply(torrent, pieceIndex) {
  * @param {{ isCancelled: () => boolean, onCancel?: (listener: () => void) => () => void }} cancellation
  * @returns {Promise<void>}
  */
-function whenPieceReady(torrent, index, cancellation) {
+function whenPieceReady(torrent, index, cancellation, wanted) {
   if (torrent.bitfield?.get(index)) {
     return Promise.resolve();
   }
 
   return new Promise((resolve, reject) => {
+    let stopListening = () => {};
+    let finished = false;
     /** @param {number} verifiedIndex */
     const onVerified = (verifiedIndex) => {
       if (verifiedIndex === index) {
@@ -160,6 +92,14 @@ function whenPieceReady(torrent, index, cancellation) {
         resolve();
       }
     };
+    const onMapChanged = () => {
+      if (wanted()) return;
+      cleanup();
+      const error = new Error(`Piece ${index} is outside the source priority map.`);
+      error.code = "SOURCE_RANGE_NOT_WANTED";
+      error.canRetry = false;
+      reject(error);
+    };
     const onDestroyed = () => {
       cleanup();
       reject(new Error(`Torrent went away while waiting for piece ${index}.`));
@@ -172,25 +112,31 @@ function whenPieceReady(torrent, index, cancellation) {
       reject(new Error(`Read cancelled while waiting for piece ${index}.`));
       return;
     }
-    const stopListening = cancellation.onCancel?.(() => {
-      cleanup();
-      reject(new Error(`Read cancelled while waiting for piece ${index}.`));
-    }) ?? (() => {});
-
     function cleanup() {
+      finished = true;
       stopListening();
       torrent.removeListener("verified", onVerified);
       torrent.removeListener("close", onDestroyed);
+      torrent.removeListener("priority-map-changed", onMapChanged);
     }
 
     torrent.on("verified", onVerified);
     torrent.once("close", onDestroyed);
+    torrent.on("priority-map-changed", onMapChanged);
+    stopListening = cancellation.onCancel?.(() => {
+      cleanup();
+      reject(new Error(`Read cancelled while waiting for piece ${index}.`));
+    }) ?? (() => {});
+    if (finished) {
+      stopListening();
+      return;
+    }
 
     // The piece may have arrived between the check above and this listener.
     if (torrent.bitfield?.get(index)) {
       cleanup();
       resolve();
-    }
+    } else onMapChanged();
   });
 }
 
@@ -217,9 +163,6 @@ function whenPieceReady(torrent, index, cancellation) {
  * @param {number} params.start - Inclusive, relative to the file.
  * @param {number} params.end - Inclusive, relative to the file.
  * @param {{ isCancelled: () => boolean }} params.cancellation
- * @param {number} [params.windowBytes] - How far ahead of the read head to ask
- *   the swarm for. Defaults to {@link READ_WINDOW_BYTES}; a caller that knows
- *   the media's byte rate should size it in seconds of playback instead.
  * @returns {AsyncGenerator<PieceFragment>}
  */
 /**
@@ -290,20 +233,6 @@ export function supplyFiguresFor(infoHash, fileName, segmentSeconds) {
   };
 }
 
-/**
- * Waits split by whether the blocked piece was steered onto another peer.
- *
- * The steering is visible per wait already — how many peers held the piece, how
- * many were asked, what the tail looked like. What was NOT visible is what it
- * bought, and that cannot be read off one line: it is the difference between
- * the waits where a second peer was asked and the waits where none could be.
- * Kept per file, reported with the same summary, so a session says by number
- * whether the swap shortens the tail instead of leaving it to impression.
- *
- * @type {Map<string, { swapped: number[], alone: number[] }>}
- */
-const waitsBySteering = new Map();
-
 /**
  * Record one wait against the priority level of the requested piece. The level
  * identifies which part of the priority map needs more lead time.
@@ -357,41 +286,6 @@ function describeWaitLevels(key) {
  */
 const waitsByLevel = new Map();
 
-function noteSteeringOutcome(key, waitedMs, steered) {
-  let split = waitsBySteering.get(key);
-  if (!split) {
-    split = { swapped: [], alone: [] };
-    waitsBySteering.set(key, split);
-  }
-  const into = steered ? split.swapped : split.alone;
-  into.push(waitedMs);
-  while (into.length > SUPPLY_WAIT_HISTORY) {
-    into.shift();
-  }
-}
-
-/**
- * What the split says, or null while one side of it is still empty — a
- * comparison needs both.
- *
- * @param {string} key
- * @returns {string | null}
- */
-function describeSteering(key) {
-  const split = waitsBySteering.get(key);
-  if (!split || split.swapped.length === 0 || split.alone.length === 0) {
-    return null;
-  }
-  const middle = (values) => {
-    const sorted = [...values].sort((left, right) => left - right);
-    return sorted[Math.floor(sorted.length / 2)];
-  };
-  return (
-    `steered ${split.swapped.length} waits median ${middle(split.swapped)}ms, ` +
-    `unsteered ${split.alone.length} waits median ${middle(split.alone)}ms`
-  );
-}
-
 /**
  * How many readers are blocked on a torrent AT THIS MOMENT, by infohash.
  *
@@ -503,12 +397,7 @@ function noteSupplyWait(key, label, waitedMs) {
     `one every ${demand.medianIntervalSec.toFixed(2)}s of running, ${demand.samples} stall(s) ` +
     `from ${demand.waits} wait(s)) — ` +
     `and the smallest buffer that hides it is ${buffer ? buffer.seconds.toFixed(1) : "?"}s` +
-    // What steering the blocked piece onto another peer bought, as the
-    // difference between the waits where it placed something and the waits
-    // where it could not. Absent until both sides have a sample, because a
-    // comparison with one side empty is not a comparison.
-    (describeSteering(key) ? ` — ${describeSteering(key)}` : "") +
-    // The comparison this release exists to make. Read it first.
+    // Attribute source waits to the level declared by the shared map.
     (describeWaitLevels(key) ? ` — ${describeWaitLevels(key)}` : "")
   );
 }
@@ -520,559 +409,54 @@ function noteSupplyWait(key, label, waitedMs) {
  */
 const SEGMENT_SECONDS_FOR_BUFFER = 4;
 
-export async function* readFragments({
-  torrent,
-  fileIndex,
-  start,
-  end,
-  cancellation,
-  windowBytes = READ_WINDOW_BYTES
-}) {
+export async function* readFragments({ torrent, fileIndex, start, end, cancellation }) {
   const store = pieceStoreOf(torrent);
-  if (!store) {
-    throw new Error("This torrent is not backed by a shared piece store.");
-  }
-  // What this reader wants goes here and nowhere else. `SwarmSelection` is the
-  // only thing that turns any of it into a request to the swarm, so a reader
-  // can no longer contradict the background fill or the pool.
-  const { register, selection } = demandFor(torrent);
-
   const file = torrent.files?.[fileIndex];
-  if (!file) {
-    throw new Error(`File ${fileIndex} not found.`);
-  }
-
+  if (!store || !file) throw new Error("The source file or shared piece store is unavailable.");
   const pieceLength = torrent.pieceLength;
-  // Piece numbers are torrent-wide, so a file's own offsets have to be lifted
-  // into the torrent's address space first.
-  const absoluteStart = file.offset + start;
-  const absoluteEnd = file.offset + end;
-  const firstPiece = Math.floor(absoluteStart / pieceLength);
-  const lastPiece = Math.floor(absoluteEnd / pieceLength);
-
-  // This reader owns what it asks for, and gives it back when it is done. The
-  // window is a STREAM selection: those are removed by exact bounds and several
-  // identical ones coexist — WebTorrent's own source calls that "in a way a
-  // count" — so N readers on one torrent produce the union of their windows,
-  // and each one leaving takes away only its own. That is what makes several
-  // parallel readers (the codec probe's head and tail, subtitles, one input per
-  // viewer) cooperate instead of overwrite each other.
-  //
-  // The previous code selected the whole requested range, marked all of it
-  // critical, and never deselected anything — so ffmpeg's opening
-  // `bytes 0-<EOF>` left a permanent selection over the entire file, and no
-  // later prioritisation could outrank it.
-  const basePieces = Math.max(1, Math.ceil(Math.max(1, windowBytes) / pieceLength));
-  // What the window is RIGHT NOW. It starts at what the caller sized in seconds
-  // of playback and grows while the reader keeps being made to wait — see
-  // `nextWindowPieces`.
-  let windowPieces = basePieces;
-  /**
-   * The widest this reader may go: its share of what the store can hold in
-   * memory. Measured rather than chosen — the capacity is the store's own, and
-   * the number of readers is how many windows are declared on it right now.
-   *
-   * @returns {number}
-   */
-  const ceilingPieces = () => {
-    const capacity = Number(store?.capacity);
-    if (!Number.isFinite(capacity) || capacity <= 0) {
-      return basePieces;
-    }
-    const readers = Math.max(1, store.protectedRanges?.().length ?? 1);
-    return Math.max(basePieces, Math.floor(capacity / readers));
-  };
-  /** @type {{ from: number, to: number } | null} */
-  let window = null;
-  /** @type {{ from: number, to: number } | null} */
-  let blockedStated = false;
-  /**
-   * Drops the pin of the fragment currently in the consumer's hands, if it
-   * still holds one. See where it is assigned.
-   *
-   * @type {(() => void) | null}
-   */
-  let releaseHeldPin = null;
-
-  // Identity of this read, so the store can tell one reader's window from
-  // another's. Each read gets its own; `readerSequence` never repeats within a
-  // process.
-  const readerId = `read-${(readerSequence += 1)}`;
-
-  /**
-   * Set when the window JUMPS, cleared by the first wait after it.
-   *
-   * The wait that follows a jump is the cost of the jump: the pieces at the new
-   * position have not been asked for yet, and the encoder is restarting. It is
-   * not evidence about how well this swarm SUSTAINS a read, which is the only
-   * thing `requiredSpeed` is about — and letting it in is what collapsed the
-   * quality offer 131 ms after the seek measured on 2026-08-18, refusing every
-   * re-encoded rung on the strength of one jump.
-   *
-   * @type {boolean}
-   */
-  let waitBelongsToJump = false;
-
-  /** What the consumer has taken from this read, in bytes. */
-  let deliveredBytes = 0;
-  // How often this read had to stop, and for how long in total. Reported at the
-  // end whatever the outcome, so a read that never stopped is counted too.
-  let waitCount = 0;
-  let waitedTotalMs = 0;
-  const readStartedAt = Date.now();
-
-  /**
-   * Where the reader's claim starts: the first piece it does not already have. Everything between the read position and that piece
-   * is on disk or in memory, so claiming it asks the swarm for what we hold.
-   *
-   * @param {number} pieceIndex
-   * @returns {number}
-   */
-  const firstMissingFrom = (pieceIndex) => {
-    for (let index = pieceIndex; index <= lastPiece; index += 1) {
-      if (!torrent.bitfield?.get?.(index)) {
-        return index;
-      }
-    }
-    return pieceIndex;
-  };
-
-
-  /**
-   * State one band as a need, in bytes.
-   *
-   * The urgency is part of the claimant key, so this blocked-read claim can be
-   * withdrawn without changing the priority map's claims for the same file.
-   *
-   * @param {{ from: number, to: number, urgency: number }} band
-   * @returns {void}
-   */
-  const stateBand = (band) => {
-    const range = bytesOf({
-      fileOffset: Number(file.offset),
-      fileLength: Number(file.length),
-      from: band.from,
-      to: band.to,
-      pieceLength
-    });
-    if (!range) {
-      return;
-    }
-    register.state({
-      claimant: `${readerId}:${urgencyName(band.urgency)}`,
-      fileIndex,
-      byteStart: range.byteStart,
-      byteEnd: range.byteEnd,
-      urgency: band.urgency
-    });
-  };
-
-  /**
-   * Move the window the reader is working through.
-   *
-   * It states NOTHING to the swarm. What should be downloaded ahead of a viewer
-   * is the priority map's answer, stated once for the whole file by the side
-   * that knows where the viewers are; a read is consumption, not a forecast.
-   *
-   * A read used to declare a rolling window of its own — the piece it wanted
-   * and two bands beyond it — and with fifteen reads on one file that was
-   * fifteen windows on a piece store holding sixteen pieces. Half of all
-   * evictions then took a piece a reader had declared, two thirds of reads came
-   * back from disk, and the bytes handed out stopped being the file's: twenty-
-   * two source-parse errors, a segment the player refused, and an empty picture
-   * for six minutes (field 2026-09-05).
-   *
-   * What the window is still for: the pieces to mark critical when the reader
-   * is actually stopped, and the range to bring back from disk after a jump.
-   *
-   * @param {number} pieceIndex
-   * @returns {void}
-   */
-  /**
-   * Where the priority map puts one piece, in the map's own levels.
-   *
-   * A stated window is file-relative — `bytesOf` subtracts the file's offset
-   * within the torrent — so the piece is put in that frame before it is looked
-   * up, or every answer belongs to some other part of the torrent.
-   *
-   * @param {number} pieceIndex
-   * @returns {number | null}
-   */
-  const mapLevelOf = (pieceIndex) =>
-    register.urgencyAt(fileIndex, pieceIndex * pieceLength - Number(file.offset));
-
-  const moveWindowTo = (pieceIndex) => {
-    const anchor = firstMissingFrom(pieceIndex);
-    const next = readWindowFor({ pieceIndex: anchor, lastPiece, windowPieces });
-    if (window && window.from === next.from && window.to === next.to) {
-      return;
-    }
-    const isJump = !window || next.from > window.to || next.from < window.from;
-    window = next;
-    if (isJump) {
-      waitBelongsToJump = true;
-      // A jump — a seek, not the window sliding along — can land on pieces that
-      // are already downloaded but have been spilled to disk. Bring the whole
-      // window back at once instead of one disk round trip per piece as the
-      // reader reaches them.
-      const revived = store.warmRange?.(next.from, next.to) ?? 0;
-      if (revived > 0) {
-        logger.info(
-          `piece-reader: reviving ${revived} spilled piece(s) of ${next.from}-${next.to} ` +
-            `for a jump to ${(start / 1024 / 1024).toFixed(0)}MB of "${file.name}"`
-        );
-      }
-    }
-  };
-
-  // How many times THIS piece has been asked for again after the store
-  // withdrew it. Reset once a piece is in hand, so the allowance is per piece.
-  let withdrawnRetries = 0;
-
+  const absoluteStart = file.offset + start, absoluteEnd = file.offset + end;
+  const first = Math.floor(absoluteStart / pieceLength), last = Math.floor(absoluteEnd / pieceLength);
+  const { register } = demandFor(torrent);
+  let release = null;
   try {
-    for (let pieceIndex = firstPiece; pieceIndex <= lastPiece; pieceIndex += 1) {
-      if (cancellation.isCancelled()) {
-        return;
-      }
-
-      const pieceStart = pieceIndex * pieceLength;
-      const fromWithinPiece = Math.max(absoluteStart, pieceStart) - pieceStart;
-      const toWithinPiece = Math.min(absoluteEnd, pieceStart + pieceLength - 1) - pieceStart;
-
-      moveWindowTo(pieceIndex);
-
-      if (!torrent.bitfield?.get(pieceIndex)) {
-        // Everything from here to the end of the window is wanted NOW, so all
-        // of it is marked, not just the piece under the head. `critical`
-        // enables hotswap: a block reserved by a slow peer is re-requested from
-        // a faster one instead of holding up the reader. Measured 2026-08-04
-        // with only the blocked piece marked, the first segment after a seek
-        // took 7.2 s while its four 4 MB pieces arrived one after another at
-        // ~2.2 MB/s, with waits of 1.3 s and 2.8 s on single pieces.
-        //
-        // This is not the old behaviour returning: that marked the whole
-        // REQUESTED RANGE, which for ffmpeg's input means every piece to the
-        // end of the file — hundreds of them, at which point the flag says
-        // nothing. A window is what a reader genuinely needs next.
-        // Stated as its own need at the level that is being waited on, which
-        // is what carries the permission to take a block from a slow peer.
-        // Nothing here calls the library: `reconcile` reads what is stated.
-        stateBand({ from: pieceIndex, to: window.to, urgency: Urgency.BLOCKED });
-        blockedStated = true;
-        selection.reconcile();
-      }
-
-      const waitStartedAt = Date.now();
-      // What the WHOLE torrent received while this one piece was missing. It is
-      // the reading that separates the two causes a wait can have, and neither
-      // could be told from the other before: bytes arriving briskly throughout
-      // mean the swarm had capacity and this piece was stuck behind the wire
-      // that reserved it — the blocked-piece tail; bytes barely moving mean
-      // there was nothing to be had, and no reordering of requests would have
-      // helped. Asked of 2026-08-31, when a session with 4-5 peers of 38 known
-      // waited 41.32 s at worst and the log could not say which it was.
-      const downloadedAtWaitStart = Number(torrent?.downloaded) || 0;
-      // The reader is blocked, so this piece is now the only thing that matters
-      // on this torrent: hand it to the fastest wires that hold it. A block is
-      // reserved for exactly one wire, and the read ends when the slowest
-      // holder delivers — measured 2026-08-17, the swarm had a fivefold surplus
-      // of bandwidth and the reader still waited 1.0-4.5 s, 47 times in two
-      // minutes, on pieces five peers already had.
-      let pushed = { asked: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 };
-      // The tail as it stood at an attempt that placed NOTHING — the state the
-      // duplication work has to answer, and the only one worth a line. Sampled
-      // at that instant rather than once up front, because the steering runs
-      // again every half second and the piece changes under it; the last such
-      // reading is kept, so the line describes the most recent failure.
-      let tailWhenNothingPlaced = null;
-      // What duplicating the tail placed, summed over the wait. Measured
-      // 2026-08-19 on a real swarm: the blocks a reader waits on are 2-14 of
-      // 512 and sit on wires the library considers fast, so its own hotswap
-      // never fires for them — see `duplicateTailFor`.
-      let duplicated = 0;
-      const pushToFastest = () => {
-        try {
-          const result = askFastestWiresFor(torrent, pieceIndex);
-          if (result.asked === 0) {
-            tailWhenNothingPlaced = describePieceTail(torrent, pieceIndex);
-          }
-          // Every attempt, not only the ones where nothing else could be placed.
-          // The ordinary steering asks for whatever blocks are still free; the
-          // read, meanwhile, ends when the LAST block arrives, and that block is
-          // reserved to one wire whether or not other blocks could be asked for.
-          // Field 2026-09-03: 46.3 s on one piece, ordinary requests placed on
-          // 54 of 87 attempts throughout, and a tail of 3 blocks of 512 held by
-          // wires at 51-99 KB/s to the end — while duplication, which ran only
-          // on the 33 attempts that placed nothing, managed 5 blocks in the
-          // whole wait. `duplicateTailFor` bounds itself by the tail's length,
-          // so a piece that is merely still arriving is left alone.
-          duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
-          pushed = {
-            asked: pushed.asked + result.asked,
-            refusedWhileReserved:
-              (pushed.refusedWhileReserved ?? 0) + (result.refusedWhileReserved ?? 0),
-            // Summed like the successes, so the line compares two totals over
-            // the same attempts instead of a total against a snapshot.
-            attempted: (pushed.attempted ?? 0) + result.attempted,
-            considered: result.considered,
-            fastestBytesPerSecond: result.fastestBytesPerSecond
-          };
-        } catch (error) {
-          // The entry is internal to the library; if a version changes it, this
-          // lever stops working and that must be visible rather than silent.
-          logger.warn(`piece-reader: could not steer piece ${pieceIndex} — ${error?.message ?? error}`);
+    for (let index = first; index <= last; index++) {
+      if (cancellation.isCancelled()) return;
+      const pieceStart = index * pieceLength;
+      const wanted = () => register.windows().some(window => window.fileIndex === fileIndex &&
+        window.byteStart + file.offset < pieceStart + pieceLength && window.byteEnd + file.offset >= pieceStart);
+      let retries = 0;
+      while (true) {
+        const waitAt = Date.now();
+        countBlockedReader(torrent.infoHash, 1);
+        try { await whenPieceReady(torrent, index, cancellation, wanted); }
+        finally { countBlockedReader(torrent.infoHash, -1); }
+        const waitedMs = Date.now() - waitAt;
+        if (index > first && waitedMs >= PIECE_WAIT_LOG_MS) {
+          const key = `${torrent.infoHash ?? "?"}/${file.name ?? "?"}`;
+          noteSupplyWait(key, file.name ?? "", waitedMs);
+          const level = register.urgencyAt(fileIndex, Math.max(0, pieceStart - file.offset));
+          if (level !== null) noteWaitLevel(key, waitedMs, level);
         }
-      };
-      if (canPlaceRequests(torrent)) {
-        pushToFastest();
-      } else {
-        // Nothing can be placed at all on this build, so the tail is the whole
-        // of the answer.
-        tailWhenNothingPlaced = describePieceTail(torrent, pieceIndex);
-        logger.warn(
-          "piece-reader: this webtorrent build offers no way to place a request; " +
-            "the blocked piece cannot be steered onto a faster peer"
-        );
-      }
-      // Sampled while waiting rather than after: once the piece lands, nothing
-      // is outstanding on it any more and every count reads zero.
-      let supply = null;
-      const supplyProbe = setInterval(() => {
-        const sample = pieceSupply(torrent, pieceIndex);
-        if (!supply || sample.blocks > supply.blocks) {
-          supply = sample;
-        }
-        // Wires come and go, and their speeds change: a holder that was slow a
-        // moment ago may now be the fastest one available.
-        pushToFastest();
-      }, 500);
-      // Counted for exactly as long as this reader is inside the wait, so that
-      // background work can stand aside while the viewer's own reading is
-      // starving. The `finally` is what makes it safe: a cancelled or failed
-      // read must not leave the torrent looking permanently blocked, which
-      // would stop that background work for the rest of the session.
-      countBlockedReader(torrent?.infoHash, 1);
-      try {
-        await whenPieceReady(torrent, pieceIndex, cancellation);
-      } finally {
-        countBlockedReader(torrent?.infoHash, -1);
-        clearInterval(supplyProbe);
-      }
-      // What a reader spent waiting for data, attributed to the exact piece. A
-      // seek's cost is dominated by the first segment after the encoder
-      // restarts (measured 9.2-9.4 s), and without this there is no way to say
-      // whether that is the swarm, the picker, or ffmpeg. Logged only when the
-      // wait is long enough to matter, so ordinary sequential reading is silent.
-      const waitedMs = Date.now() - waitStartedAt;
-      // Where the map puts this piece, read once and used by both the
-      // attribution below and the line beside it.
-      const wantedBy = mapLevelOf(pieceIndex);
-      // The window answers to what just happened: a wait means the lead was too
-      // short, an immediate hit means it is longer than it needs to be. Applied
-      // before the logging below so the line reports the window the next piece
-      // will actually use.
-      if (waitBelongsToJump) {
-        // Recorded nowhere: see `waitBelongsToJump`. Said out loud, because a
-        // gap in the supply history is otherwise indistinguishable from a swarm
-        // that never made the reader wait.
-        logger.info(
-          `piece-reader: ${waitedMs}ms on the first piece after a jump — the cost of moving, ` +
-            `not of this swarm's supply, so it is not counted against the quality offer`
-        );
-        waitBelongsToJump = false;
-      } else {
-        const supplyKey = `${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`;
-        noteSteeringOutcome(supplyKey, waitedMs, pushed.asked > 0 || duplicated > 0);
-        // Which level of the priority map the reader was stopped in. A wait
-        // belongs to a level, and the level says whether that zone is asked for
-        // too late — the reader itself no longer has an opinion about it.
-        noteWaitLevel(
-          supplyKey,
-          waitedMs,
-          wantedBy ?? Urgency.BLOCKED
-        );
-        waitCount += 1;
-        waitedTotalMs += waitedMs;
-        noteSupplyWait(supplyKey, file?.name ?? "", waitedMs);
-      }
-      const widened = nextWindowPieces({
-        current: windowPieces,
-        base: basePieces,
-        ceiling: ceilingPieces(),
-        waitedMs,
-        waitThresholdMs: PIECE_WAIT_LOG_MS
-      });
-      if (widened !== windowPieces) {
-        windowPieces = widened;
-      }
-      if (waitedMs >= PIECE_WAIT_LOG_MS) {
-        const rateKbps = Math.round(pieceLength / 1024 / (waitedMs / 1000));
-        // Two rates, side by side, and no verdict word between them: the swarm's
-        // own delivery during the wait against what this piece managed. Both are
-        // measured; which one a reader calls "the cause" follows from the pair
-        // without a threshold having to be chosen here. Far apart means the
-        // bytes were flowing and this piece was not among them; close together,
-        // or both near zero, means there was nothing to deliver.
-        const swarmBytes = Math.max(0, (Number(torrent?.downloaded) || 0) - downloadedAtWaitStart);
-        const swarmKbps = Math.round(swarmBytes / 1024 / (waitedMs / 1000));
-        logger.info(
-          `piece-reader: waited ${waitedMs}ms for piece ${pieceIndex} ` +
-            `(${pieceIndex - firstPiece + 1} of ${lastPiece - firstPiece + 1} in a read from ` +
-            `${(start / 1024 / 1024).toFixed(0)}MB of "${file.name}") ` +
-            `— ${rateKbps}KB/s on this piece while the swarm delivered ` +
-            `${swarmKbps}KB/s (${(swarmBytes / 1024 / 1024).toFixed(1)}MB) across the torrent, ` +
-            `${Number(torrent?.numPeers) || 0} peers connected; ` +
-            (supply
-              ? `${supply.holders}/${supply.peers} peers had it, ${supply.askedOf} were asked, ` +
-                `${supply.blocks} blocks (${Math.round((supply.blocks * 16384) / 1024)}KB) in flight at peak`
-              : "no sample taken") +
-            // What WE did about it, so the next session says whether steering
-            // the piece onto faster holders shortens the tail — by number
-            // rather than by impression.
-            `; steered onto ${pushed.asked} of ${pushed.attempted} asks (${pushed.considered} peers held it)` +
-            // How often a fast peer we picked was refused because every block
-            // was already spoken for and the library declined to take one from
-            // a slow holder. Its thresholds are constants, not settings: the
-            // asker must be above 16 KB/s, the holder below 48 KB/s and twice
-            // as slow. A number here is what would justify replacing that rule;
-            // a zero says the thresholds are not what we are short of.
-            ((pushed.refusedWhileReserved ?? 0) > 0
-              ? `; ${pushed.refusedWhileReserved} refused with every block reserved`
-              : "") +
-            (pushed.fastestBytesPerSecond > 0
-              ? `, fastest ${Math.round(pushed.fastestBytesPerSecond / 1024)}KB/s`
-              : "") +
-            // Only when the steering placed nothing, which is the case that
-            // decides whether duplicating the tail is worth building: it says
-            // how much of the piece is still missing and which wires are
-            // holding it, slowest first.
-            (tailWhenNothingPlaced
-              ? `; tail ${tailWhenNothingPlaced.missing}/${tailWhenNothingPlaced.chunks} blocks missing, held by ` +
-                (tailWhenNothingPlaced.outstanding.length > 0
-                  ? tailWhenNothingPlaced.outstanding
-                    .map((wire) => `${wire.blocks}@${Math.round(wire.bytesPerSecond / 1024)}KB/s` +
-                      (wire.choking ? " (choking)" : ""))
-                    .join(" ")
-                  : "nobody")
-              : "") +
-            // What we did about the tail, so the next session says by number
-            // whether a second copy of those blocks shortens the wait.
-            (duplicated > 0 ? `; duplicated ${duplicated} blocks` : "") +
-            // Where the priority map puts this piece. A wait at the level the
-            // viewer is about to reach is a different fault from a wait on the
-            // speculative tail, and the reader states nothing of its own that
-            // could be read instead.
-            `; the map wants it ${wantedBy === null
-              ? "nowhere — nobody asked for this piece"
-              : urgencyName(wantedBy)}`
-        );
-      }
-
-      // Pinned BEFORE it is located, and before any await that could let an
-      // eviction run: the offset is only meaningful while the piece is held.
-      store.pin(pieceIndex);
-      let located = null;
-      try {
-        located = await store.reside(pieceIndex);
-      } catch (error) {
-        store.unpin(pieceIndex);
-        throw error;
-      }
-
-      if (!located) {
-        store.unpin(pieceIndex);
-        // THE CLAIM HAS JUST BEEN WITHDRAWN, so this is a wait and not a
-        // failure. The store drops a piece behind every read head, and a read
-        // that re-opens an input at byte 0 — which is every encoder restart —
-        // asks for exactly those pieces. Until 2026-09-12 this threw, ffmpeg
-        // read the empty body as the end of the file, and the encoder died and
-        // was restarted into the same emptiness: field, `Piece 0 is verified
-        // but absent from the store` answered every read for 92 minutes while
-        // the viewer looked at a still picture.
-        //
-        // Going back one step re-runs this piece's whole path rather than a
-        // shortened copy of it: the bitfield now says the piece is missing, so
-        // the block above declares it, steers it onto the fastest holders and
-        // waits for it, exactly as it does for a piece that was never here.
-        // Once per piece — a second emptiness means the bytes are not coming
-        // and the caller must hear so.
-        if (withdrawnRetries === 0) {
-          withdrawnRetries += 1;
-          pieceIndex -= 1;
-          continue;
+        if (cancellation.isCancelled()) return;
+        store.pin(index);
+        let located;
+        try { located = await store.reside(index); }
+        catch (error) { store.unpin(index); throw error; }
+        if (!located) {
+          store.unpin(index);
+          if (retries++ === 0) continue;
+          throw new Error(`Piece ${index} was withdrawn from the store and did not come back.`);
         }
-        throw new Error(
-          `Piece ${pieceIndex} was withdrawn from the store and did not come back.`
-        );
+        let released = false;
+        release = () => { if (!released) { released = true; store.unpin(index); } };
+        const from = Math.max(absoluteStart, pieceStart) - pieceStart;
+        const through = Math.min(absoluteEnd, pieceStart + pieceLength - 1) - pieceStart;
+        yield { pieceIndex: index, buffer: located.buffer, offset: located.offset + from,
+          length: through - from + 1, release };
+        release();
+        release = null;
+        break;
       }
-      // Counted per piece: a long read may legitimately meet this more than
-      // once, and each piece is entitled to its own second chance.
-      withdrawnRetries = 0;
-
-      let releasedThisPiece = false;
-      // Remembered so the generator can drop it itself. The pin is taken here
-      // and the consumer is expected to release it — but a consumer that
-      // ABANDONS the iterator never gets the chance, and a seek abandons it
-      // every time: the encoder is killed, the response is torn down, and the
-      // loop is left between two fragments. Field 2026-08-06: after one seek
-      // every slot in the store was pinned, the store answered
-      // `Every resident piece is pinned; no slot can be freed` — to the
-      // WebTorrent client, which closed the store and destroyed the torrent —
-      // and the session died with `File 0 not found`.
-      releaseHeldPin = () => {
-        if (!releasedThisPiece) {
-          releasedThisPiece = true;
-          store.unpin(pieceIndex);
-        }
-      };
-      // What the consumer takes, counted as it is handed over: for a viewer this
-      // is the film's own byte rate, which is what the band widths are derived
-      // against.
-      deliveredBytes += toWithinPiece - fromWithinPiece + 1;
-      yield {
-        pieceIndex,
-        buffer: located.buffer,
-        offset: located.offset + fromWithinPiece,
-        length: toWithinPiece - fromWithinPiece + 1,
-        release() {
-          if (releasedThisPiece) {
-            return;
-          }
-          releasedThisPiece = true;
-          store.unpin(pieceIndex);
-        }
-      };
-      // Handed back, and released by the consumer or not at all — either way
-      // this reader no longer owes anything for it.
-      releaseHeldPin = null;
-    }
-  } finally {
-    // A fragment handed out and never released is a slot lost for the life of
-    // the process. Reached on every exit, including the consumer walking away.
-    if (releaseHeldPin) {
-      releaseHeldPin();
-      releaseHeldPin = null;
     }
-    // What this read did, said once at its end and under EVERY outcome: how
-    // much it delivered, and how much of that time it spent stopped. Said even
-    // when it never stopped, because "no wait" is the result worth counting and
-    // a line printed only beside a wait cannot report it.
-    const readSeconds = (Date.now() - readStartedAt) / 1000;
-    if (deliveredBytes > 0) {
-      logger.info(
-        `read "${String(file?.name ?? "?").slice(0, 40)}" ` +
-        `delivered=${(deliveredBytes / 1e6).toFixed(1)}MB in ${readSeconds.toFixed(1)}s ` +
-        `waits=${waitCount} waited=${(waitedTotalMs / 1000).toFixed(1)}s`
-      );
-    }
-    // Reached on completion, on cancellation, on a throw, and when the consumer
-    // stops iterating — a claim left behind would keep the swarm fetching for a
-    // reader that no longer exists.
-    if (blockedStated) {
-      register.withdraw(`${readerId}:${urgencyName(Urgency.BLOCKED)}`);
-    }
-    // Once, after everything has been withdrawn — and it releases this reader's
-    // hold on memory as well, because both views come from the same statement.
-    selection.reconcile();
-  }
+  } finally { release?.(); }
 }