@torrent-tv/proxy 2.39.0 → 2.40.0

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

@@ -1,772 +1,1114 @@
-/**
- * @file Reading a byte range as positions in shared memory, not as bytes.
- *
- * The pieces already live in a `SharedArrayBuffer` the main thread can map. So
- * the torrent thread does not need to hand over any bytes at all: it can say
- * *where* a piece sits and let the other side read it there. What crosses the
- * boundary is two numbers per piece.
- *
- * That is the whole point of the exercise. The alternative — copying each piece
- * into memory we own and transferring it — costs 18.84 ms per 10 MB segment on
- * the field host, and costs it **on the critical path**, in the thread that is
- * also running the torrent, at the moment a viewer is waiting for that segment.
- * Here the copy is gone entirely rather than moved.
- *
- * Two obligations come with it, and both are enforced rather than assumed:
- *
- *  - a piece being read is **pinned**, so eviction cannot take the memory out
- *    from under the reader mid-read;
- *  - the pin is released only once the other thread reports it has finished
- *    with those bytes — not when they were sent, because nothing was sent.
- */
-
-import { findSharedStore } from "../piece-store/shared-piece-store.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);
-}
-
-/**
- * Add this reader's window to the download set as a stream selection.
- *
- * `_select`/`_deselect` with the stream flag are what WebTorrent's own
- * `FileIterator` uses; there is no public call for it, because the public
- * `select` produces the merging, interval-subtracted kind whose bookkeeping
- * cannot express "one of several readers wants this". Falls back to the public
- * call if a future version drops the private one.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {{ from: number, to: number }} window
- * @param {number} [priority] - 1 for what a reader needs next, 0 for the
- *   background fill of the rest of the file.
- * @returns {void}
- */
-function claimWindow(torrent, { from, to }, priority = 1) {
-  try {
-    if (typeof torrent._select === "function") {
-      torrent._select(from, to, priority, null, true);
-    } else if (typeof torrent.select === "function") {
-      torrent.select(from, to, priority);
-    }
-  } catch {
-    // Best effort — never fail a read because selection bookkeeping refused.
-  }
-}
-
-/**
- * Take this reader's window back out of the download set.
- *
- * The bounds must match the ones given to {@link claimWindow} exactly: a stream
- * selection is removed by equality, not by overlap.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {{ from: number, to: number }} window
- * @returns {void}
- */
-function releaseWindow(torrent, { from, to }) {
-  try {
-    if (typeof torrent._deselect === "function") {
-      torrent._deselect(from, to, true);
-    } else if (typeof torrent.deselect === "function") {
-      torrent.deselect(from, to);
-    }
-  } catch {
-    // Best effort.
-  }
-}
-
-/**
- * Mark the piece a reader is blocked on, clearing the mark it set before.
- *
- * Criticality is never cleared by WebTorrent itself, so a reader that walked a
- * film would leave every piece of it marked. Only the indices this reader set
- * are cleared, so a second reader's mark on the same piece is not stolen — and
- * the flag is advisory anyway.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {number} from
- * @param {number} to
- * @param {{ from: number, to: number } | null} previous
- * @returns {{ from: number, to: number } | null}
- */
-function markCritical(torrent, from, to, previous) {
-  if (previous && previous.from === from && previous.to === to) {
-    return previous;
-  }
-  if (previous) {
-    clearCritical(torrent, previous);
-  }
-  try {
-    torrent.critical?.(from, to);
-  } catch {
-    return null;
-  }
-  return { from, to };
-}
-
-/**
- * Drop critical marks this reader set.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {{ from: number, to: number }} mark
- * @returns {void}
- */
-function clearCritical(torrent, { from, to }) {
-  if (!Array.isArray(torrent._critical)) {
-    return;
-  }
-  for (let index = from; index <= to; index += 1) {
-    torrent._critical[index] = false;
-  }
-}
-
-/**
- * Who is working on the piece a reader is blocked on, right now.
- *
- * The open question about a seek: a single 8 MiB piece takes 3.0-4.6 s to
- * arrive while the swarm as a whole is moving 4-6 MB/s, so roughly 2 MB/s is
- * reaching the piece that is actually being waited for. Whether that is because
- * few peers hold it, few are being asked, or each is slow cannot be told apart
- * from the outside — these three counts tell them apart.
- *
- * `wire.requests` is what has been asked of that peer and not yet answered; a
- * block is 16 KB, so `blocks x 16 KB` is the work in flight on this piece.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {number} pieceIndex
- * @returns {{ peers: number, holders: number, askedOf: number, blocks: number }}
- */
-export function pieceSupply(torrent, pieceIndex) {
-  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
-  let holders = 0;
-  let askedOf = 0;
-  let blocks = 0;
-  for (const wire of wires) {
-    if (wire?.peerPieces?.get?.(pieceIndex)) {
-      holders += 1;
-    }
-    const requests = Array.isArray(wire?.requests) ? wire.requests : [];
-    const forThisPiece = requests.filter((request) => request?.piece === pieceIndex).length;
-    if (forThisPiece > 0) {
-      askedOf += 1;
-      blocks += forThisPiece;
-    }
-  }
-  return { peers: wires.length, holders, askedOf, blocks };
-}
-
-/**
- * Wait until a piece has been downloaded and verified.
- *
- * WebTorrent announces this as `verified`. The bitfield is re-checked after the
- * listener is attached because the piece can complete in between, and a missed
- * event here would wait forever.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {number} index
- * @param {{ isCancelled: () => boolean }} cancellation
- * @returns {Promise<void>}
- */
-function whenPieceReady(torrent, index, cancellation) {
-  if (torrent.bitfield?.get(index)) {
-    return Promise.resolve();
-  }
-
-  return new Promise((resolve, reject) => {
-    /** @param {number} verifiedIndex */
-    const onVerified = (verifiedIndex) => {
-      if (verifiedIndex === index) {
-        cleanup();
-        resolve();
-      }
-    };
-    const onDestroyed = () => {
-      cleanup();
-      reject(new Error(`Torrent went away while waiting for piece ${index}.`));
-    };
-    // Cancellation is polled rather than pushed: a superseded seek destroys the
-    // read, and without this the wait would outlive it and hold a pin.
-    const poll = setInterval(() => {
-      if (cancellation.isCancelled()) {
-        cleanup();
-        reject(new Error(`Read cancelled while waiting for piece ${index}.`));
-      }
-    }, 250);
-
-    function cleanup() {
-      clearInterval(poll);
-      torrent.removeListener("verified", onVerified);
-      torrent.removeListener("close", onDestroyed);
-    }
-
-    torrent.on("verified", onVerified);
-    torrent.once("close", onDestroyed);
-
-    // The piece may have arrived between the check above and this listener.
-    if (torrent.bitfield?.get(index)) {
-      cleanup();
-      resolve();
-    }
-  });
-}
-
-/**
- * A fragment of a read: where to find it, and how to let it go.
- *
- * @typedef {object} PieceFragment
- * @property {number} pieceIndex
- * @property {number} offset - Byte offset into the shared pool.
- * @property {number} length
- * @property {() => void} release - Drops this fragment's pin. Call exactly once.
- */
-
-/**
- * Walk a byte range of a file, yielding each piece's position in shared memory.
- *
- * Yields at most one fragment per piece; the first and last are usually partial.
- * The caller must `release()` every fragment it receives, including on failure —
- * an unreleased pin permanently costs a slot.
- *
- * @param {object} params
- * @param {import("webtorrent").Torrent} params.torrent
- * @param {number} params.fileIndex
- * @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>}
- */
-/**
- * The last interruptions this file's readers met, newest last.
- *
- * Bounded and per file, because both figures derived from it describe THIS
- * file on THIS swarm: a piece is 8 MiB here and 512 KiB elsewhere, and a swarm
- * that answers in 200 ms today may not tomorrow. Nothing is stored beyond the
- * process — a restart starts from no evidence, which is the honest state.
- *
- * @type {Map<string, Array<{ waitedMs: number, at: number }>>}
- */
-const supplyWaits = new Map();
-
-/** How many interruptions are kept per file. */
-const SUPPLY_WAIT_HISTORY = 40;
-
-/** How often the derived figures are printed, at most. */
-const SUPPLY_REPORT_INTERVAL_MS = 30_000;
-
-/** When each file's figures were last printed. */
-const supplyReportedAt = new Map();
-
-/**
- * Record one interruption and, at most twice a minute, say what it implies.
- *
- * The two figures are the whole of roadmap item 3: the speed a step must
- * sustain to survive this supply (`1 + worst wait / median interval`), and the
- * smallest buffer that hides an interruption from the viewer. Both are printed
- * before either is USED, so the field says whether the arithmetic describes
- * reality before anything is decided by it.
- *
- * @param {string} key - Something stable per file.
- * @param {string} label - What to call it in the log.
- * @param {number} waitedMs
- * @returns {void}
- */
-/**
- * What this file's recent interruptions demand, for a caller that has to decide
- * something with them.
- *
- * Exported because the figures are measured HERE — the reader is the only place
- * that knows how long it waited — while the decisions they feed are made
- * elsewhere: the smallest buffer that hides an interruption goes to the browser,
- * and the speed a step must sustain goes to the quality offer.
- *
- * @param {string} infoHash
- * @param {string} fileName
- * @param {number} segmentSeconds - The session's own segment duration.
- * @returns {{ requiredSpeed: number, worstWaitSec: number, medianIntervalSec: number, samples: number, minimumBufferSec: number } | null}
- */
-export function supplyFiguresFor(infoHash, fileName, segmentSeconds) {
-  const history = supplyWaits.get(`${infoHash ?? "?"}/${fileName ?? "?"}`);
-  const demand = requiredSpeedFrom(history ?? []);
-  if (!demand) {
-    return null;
-  }
-  const buffer = minimumBufferFrom({
-    segmentSeconds,
-    worstSupplyWaitSec: demand.worstWaitSec
-  });
-  return {
-    requiredSpeed: demand.requiredSpeed,
-    worstWaitSec: demand.worstWaitSec,
-    medianIntervalSec: demand.medianIntervalSec,
-    samples: demand.samples,
-    minimumBufferSec: buffer ? buffer.seconds : null
-  };
-}
-
-function noteSupplyWait(key, label, waitedMs) {
-  const history = supplyWaits.get(key) ?? [];
-  history.push({ waitedMs, at: Date.now() });
-  while (history.length > SUPPLY_WAIT_HISTORY) {
-    history.shift();
-  }
-  supplyWaits.set(key, history);
-
-  const now = Date.now();
-  if (now - (supplyReportedAt.get(key) ?? 0) < SUPPLY_REPORT_INTERVAL_MS) {
-    return;
-  }
-  const demand = requiredSpeedFrom(history);
-  if (!demand) {
-    return;
-  }
-  supplyReportedAt.set(key, now);
-  const buffer = minimumBufferFrom({
-    segmentSeconds: SEGMENT_SECONDS_FOR_BUFFER,
-    worstSupplyWaitSec: demand.worstWaitSec
-  });
-  logger.info(
-    `supply "${label.slice(0, 40)}": a step must run at ${demand.requiredSpeed.toFixed(2)}x ` +
-    `to survive this swarm (worst wait ${demand.worstWaitSec.toFixed(2)}s, one every ` +
-    `${demand.medianIntervalSec.toFixed(2)}s, ${demand.samples} measured) — ` +
-    `and the smallest buffer that hides it is ${buffer ? buffer.seconds.toFixed(1) : "?"}s`
-  );
-}
-
-/**
- * The segment length the buffer figure is stated against. The reader does not
- * know the session's own, and this is a REPORT rather than a decision — the
- * decision, when it is made, will use the session's real one.
- */
-const SEGMENT_SECONDS_FOR_BUFFER = 4;
-
-export async function* readFragments({
-  torrent,
-  fileIndex,
-  start,
-  end,
-  cancellation,
-  windowBytes = READ_WINDOW_BYTES
-}) {
-  const store = findSharedStore(torrent);
-  if (!store) {
-    throw new Error("This torrent is not backed by a shared piece store.");
-  }
-
-  const file = torrent.files?.[fileIndex];
-  if (!file) {
-    throw new Error(`File ${fileIndex} not found.`);
-  }
-
-  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 criticalMark = null;
-  /**
-   * 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;
-
-  const moveWindowTo = (pieceIndex) => {
-    const next = readWindowFor({ pieceIndex, lastPiece, windowPieces });
-    if (window && window.from === next.from && window.to === next.to) {
-      return;
-    }
-    const isJump = !window || next.from > window.to || next.from < window.from;
-    if (window) {
-      releaseWindow(torrent, window);
-    }
-    claimWindow(torrent, next);
-    window = next;
-    // Tell the store these pieces are wanted, so it evicts something else.
-    // Without it the piece the decoder reads next looks exactly as stale as one
-    // the encoder fetched forty minutes ahead, and the second kind is what
-    // fills the store while the encoder runs ahead of the viewer.
-    store.protectRange?.(readerId, next.from, next.to);
-    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}"`
-        );
-      }
-    }
-  };
-
-  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.
-        criticalMark = markCritical(torrent, pieceIndex, window.to, criticalMark);
-      }
-
-      const waitStartedAt = Date.now();
-      // 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);
-            // Nothing could be placed the ordinary way, which means every block
-            // is spoken for. That is exactly when a second copy of the last
-            // blocks is worth asking for.
-            duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
-          }
-          pushed = {
-            asked: pushed.asked + result.asked,
-            // 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}`);
-        }
-      };
-      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);
-      try {
-        await whenPieceReady(torrent, pieceIndex, cancellation);
-      } finally {
-        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;
-      // 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 {
-        noteSupplyWait(`${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`, 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));
-        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; ` +
-            (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)` +
-            (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` : "")
-        );
-      }
-
-      // 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);
-        throw new Error(`Piece ${pieceIndex} is verified but absent from the store.`);
-      }
-
-      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);
-        }
-      };
-      yield {
-        pieceIndex,
-        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;
-    }
-    // Reached on completion, on cancellation, on a throw, and when the consumer
-    // stops iterating — a window left behind would keep the swarm fetching for
-    // a reader that no longer exists.
-    if (window) {
-      releaseWindow(torrent, window);
-    }
-    store.releaseProtection?.(readerId);
-    if (criticalMark) {
-      clearCritical(torrent, criticalMark);
-    }
-  }
-}
+/**
+ * @file Reading a byte range as positions in shared memory, not as bytes.
+ *
+ * The pieces already live in a `SharedArrayBuffer` the main thread can map. So
+ * the torrent thread does not need to hand over any bytes at all: it can say
+ * *where* a piece sits and let the other side read it there. What crosses the
+ * boundary is two numbers per piece.
+ *
+ * That is the whole point of the exercise. The alternative — copying each piece
+ * into memory we own and transferring it — costs 18.84 ms per 10 MB segment on
+ * the field host, and costs it **on the critical path**, in the thread that is
+ * also running the torrent, at the moment a viewer is waiting for that segment.
+ * Here the copy is gone entirely rather than moved.
+ *
+ * Two obligations come with it, and both are enforced rather than assumed:
+ *
+ *  - a piece being read is **pinned**, so eviction cannot take the memory out
+ *    from under the reader mid-read;
+ *  - the pin is released only once the other thread reports it has finished
+ *    with those bytes — not when they were sent, because nothing was sent.
+ */
+
+import { findSharedStore } from "../piece-store/shared-piece-store.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;
+
+/**
+ * How urgently each band is wanted, most urgent first.
+ *
+ * Distinct numbers, and none of them zero: WebTorrent selects the whole torrent
+ * at priority 0 for the background fill, so a band at 0 would be indistinguishable
+ * from it. Equal non-zero priorities are deliberately shuffled against each other
+ * by the library (`shufflePriority`), so bands that must keep their order have to
+ * differ.
+ *
+ * 4 is what the viewer reaches in seconds; 3 and 2 are the lead being built ahead
+ * of them; 1 is what was never downloaded BEHIND the position, which only a
+ * backward seek needs.
+ */
+/**
+ * Which way this proxy claims what a reader wants, when the deployment names it:
+ * `flat` is the single band every release before this used, `bands` is the four
+ * described above. Anything else — the default — alternates per read, so the two
+ * accumulate side by side from real viewing and the log can compare them.
+ */
+const READ_MODE_SETTING = process.env.TORRENT_TV_READ_MODE ?? "";
+
+const BAND_PRIORITIES = [4, 3, 2, 1];
+
+/**
+ * Where each band sits, given the urgent one and how far the trailing bands have
+ * been allowed to grow.
+ *
+ * The urgent band is the reader's own window, anchored at the first piece it does
+ * not already hold. Behind it the lead is built in two steps rather than one, so
+ * the nearer half is asked for before the farther half; behind THOSE, once they
+ * have reached the end of the file, comes whatever was never downloaded before the
+ * position — needed only if the viewer seeks backwards, and never ahead of the
+ * picture they are watching.
+ *
+ * @param {{ urgent: { from: number, to: number }, pieceIndex: number, firstPiece: number, lastPiece: number, widths: { near: number, far: number } }} params
+ * @returns {Array<{ from: number, to: number, priority: number }>}
+ */
+export function bandsFrom({ urgent, pieceIndex, firstPiece, lastPiece, widths }) {
+  const bands = [{ from: urgent.from, to: urgent.to, priority: BAND_PRIORITIES[0] }];
+  let edge = urgent.to;
+  for (let index = 0; index < 2; index += 1) {
+    if (edge >= lastPiece) {
+      break;
+    }
+    const width = index === 0 ? widths.near : widths.far;
+    if (width <= 0) {
+      break;
+    }
+    const from = edge + 1;
+    const to = Math.min(lastPiece, edge + width);
+    bands.push({ from, to, priority: BAND_PRIORITIES[index + 1] });
+    edge = to;
+  }
+  // Only once the lead has nothing left to cover: asking for the past while the
+  // future is still missing would take capacity from the picture being watched.
+  if (edge >= lastPiece && pieceIndex > firstPiece) {
+    bands.push({ from: firstPiece, to: pieceIndex - 1, priority: BAND_PRIORITIES[3] });
+  }
+  return bands;
+}
+
+/**
+ * How wide the two lead bands should be, in pieces, from what has been measured
+ * about this file on this swarm.
+ *
+ * Nothing here is chosen. The near band has to cover the worst interruption this
+ * reader has actually met, because that is what must already be in hand for one
+ * not to reach the viewer: `worstWait × consumeRate`. The far band has to cover
+ * what the swarm can put ahead of the viewer between interruptions, which is the
+ * surplus it delivers over what the film eats, for as long as it typically runs
+ * without stopping: `(downloadRate - consumeRate) × medianInterval`. A swarm
+ * with no surplus produces no far band, which is correct — there is nothing to
+ * get ahead with.
+ *
+ * Until a reader has met two interruptions there are no figures, and both bands
+ * fall back to the width of the urgent one; the log says so in words.
+ *
+ * @param {{ worstWaitSec: number | null, medianIntervalSec: number | null, downloadBytesPerSec: number, consumeBytesPerSec: number, pieceLength: number, basePieces: number }} params
+ * @returns {{ near: number, far: number, measured: boolean }}
+ */
+export function bandWidthsFrom({
+  worstWaitSec,
+  medianIntervalSec,
+  downloadBytesPerSec,
+  consumeBytesPerSec,
+  pieceLength,
+  basePieces
+}) {
+  const usable = Number.isFinite(worstWaitSec) && worstWaitSec > 0 &&
+    Number.isFinite(medianIntervalSec) && medianIntervalSec > 0 &&
+    Number.isFinite(consumeBytesPerSec) && consumeBytesPerSec > 0 &&
+    Number.isFinite(pieceLength) && pieceLength > 0;
+  if (!usable) {
+    return { near: basePieces, far: basePieces, measured: false };
+  }
+  const near = Math.max(1, Math.ceil((worstWaitSec * consumeBytesPerSec) / pieceLength));
+  const surplus = Math.max(0, (Number(downloadBytesPerSec) || 0) - consumeBytesPerSec);
+  const far = Math.max(0, Math.ceil((surplus * medianIntervalSec) / pieceLength));
+  return { near, far, measured: true };
+}
+
+/**
+ * Whether two sets of bands are the same, so an unchanged claim is not released
+ * and re-made on every read.
+ *
+ * @param {Array<{ from: number, to: number, priority: number }>} left
+ * @param {Array<{ from: number, to: number, priority: number }>} right
+ * @returns {boolean}
+ */
+export function sameBands(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return left.every((band, index) =>
+    band.from === right[index].from &&
+    band.to === right[index].to &&
+    band.priority === right[index].priority);
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Add this reader's window to the download set as a stream selection.
+ *
+ * `_select`/`_deselect` with the stream flag are what WebTorrent's own
+ * `FileIterator` uses; there is no public call for it, because the public
+ * `select` produces the merging, interval-subtracted kind whose bookkeeping
+ * cannot express "one of several readers wants this". Falls back to the public
+ * call if a future version drops the private one.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {{ from: number, to: number }} window
+ * @param {number} [priority] - 1 for what a reader needs next, 0 for the
+ *   background fill of the rest of the file.
+ * @returns {void}
+ */
+function claimWindow(torrent, { from, to }, priority = 1) {
+  try {
+    if (typeof torrent._select === "function") {
+      torrent._select(from, to, priority, null, true);
+    } else if (typeof torrent.select === "function") {
+      torrent.select(from, to, priority);
+    }
+  } catch {
+    // Best effort — never fail a read because selection bookkeeping refused.
+  }
+}
+
+/**
+ * Take this reader's window back out of the download set.
+ *
+ * The bounds must match the ones given to {@link claimWindow} exactly: a stream
+ * selection is removed by equality, not by overlap.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {{ from: number, to: number }} window
+ * @returns {void}
+ */
+function releaseWindow(torrent, { from, to }) {
+  try {
+    if (typeof torrent._deselect === "function") {
+      torrent._deselect(from, to, true);
+    } else if (typeof torrent.deselect === "function") {
+      torrent.deselect(from, to);
+    }
+  } catch {
+    // Best effort.
+  }
+}
+
+/**
+ * Mark the piece a reader is blocked on, clearing the mark it set before.
+ *
+ * Criticality is never cleared by WebTorrent itself, so a reader that walked a
+ * film would leave every piece of it marked. Only the indices this reader set
+ * are cleared, so a second reader's mark on the same piece is not stolen — and
+ * the flag is advisory anyway.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {number} from
+ * @param {number} to
+ * @param {{ from: number, to: number } | null} previous
+ * @returns {{ from: number, to: number } | null}
+ */
+function markCritical(torrent, from, to, previous) {
+  if (previous && previous.from === from && previous.to === to) {
+    return previous;
+  }
+  if (previous) {
+    clearCritical(torrent, previous);
+  }
+  try {
+    torrent.critical?.(from, to);
+  } catch {
+    return null;
+  }
+  return { from, to };
+}
+
+/**
+ * Drop critical marks this reader set.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {{ from: number, to: number }} mark
+ * @returns {void}
+ */
+function clearCritical(torrent, { from, to }) {
+  if (!Array.isArray(torrent._critical)) {
+    return;
+  }
+  for (let index = from; index <= to; index += 1) {
+    torrent._critical[index] = false;
+  }
+}
+
+/**
+ * Who is working on the piece a reader is blocked on, right now.
+ *
+ * The open question about a seek: a single 8 MiB piece takes 3.0-4.6 s to
+ * arrive while the swarm as a whole is moving 4-6 MB/s, so roughly 2 MB/s is
+ * reaching the piece that is actually being waited for. Whether that is because
+ * few peers hold it, few are being asked, or each is slow cannot be told apart
+ * from the outside — these three counts tell them apart.
+ *
+ * `wire.requests` is what has been asked of that peer and not yet answered; a
+ * block is 16 KB, so `blocks x 16 KB` is the work in flight on this piece.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {number} pieceIndex
+ * @returns {{ peers: number, holders: number, askedOf: number, blocks: number }}
+ */
+export function pieceSupply(torrent, pieceIndex) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
+  let holders = 0;
+  let askedOf = 0;
+  let blocks = 0;
+  for (const wire of wires) {
+    if (wire?.peerPieces?.get?.(pieceIndex)) {
+      holders += 1;
+    }
+    const requests = Array.isArray(wire?.requests) ? wire.requests : [];
+    const forThisPiece = requests.filter((request) => request?.piece === pieceIndex).length;
+    if (forThisPiece > 0) {
+      askedOf += 1;
+      blocks += forThisPiece;
+    }
+  }
+  return { peers: wires.length, holders, askedOf, blocks };
+}
+
+/**
+ * Wait until a piece has been downloaded and verified.
+ *
+ * WebTorrent announces this as `verified`. The bitfield is re-checked after the
+ * listener is attached because the piece can complete in between, and a missed
+ * event here would wait forever.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {number} index
+ * @param {{ isCancelled: () => boolean }} cancellation
+ * @returns {Promise<void>}
+ */
+function whenPieceReady(torrent, index, cancellation) {
+  if (torrent.bitfield?.get(index)) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve, reject) => {
+    /** @param {number} verifiedIndex */
+    const onVerified = (verifiedIndex) => {
+      if (verifiedIndex === index) {
+        cleanup();
+        resolve();
+      }
+    };
+    const onDestroyed = () => {
+      cleanup();
+      reject(new Error(`Torrent went away while waiting for piece ${index}.`));
+    };
+    // Cancellation is polled rather than pushed: a superseded seek destroys the
+    // read, and without this the wait would outlive it and hold a pin.
+    const poll = setInterval(() => {
+      if (cancellation.isCancelled()) {
+        cleanup();
+        reject(new Error(`Read cancelled while waiting for piece ${index}.`));
+      }
+    }, 250);
+
+    function cleanup() {
+      clearInterval(poll);
+      torrent.removeListener("verified", onVerified);
+      torrent.removeListener("close", onDestroyed);
+    }
+
+    torrent.on("verified", onVerified);
+    torrent.once("close", onDestroyed);
+
+    // The piece may have arrived between the check above and this listener.
+    if (torrent.bitfield?.get(index)) {
+      cleanup();
+      resolve();
+    }
+  });
+}
+
+/**
+ * A fragment of a read: where to find it, and how to let it go.
+ *
+ * @typedef {object} PieceFragment
+ * @property {number} pieceIndex
+ * @property {number} offset - Byte offset into the shared pool.
+ * @property {number} length
+ * @property {() => void} release - Drops this fragment's pin. Call exactly once.
+ */
+
+/**
+ * Walk a byte range of a file, yielding each piece's position in shared memory.
+ *
+ * Yields at most one fragment per piece; the first and last are usually partial.
+ * The caller must `release()` every fragment it receives, including on failure —
+ * an unreleased pin permanently costs a slot.
+ *
+ * @param {object} params
+ * @param {import("webtorrent").Torrent} params.torrent
+ * @param {number} params.fileIndex
+ * @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>}
+ */
+/**
+ * The last interruptions this file's readers met, newest last.
+ *
+ * Bounded and per file, because both figures derived from it describe THIS
+ * file on THIS swarm: a piece is 8 MiB here and 512 KiB elsewhere, and a swarm
+ * that answers in 200 ms today may not tomorrow. Nothing is stored beyond the
+ * process — a restart starts from no evidence, which is the honest state.
+ *
+ * @type {Map<string, Array<{ waitedMs: number, at: number }>>}
+ */
+const supplyWaits = new Map();
+
+/** How many interruptions are kept per file. */
+const SUPPLY_WAIT_HISTORY = 40;
+
+/** How often the derived figures are printed, at most. */
+const SUPPLY_REPORT_INTERVAL_MS = 30_000;
+
+/** When each file's figures were last printed. */
+const supplyReportedAt = new Map();
+
+/**
+ * Record one interruption and, at most twice a minute, say what it implies.
+ *
+ * The two figures are the whole of roadmap item 3: the speed a step must
+ * sustain to survive this supply (`1 + worst wait / median interval`), and the
+ * smallest buffer that hides an interruption from the viewer. Both are printed
+ * before either is USED, so the field says whether the arithmetic describes
+ * reality before anything is decided by it.
+ *
+ * @param {string} key - Something stable per file.
+ * @param {string} label - What to call it in the log.
+ * @param {number} waitedMs
+ * @returns {void}
+ */
+/**
+ * What this file's recent interruptions demand, for a caller that has to decide
+ * something with them.
+ *
+ * Exported because the figures are measured HERE — the reader is the only place
+ * that knows how long it waited — while the decisions they feed are made
+ * elsewhere: the smallest buffer that hides an interruption goes to the browser,
+ * and the speed a step must sustain goes to the quality offer.
+ *
+ * @param {string} infoHash
+ * @param {string} fileName
+ * @param {number} segmentSeconds - The session's own segment duration.
+ * @returns {{ requiredSpeed: number, worstWaitSec: number, medianIntervalSec: number, samples: number, minimumBufferSec: number } | null}
+ */
+export function supplyFiguresFor(infoHash, fileName, segmentSeconds) {
+  const history = supplyWaits.get(`${infoHash ?? "?"}/${fileName ?? "?"}`);
+  const demand = requiredSpeedFrom(history ?? []);
+  if (!demand) {
+    return null;
+  }
+  const buffer = minimumBufferFrom({
+    segmentSeconds,
+    worstSupplyWaitSec: demand.worstWaitSec
+  });
+  return {
+    requiredSpeed: demand.requiredSpeed,
+    worstWaitSec: demand.worstWaitSec,
+    medianIntervalSec: demand.medianIntervalSec,
+    samples: demand.samples,
+    minimumBufferSec: buffer ? buffer.seconds : null
+  };
+}
+
+/**
+ * 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 whether anything was steered during it.
+ *
+ * @param {string} key
+ * @param {number} waitedMs
+ * @param {boolean} steered
+ * @returns {void}
+ */
+function noteReadMode(key, waitedMs, mode) {
+  let split = waitsByMode.get(key);
+  if (!split) {
+    split = { flat: [], bands: [] };
+    waitsByMode.set(key, split);
+  }
+  const into = mode === "bands" ? split.bands : split.flat;
+  into.push(waitedMs);
+  while (into.length > SUPPLY_WAIT_HISTORY) {
+    into.shift();
+  }
+}
+
+/**
+ * What the two ways of claiming amount to, or null while either has no sample.
+ *
+ * This is the whole of the comparison: the same file, the same swarm, the same
+ * viewer, waits sorted by which arm was in force. It appears in the periodic
+ * summary so a session can be read without collecting lines by hand.
+ *
+ * @param {string} key
+ * @returns {string | null}
+ */
+function describeReadModes(key) {
+  const split = waitsByMode.get(key);
+  if (!split || split.flat.length === 0 || split.bands.length === 0) {
+    return null;
+  }
+  const middle = (values) => {
+    const sorted = [...values].sort((left, right) => left - right);
+    return sorted[Math.floor(sorted.length / 2)];
+  };
+  const worst = (values) => Math.max(...values);
+  return (
+    `flat ${split.flat.length} waits median ${middle(split.flat)}ms worst ${worst(split.flat)}ms, ` +
+    `bands ${split.bands.length} waits median ${middle(split.bands)}ms worst ${worst(split.bands)}ms`
+  );
+}
+
+/**
+ * Waits split by which way the reader was claiming.
+ *
+ * @type {Map<string, { flat: number[], bands: number[] }>}
+ */
+const waitsByMode = 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`
+  );
+}
+
+function noteSupplyWait(key, label, waitedMs) {
+  const history = supplyWaits.get(key) ?? [];
+  history.push({ waitedMs, at: Date.now() });
+  while (history.length > SUPPLY_WAIT_HISTORY) {
+    history.shift();
+  }
+  supplyWaits.set(key, history);
+
+  const now = Date.now();
+  if (now - (supplyReportedAt.get(key) ?? 0) < SUPPLY_REPORT_INTERVAL_MS) {
+    return;
+  }
+  const demand = requiredSpeedFrom(history);
+  if (!demand) {
+    return;
+  }
+  supplyReportedAt.set(key, now);
+  const buffer = minimumBufferFrom({
+    segmentSeconds: SEGMENT_SECONDS_FOR_BUFFER,
+    worstSupplyWaitSec: demand.worstWaitSec
+  });
+  logger.info(
+    `supply "${label.slice(0, 40)}": a step must run at ${demand.requiredSpeed.toFixed(2)}x ` +
+    `to survive this swarm (worst wait ${demand.worstWaitSec.toFixed(2)}s, one every ` +
+    `${demand.medianIntervalSec.toFixed(2)}s, ${demand.samples} measured) — ` +
+    `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.
+    (describeReadModes(key) ? ` — ${describeReadModes(key)}` : "")
+  );
+}
+
+/**
+ * The segment length the buffer figure is stated against. The reader does not
+ * know the session's own, and this is a REPORT rather than a decision — the
+ * decision, when it is made, will use the session's real one.
+ */
+const SEGMENT_SECONDS_FOR_BUFFER = 4;
+
+export async function* readFragments({
+  torrent,
+  fileIndex,
+  start,
+  end,
+  cancellation,
+  windowBytes = READ_WINDOW_BYTES
+}) {
+  const store = findSharedStore(torrent);
+  if (!store) {
+    throw new Error("This torrent is not backed by a shared piece store.");
+  }
+
+  const file = torrent.files?.[fileIndex];
+  if (!file) {
+    throw new Error(`File ${fileIndex} not found.`);
+  }
+
+  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));
+  /**
+   * How this reader claims what it wants: `flat` is one band of equal urgency,
+   * which is what every release before this did; `bands` puts the pieces the
+   * viewer is about to reach above the fill behind them, anchored at the first
+   * piece not already held.
+   *
+   * Alternated per read unless the deployment names one, so the comparison
+   * accumulates from real viewing instead of from a synthetic swarm — three
+   * such experiments in one day measured regimes the levers were not for and
+   * cost more than they settled.
+   *
+   * @type {"flat" | "bands"}
+   */
+  const readMode = READ_MODE_SETTING === "flat" || READ_MODE_SETTING === "bands"
+    ? READ_MODE_SETTING
+    : (Math.random() < 0.5 ? "flat" : "bands");
+  // 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 criticalMark = null;
+  /**
+   * 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;
+
+  /**
+   * The bands currently claimed from the swarm, most urgent first.
+   *
+   * @type {Array<{ from: number, to: number, priority: number }>}
+   */
+  let claimed = [];
+  /**
+   * What the consumer is taking from this read, in bytes a second, measured as
+   * it goes. For a viewer that is the film's own byte rate, which is exactly the
+   * quantity the band widths are derived against — and measuring it here needs
+   * nothing passed in and no assumption about who is reading.
+   */
+  let deliveredBytes = 0;
+  const readStartedAt = Date.now();
+  const consumeBytesPerSec = () => {
+    const seconds = (Date.now() - readStartedAt) / 1000;
+    return seconds > 0 ? deliveredBytes / seconds : 0;
+  };
+
+  /**
+   * Where the reader's own claim starts in `bands` mode: 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;
+  };
+
+
+  /**
+   * The widths behind the bands currently claimed, for the log to state.
+   *
+   * @type {{ near: number, far: number, measured: boolean }}
+   */
+  let lastWidths = { near: basePieces, far: basePieces, measured: false };
+
+  const bandWidths = () => {
+    const figures = supplyFiguresFor(torrent?.infoHash ?? "?", file?.name ?? "", SEGMENT_SECONDS_FOR_BUFFER);
+    lastWidths = bandWidthsFrom({
+      worstWaitSec: figures?.worstWaitSec ?? null,
+      medianIntervalSec: figures?.medianIntervalSec ?? null,
+      downloadBytesPerSec: Number(torrent?.downloadSpeed) || 0,
+      consumeBytesPerSec: consumeBytesPerSec(),
+      pieceLength,
+      basePieces
+    });
+    return lastWidths;
+  };
+
+  const moveWindowTo = (pieceIndex) => {
+    const anchor = readMode === "bands" ? firstMissingFrom(pieceIndex) : pieceIndex;
+    const next = readWindowFor({ pieceIndex: anchor, lastPiece, windowPieces });
+    const sameUrgent = window && window.from === next.from && window.to === next.to;
+    if (sameUrgent && readMode === "flat") {
+      return;
+    }
+    const isJump = !window || next.from > window.to || next.from < window.from;
+    // A seek makes every width behind the urgent band meaningless: they were
+    // grown against a position the viewer has left, and what lies beyond the
+    // new one has to be earned from a standing start.
+    const wanted = readMode === "bands"
+      ? bandsFrom({
+        urgent: next,
+        pieceIndex,
+        firstPiece,
+        lastPiece,
+        widths: bandWidths()
+      })
+      : [{ ...next, priority: BAND_PRIORITIES[0] }];
+    if (sameUrgent && sameBands(claimed, wanted)) {
+      return;
+    }
+    for (const band of claimed) {
+      releaseWindow(torrent, band);
+    }
+    for (const band of wanted) {
+      claimWindow(torrent, band, band.priority);
+    }
+    claimed = wanted;
+    window = next;
+    // Tell the store these pieces are wanted, so it evicts something else.
+    // Without it the piece the decoder reads next looks exactly as stale as one
+    // the encoder fetched forty minutes ahead, and the second kind is what
+    // fills the store while the encoder runs ahead of the viewer.
+    store.protectRange?.(readerId, next.from, next.to);
+    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}"`
+        );
+      }
+    }
+  };
+
+  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.
+        criticalMark = markCritical(torrent, pieceIndex, window.to, criticalMark);
+      }
+
+      const waitStartedAt = Date.now();
+      // 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);
+            // Nothing could be placed the ordinary way, which means every block
+            // is spoken for. That is exactly when a second copy of the last
+            // blocks is worth asking for.
+            duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
+          }
+          pushed = {
+            asked: pushed.asked + result.asked,
+            // 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}`);
+        }
+      };
+      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);
+      try {
+        await whenPieceReady(torrent, pieceIndex, cancellation);
+      } finally {
+        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;
+      // 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);
+        noteReadMode(supplyKey, waitedMs, readMode);
+        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));
+        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; ` +
+            (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)` +
+            (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` : "") +
+            // Which way the reader was claiming while this wait happened, and
+            // the bands themselves. Without it a number in the log belongs to
+            // neither arm and the comparison cannot be made afterwards.
+            `; mode=${readMode}` +
+            (readMode === "bands"
+              ? ` ${claimed.map((band) => `p${band.priority}:${band.from}-${band.to}`).join(" ")}` +
+                (lastWidths.measured
+                  ? ` (near ${lastWidths.near} far ${lastWidths.far} pieces, from the measured wait and surplus)`
+                  : " (widths not measured yet)")
+              : "")
+        );
+      }
+
+      // 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);
+        throw new Error(`Piece ${pieceIndex} is verified but absent from the store.`);
+      }
+
+      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,
+        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;
+    }
+    // Reached on completion, on cancellation, on a throw, and when the consumer
+    // stops iterating — a window left behind would keep the swarm fetching for
+    // a reader that no longer exists.
+    // Reached on completion, on cancellation, on a throw, and when the consumer
+    // stops iterating — a band left behind would keep the swarm fetching for a
+    // reader that no longer exists.
+    for (const band of claimed) {
+      releaseWindow(torrent, band);
+    }
+    store.releaseProtection?.(readerId);
+    if (criticalMark) {
+      clearCritical(torrent, criticalMark);
+    }
+  }
+}