@torrent-tv/proxy 2.80.0 → 2.80.2

package/package.json

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

package/server.js

@@ -172,6 +172,22 @@ export async function startProxyServer({
       }
       return torrentPool.getTorrentTotals();
     },
+    // The priority map, on its way to the downloading. It lives in another
+    // thread, so the map crosses the worker channel; what it does with it —
+    // seconds into bytes, what to ask the swarm for, what to keep in memory —
+    // is its own business.
+    setPriorityMap: async ({ sourceKey, fileIndex, durationSeconds, zones }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return;
+      }
+      try {
+        await torrentPool.setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones });
+      } catch {
+        // Best effort: the map is republished on the next change, and the
+        // downloading goes on serving reads meanwhile.
+      }
+    },
     getSourceStats: async (sourceKey, fileIndex) => {
       const record = sourceRegistry.get(sourceKey);
       if (!record) {

package/services/demand/DemandRegister.js

@@ -84,6 +84,26 @@ export class DemandRegister {
     return this.windows().filter((window) => window.urgency === urgency);
   }
 
+  /**
+   * How urgently one byte of one file is wanted, by whoever wants it most.
+   *
+   * The priority map states its zones here like anybody else, so this answers
+   * for a byte nobody is reading yet: it is how a wait is attributed to a level
+   * without the reader keeping a forecast of its own.
+   *
+   * @param {number} fileIndex
+   * @param {number} byteOffset
+   * @returns {number | null} Null when nothing covers that byte.
+   */
+  urgencyAt(fileIndex, byteOffset) {
+    // `windows()` is sorted most urgent first, so the first cover is the answer.
+    const found = this.windows().find((window) =>
+      window.fileIndex === fileIndex &&
+      byteOffset >= window.byteStart &&
+      byteOffset <= window.byteEnd);
+    return found ? found.urgency : null;
+  }
+
   /**
    * The union of what is wanted of one file at one level, in byte ranges.
    *

package/services/download/SwarmSelection.js

@@ -224,7 +224,10 @@ export class SwarmSelection {
         if (!range) {
           continue;
         }
-        store.protectRange(window.claimant, range.from, range.to);
+        // The level goes with the range: it is what eviction compares when
+        // everything resident is wanted by somebody, and dropping it here is
+        // what left the store choosing by recency alone.
+        store.protectRange(window.claimant, range.from, range.to, window.urgency);
         holding.add(window.claimant);
       }
     }

package/services/encode/EncodePlan.js

@@ -232,37 +232,51 @@ export function planEncoders({
   //    lowest number, because that is where a viewer is stopped. The budget
   //    rarely stretches to every gap, so which one is taken first is the whole
   //    of what a viewer's presence decides.
-  const gapsWanted = [];
-  for (const span of [...wanted].sort(
-    (left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.from - right.from
-  )) {
-    const gap = coverage.firstGapFrom(span.from, span.to);
-    if (gap !== null) {
-      gapsWanted.push(gap);
-    }
-  }
-  const alreadyPlanned = new Set(moves.map((action) => /** @type {{from:number}} */ (action).from));
-  const budget = Math.max(0, maxRuns - surviving.size);
-  for (const gap of [...new Set(gapsWanted)]) {
-    if (starts.length >= budget) {
-      break;
-    }
-    if (alreadyPlanned.has(gap)) {
-      continue;
-    }
-    const free = coverage.freeRunFrom(gap);
-    if (free === 0) {
-      continue;
-    }
-    alreadyPlanned.add(gap);
-    starts.push({
-      type: "start",
-      from: gap,
-      to: endOfStretch(gap, free),
-      because: `#${gap} is wanted and nobody is making it`
-    });
-  }
-
+  const budget = Math.max(0, maxRuns - surviving.size);
+  const alreadyPlanned = new Set(moves.map((action) => /** @type {{from:number}} */ (action).from));
+  for (const from of placeEncoders({
+    coverage,
+    windows: wanted,
+    howMany: budget,
+    speedX: live.reduce((best, run) => Math.max(best, run.speedX || 0), 0)
+  })) {
+    if (alreadyPlanned.has(from)) {
+      continue;
+    }
+    alreadyPlanned.add(from);
+    starts.push({
+      type: "start",
+      from,
+      to: endOfStretch(from, coverage.freeRunFrom(from)),
+      because: `#${from} is wanted and nobody is making it`
+    });
+  }
+
+  // ONE ENCODER'S WORK ENDS WHERE THE NEXT ONE'S BEGINS.
+  //
+  // A free stretch may run to the end of the track, and an encoder given all of
+  // it stands in the road of every encoder placed behind it: they write the
+  // same names, and each one's output is the other's "material somebody else
+  // made", so they stop one another. Field 2026-09-05: three encoders started
+  // on one track within 200 ms, each into the road another was already writing.
+  // Fifteen readers on a piece store that holds sixteen pieces followed, half
+  // of all evictions took a piece a reader had declared, and `/stream` began
+  // handing out bytes that were not the file's.
+  //
+  // The bound is taken from the NEXT ENCODER'S START, not from a band edge: a
+  // band edge travels with the viewer, so every step forward would leave a
+  // sliver just past the previous encoder and buy an encoder for it.
+  const placed = [...moves, ...starts].sort(
+    (left, right) => /** @type {any} */ (left).from - /** @type {any} */ (right).from
+  );
+  for (let index = 0; index < placed.length - 1; index += 1) {
+    const here = /** @type {{ from: number, to: number }} */ (placed[index]);
+    const next = /** @type {{ from: number }} */ (placed[index + 1]);
+    if (here.to < 0 || here.to >= next.from) {
+      here.to = next.from - 1;
+    }
+  }
+
   return [...stops, ...moves, ...starts, ...keeps];
 }
 
@@ -307,3 +321,117 @@ export function firstUnmetWant(coverage, windows) {
   }
   return lowest;
 }
+
+/**
+ * Where to put the encoders this machine can afford.
+ *
+ * Two things are wanted of a division of the film, and they are wanted in this
+ * order:
+ *
+ * 1. **the viewer must not stop.** An encoder starting at `q` stays ahead of a
+ *    viewer at `p` while `y / s <= q + y - p`, so it holds `(q - p) * s / (1-s)`
+ *    of film and no more. Beyond that the viewer catches it, and the next
+ *    encoder has to be standing there. That is where the first ones go, and it
+ *    is why the stretches grow: the further off one starts, the later the
+ *    viewer arrives and the longer it may work;
+ * 2. **the film should be finished as soon as possible.** Once the viewer is
+ *    safe, whatever is left is divided EQUALLY between the encoders that
+ *    remain: equal shares finish together, and any other division finishes when
+ *    its longest share does. That is what makes seeking cheap — the film exists.
+ *
+ * At or above realtime the first requirement is met by one encoder for the
+ * whole film, and every other encoder goes to the second — which is the common
+ * case on a copied picture, and is why "one viewer, one encoder" was never the
+ * rule.
+ *
+ * @param {object} params
+ * @param {import("./CoverageMap.js").CoverageMap} params.coverage
+ * @param {WantedSpan[]} params.windows - The merged map, in this output's own
+ *   numbering. Its highest-numbered band starts where the viewer is.
+ * @param {number} params.howMany - What the machine affords.
+ * @param {number} params.speedX - Measured. Zero when nothing has measured it,
+ *   and then only the first requirement can be served.
+ * @returns {number[]} Where to start each encoder, ascending.
+ */
+export function placeEncoders({ coverage, windows, howMany, speedX }) {
+  if (!(howMany > 0) || windows.length === 0) {
+    return [];
+  }
+  const byUrgency = [...windows].sort(
+    (left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.from - right.from
+  );
+  const viewer = byUrgency[0].from;
+  const lastWanted = Math.max(...windows.map((span) => span.to));
+
+  /** @type {number[]} */
+  const places = [];
+  const take = (at) => {
+    const gap = coverage.firstGapFrom(at, lastWanted);
+    if (gap !== null && !places.includes(gap)) {
+      places.push(gap);
+    }
+    return gap;
+  };
+
+  // The first one goes where somebody is stopped.
+  let previous = take(viewer);
+  if (previous === null) {
+    // Nothing ahead is missing. Whatever is left anywhere is divided equally.
+    return divideEqually(coverage, byUrgency, howMany, places);
+  }
+
+  const growth = speedX > 0 && speedX < 1 ? speedX / (1 - speedX) : Number.POSITIVE_INFINITY;
+  while (places.length < howMany) {
+    const holds = (previous - viewer) * growth;
+    if (!Number.isFinite(holds) || previous + holds > lastWanted) {
+      // Either it keeps ahead for the rest of the film, or its guarantee runs
+      // past the end of what anybody wants. Nobody is in danger further on, so
+      // the encoders left over go to finishing the film sooner.
+      break;
+    }
+    const next = take(Math.ceil(previous + Math.max(1, holds)));
+    if (next === null || next <= previous) {
+      break;
+    }
+    previous = next;
+  }
+  return divideEqually(coverage, byUrgency, howMany, places);
+}
+
+/**
+ * Spread whatever encoders are left over the film that is still missing.
+ *
+ * Equal shares, because equal shares finish together: any other division is
+ * finished when its longest share is, which is later.
+ *
+ * @param {import("./CoverageMap.js").CoverageMap} coverage
+ * @param {WantedSpan[]} byUrgency
+ * @param {number} howMany
+ * @param {number[]} places
+ * @returns {number[]}
+ */
+function divideEqually(coverage, byUrgency, howMany, places) {
+  for (const span of byUrgency) {
+    if (places.length >= howMany) {
+      break;
+    }
+    const gap = coverage.firstGapFrom(span.from, span.to);
+    if (gap === null) {
+      continue;
+    }
+    // Where this band's missing film would be cut if the encoders left over
+    // shared it. One share per encoder, and the first share is the gap itself.
+    const left = howMany - places.length;
+    const width = Math.max(1, Math.floor((span.to - gap + 1) / left));
+    for (let at = gap; at <= span.to && places.length < howMany; at += width) {
+      const found = coverage.firstGapFrom(at, span.to);
+      if (found === null) {
+        break;
+      }
+      if (!places.includes(found)) {
+        places.push(found);
+      }
+    }
+  }
+  return [...places].sort((left, right) => left - right);
+}

package/services/encode/SegmentStore.js

@@ -258,6 +258,35 @@ export class SegmentStore {
     return proven.sort((left, right) => left - right);
   }
 
+  /**
+   * A run is about to write these numbers again: forget that they were closed.
+   *
+   * A number closed once is not closed for ever. An encoder started at #N
+   * rewrites #N and everything after it, and while it is doing so the file
+   * under that name is half a segment — but the store remembered the earlier
+   * closing and would call it whole. Field 2026-09-05: seventeen runs were
+   * stopped and none ended normally, so numbers were being rewritten
+   * constantly, and the player met a fatal append error it never recovered
+   * from — an empty picture for the six minutes that followed.
+   *
+   * @param {string} key
+   * @param {number} from
+   */
+  forgetClosedFrom(key, from) {
+    const known = this.#closed.get(key);
+    if (!known || !Number.isInteger(from)) {
+      return;
+    }
+    for (const index of known) {
+      if (index >= from) {
+        known.delete(index);
+      }
+    }
+    // What the directory says has to be read again too: the successor rule
+    // would otherwise prove the rewritten piece from a file made before it.
+    this.#held.delete(key);
+  }
+
   /**
    * Whether this piece is finished, and may therefore be served.
    *

package/services/encode/run-budget.js

@@ -24,6 +24,14 @@
  *
  * Which of them bound the answer is returned beside it, because "why is there
  * only one encoder" is otherwise a question no log can answer.
+ *
+ * **Only the first is supplied today.** The two readings the others need are
+ * both in the torrent thread — what the swarm delivers against the film's own
+ * byte rate, and the store's allowance against what one reader keeps — and
+ * carrying them across is its own piece of work, deliberately not done here.
+ * Until it is, the swarm and the memory terms are inert: this returns what the
+ * processor allows, and says so. Stated rather than left to be discovered from
+ * a parameter nobody passes.
  */
 
 /**

package/services/hls-session-manager.js

@@ -24,6 +24,7 @@ import { availableShareFrom } from "./available-share.js";
 import { contentionPenalty } from "./contention.js";
 import { minimumBufferFrom } from "./supply-margin.js";
 import { mapForViewer } from "./priority/PriorityMap.js";
+import { PriorityOrchestrator } from "./priority/PriorityOrchestrator.js";
 import { baseDrawFrom, costPerMegabyteFrom } from "./torrent-cost.js";
 import { medianOf, movedBeyondScatter, scatterOf } from "./learned-median.js";
 import {
@@ -1522,6 +1523,7 @@ export class HlsSessionManager {
     softwarePresetBenchmark = null,
     decodeCostModel = null,
     getSourceStats = null,
+    setPriorityMap = null,
     // What a second job costs on this host, measured at startup. Null when it
     // could not be measured, and then nothing is corrected — the alternative
     // is inventing a penalty, which is the same fault as inventing a fill rate.
@@ -1578,6 +1580,7 @@ export class HlsSessionManager {
     // realtime budget to tell a CPU limit from a download-starved input:
     // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
     this.getSourceStats = typeof getSourceStats === "function" ? getSourceStats : null;
+    this.setPriorityMap = typeof setPriorityMap === "function" ? setPriorityMap : null;
     this.contentionPenalties = contentionPenalties instanceof Map ? contentionPenalties : null;
     // Totals across every torrent this proxy holds, used to price what the
     // torrent itself costs the machine (item 7). Optional: a proxy wired
@@ -1669,6 +1672,21 @@ export class HlsSessionManager {
       encodersRunningNow: () => this.#encodersRunningNow(),
       torrentCostSecFor: (session) => this.#torrentCostSecFor(session)
     });
+    // The priority map, built from where the viewers are and handed to both
+    // sides that act on it. The downloading lives in another thread, so its
+    // copy travels over the worker channel.
+    this.priority = new PriorityOrchestrator({
+      publish: ({ sourceKey, fileIndex, durationSeconds, zones }) => {
+        void Promise.resolve(
+          this.setPriorityMap?.({ sourceKey, fileIndex, durationSeconds, zones })
+        ).catch(() => {});
+      },
+      viewersOf: (session) => viewersOf(session),
+      allowanceFor: (session) => minimumBufferFrom({
+        segmentSeconds: this.segmentDurationSec,
+        worstSupplyWaitSec: session.supplyFigures?.worstWaitSec
+      })?.seconds ?? this.segmentDurationSec
+    });
     this.encodeOrchestrator = new EncodeOrchestrator({
       maxRunsFor: (address) => this.maxRunsForOutput(address),
       makeRun: ({ address, from, to }) => this.#makeRunAt(address, from, to),
@@ -3710,7 +3728,7 @@ export class HlsSessionManager {
    * @returns {{from: number, to: number, priority: number}[]} In segment
    *   numbers, both ends inclusive.
    */
-  #demandZonesFor(session, atSeconds) {
+  #demandZonesFor(session, atSeconds, playing = true) {
     const boundaries = session.timeline?.boundaries ?? [];
     const segmentCount = Number(session.timeline?.segmentCount) || 0;
     // Where they are, in this output's own numbering. The viewer holds seconds;
@@ -3731,12 +3749,7 @@ export class HlsSessionManager {
         segmentSeconds: this.segmentDurationSec,
         worstSupplyWaitSec: session.supplyFigures?.worstWaitSec
       })?.seconds ?? this.segmentDurationSec,
-      // The slope between two progress reports, which is what this class
-      // measures everywhere else it prices an encode. `progress.speed` is
-      // ffmpeg's own cumulative figure and includes the run's start, so it
-      // reads low for the first seconds of every run; `recentSpeed` is the
-      // reading taken over a window and is the one the budget already trusts.
-      encodeSpeedX: Number(session.recentSpeed?.speed) || Number(session.progress?.speed) || 0
+      playing
     });
     /** @type {{from: number, to: number, priority: number}[]} */
     const inSegments = [];
@@ -3943,7 +3956,7 @@ export class HlsSessionManager {
           // consulted: the 120 seconds that used to size this window were the
           // suspended encoder's threshold, one chosen number answering seven
           // different questions.
-          for (const zone of this.#demandZonesFor(session, at)) {
+          for (const zone of this.#demandZonesFor(session, at, viewer.playing !== false)) {
             this.encodeOrchestrator.want({
               // The claimant is the PERSON, without the priority in it: their
               // zones are separate windows, but they leave together, and
@@ -3958,6 +3971,10 @@ export class HlsSessionManager {
         }
       }
     }
+    this.priority.publishFor({
+      sessionGroups: byOutput.values(),
+      staleAfterMs: this.presenceStaleAfterMs()
+    });
     this.encodeOrchestrator.reconcile();
   }
 

package/services/orchestrators/EncodeOrchestrator.js

@@ -27,6 +27,7 @@ import { CoverageMap } from "../encode/CoverageMap.js";
 import { firstUnmetWant, planEncoders } from "../encode/EncodePlan.js";
 import { endOfRun } from "../encode/EncodeRun.js";
 import { ENCODE_EXIT } from "../encode/encode-exit.js";
+import { mergeMaps } from "../priority/PriorityMap.js";
 import { affordableRuns } from "../encode/run-budget.js";
 import { RunCosts } from "../encode/run-costs.js";
 import { SegmentDemand } from "../encode/SegmentDemand.js";
@@ -244,11 +245,28 @@ export class EncodeOrchestrator {
     // order: what a viewer must have before they set off comes before what is
     // merely in front of them, which comes before the rest of the track. Passed
     // as a plain number so the plan stays arithmetic.
-    const windows = this.demand.windowsOn(address).map((window) => ({
-      from: window.from,
-      to: window.to,
-      priority: Number(window.priority) || 0
-    }));
+    // ONE MAP, NOT ONE WINDOW PER VIEWER PER ZONE.
+    //
+    // Two viewers a few seconds apart state stretches that overlap, and the
+    // plan puts one encoder on each stretch it is given — so unmerged windows
+    // buy an encoder per viewer for film they both want, which is the opposite
+    // of what sharing the output is for. Merged, the highest number per segment
+    // wins and the stretches do not overlap, so one encoder serves everyone
+    // standing in front of it.
+    const windows = mergeMaps([
+      this.demand.windowsOn(address).map((window) => ({
+        from: window.from,
+        // Half-open on the way in and back again: these are whole segment
+        // numbers, and #10..#20 next to #21..#30 must not be read as touching
+        // at 20 and 21 at once.
+        to: window.to + 1,
+        // A window stated without a number is still a want — one
+        // undifferentiated want, which is what a caller that knows only a
+        // position states. Zero would read as "nothing wanted here" and the
+        // merge would drop it.
+        priority: Number(window.priority) || 1
+      }))
+    ]).map((zone) => ({ from: zone.from, to: zone.to - 1, priority: zone.priority }));
     const live = this.runsOn(address).filter((run) => run.isAlive);
     const actions = planEncoders({
       coverage,
@@ -325,6 +343,10 @@ export class EncodeOrchestrator {
     const onThisOutput = this.#runs.get(address) ?? [];
     onThisOutput.push(run);
     this.#runs.set(address, onThisOutput);
+    // This run rewrites everything from here on, so what was closed from here
+    // on is no longer closed. Without this a number closed by an earlier run
+    // stays servable while a later one is halfway through writing it again.
+    this.segmentStore?.forgetClosedFrom(address, from);
     this.coverageOf(address).claim(run, from, endOfRun({ from, to }));
     run.start(because);
   }

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

@@ -3,7 +3,14 @@
  *
  * Two responsibilities, deliberately kept apart from any storage:
  *
- *  - **recency**, so the piece evicted is the one least likely to be wanted;
+ *  - **how much a piece is wanted**, so the piece evicted is the one wanted
+ *    least. That number comes from the priority map, which is the one place
+ *    that knows where the viewers are; recency only separates pieces the map
+ *    wants equally. Recency alone cannot answer it: a reader walking a film
+ *    touches each piece once, so the piece the decoder will want in two seconds
+ *    looks exactly as stale as one fetched forty minutes ago and never read
+ *    again — and with the encoder running ahead of the viewer, the second kind
+ *    is what fills the store;
  *  - **pinning**, so a piece being read cannot be evicted at all.
  *
  * The second is not a refinement of the first. webtor's seeder relies on recency
@@ -28,18 +35,16 @@ export class PieceLru {
   /** Piece index → number of readers currently holding it. */
   #pins = new Map();
   /**
-   * Reader id → the piece range it expects to read next.
+   * Claimant → the piece range it states, and how much it wants it.
    *
-   * Recency alone does not describe this. A reader walking a film touches its
-   * pieces once, so the piece the decoder will want in two seconds looks
-   * exactly as stale as one fetched forty minutes ago and never read again —
-   * and with the encoder running ahead of the viewer, the second kind is what
-   * fills the store. Measured 2026-08-04: the hit rate fell from 100% to 45.7%
-   * with 221 pieces read back from disk in one session.
+   * The ranges are the priority map's zones, stated by whoever holds the map,
+   * plus the piece a read is stopped on. The number is the map's own: lower is
+   * more urgent, and a piece no range covers is wanted by nobody at all.
    *
    * A preference, not a pin. At the smallest budget the store guarantees only
-   * two resident pieces, so a hard hold on a window would deadlock it; when
-   * nothing unprotected is left, protection is ignored rather than obeyed.
+   * two resident pieces, so a hard hold on a zone would deadlock it; when
+   * everything resident is wanted, the least wanted of them goes rather than
+   * nothing going at all.
    */
   #protected = new Map();
   #capacity;
@@ -164,8 +169,8 @@ export class PieceLru {
   }
 
   /**
-   * The least recently used piece that is free to go, or `null` when every
-   * resident piece is pinned.
+   * The least wanted piece that is free to go, or `null` when every resident
+   * piece is pinned.
    *
    * Returning `null` rather than evicting a pinned piece is the whole point:
    * the caller must then wait or fail, never take memory out from under a
@@ -194,22 +199,63 @@ export class PieceLru {
    *   victim is inside one, and -1 when no reader has declared anything.
    */
   evictionChoice() {
-    // First choice: the least recently used piece nobody is reading and nobody
-    // is about to read.
+    /** @type {{ index: number, want: number } | null} */
+    let victim = null;
+    // `#order` runs least-recently-used first, so among pieces the map wants
+    // equally the first one seen is the stalest — recency decides the tie and
+    // nothing else. A piece no zone covers is wanted by nobody, which is the
+    // most anything can be un-wanted, so the walk stops at the first of those:
+    // that is the ordinary case and it costs one step.
     for (const index of this.#order) {
-      if (!this.#pins.has(index) && !this.#isProtected(index)) {
-        return { index, protectionYielded: false, distance: this.#distanceToWindow(index) };
+      if (this.#pins.has(index)) {
+        continue;
+      }
+      const want = this.wantAt(index);
+      if (victim === null || want > victim.want) {
+        victim = { index, want };
+        if (want === Number.POSITIVE_INFINITY) {
+          break;
+        }
       }
     }
-    // Nothing spare left. Protection yields — it is a preference, and refusing
-    // here would leave the store unable to admit anything at all. Pins do not
-    // yield: a piece being read now cannot have its memory taken away.
-    for (const index of this.#order) {
-      if (!this.#pins.has(index)) {
-        return { index, protectionYielded: true, distance: this.#distanceToWindow(index) };
+    if (victim === null) {
+      // Every resident piece is being read. The caller must wait or fail; it
+      // may never take memory out from under a reader.
+      return { index: null, protectionYielded: false, distance: -1 };
+    }
+    return {
+      index: victim.index,
+      // The map wanted this piece and it is going anyway — the store is being
+      // asked to hold more than it has room for, and this piece comes back
+      // from disk. Reported so that thrashing is visible as thrashing rather
+      // than as ordinary work: 6565 spills and 7575 revivals in 44 minutes on
+      // 2026-09-02, with only 53.6 % of reads served from memory.
+      protectionYielded: victim.want !== Number.POSITIVE_INFINITY,
+      distance: this.#distanceToWindow(victim.index)
+    };
+  }
+
+  /**
+   * How much the priority map wants this piece, by the most urgent zone that
+   * covers it.
+   *
+   * Public because admission asks it too: whether an arriving piece displaces
+   * a resident one is the same comparison as which resident one goes, and
+   * answering them from two different quantities is how a store evicts what it
+   * has just decided to keep.
+   *
+   * @param {number} index
+   * @returns {number} Lower is more urgent. Infinity when no zone covers it,
+   *   so a piece nobody asked for compares as less wanted than any zone.
+   */
+  wantAt(index) {
+    let want = Number.POSITIVE_INFINITY;
+    for (const range of this.#protected.values()) {
+      if (index >= range.from && index <= range.to && range.urgency < want) {
+        want = range.urgency;
       }
     }
-    return { index: null, protectionYielded: false, distance: -1 };
+    return want;
   }
 
   /**
@@ -279,14 +325,20 @@ export class PieceLru {
   }
 
   /**
-   * The piece that would be evicted next, and how long it will be waited for.
+   * The piece that would be evicted next, how much the map wants it, and how
+   * long it will be waited for.
+   *
+   * Both numbers, because that is the order admission compares them in: the
+   * map's level first, and the distance only between pieces the map wants
+   * equally.
    *
-   * @returns {{ index: number | null, wait: number }}
+   * @returns {{ index: number | null, want: number, wait: number }}
    */
   nextVictim() {
     const choice = this.evictionChoice();
     return {
       index: choice.index,
+      want: choice.index === null ? Number.POSITIVE_INFINITY : this.wantAt(choice.index),
       wait: choice.index === null ? -1 : this.waitFor(choice.index)
     };
   }
@@ -342,20 +394,28 @@ export class PieceLru {
   }
 
   /**
-   * Declare the pieces a reader expects to need next, replacing whatever it
-   * declared before. Ranges from different readers add up.
+   * State a range of pieces and how much they are wanted, replacing whatever
+   * that claimant stated before. Ranges from different claimants add up.
    *
-   * @param {string|number} readerId - Identity of the reader, so its own range
-   *   is replaced rather than accumulated.
+   * @param {string|number} readerId - Identity of the claimant, so its own
+   *   range is replaced rather than accumulated.
    * @param {number} from - First piece, inclusive.
    * @param {number} to - Last piece, inclusive.
+   * @param {number} [urgency] - The priority map's own number, lower being more
+   *   urgent. A caller that states none is treated as wanting these pieces
+   *   least of everyone who did state one, so an unstated range can never
+   *   displace a stated one.
    * @returns {void}
    */
-  protect(readerId, from, to) {
+  protect(readerId, from, to, urgency) {
     if (!Number.isInteger(from) || !Number.isInteger(to) || to < from) {
       return;
     }
-    this.#protected.set(readerId, { from, to });
+    this.#protected.set(readerId, {
+      from,
+      to,
+      urgency: Number.isFinite(urgency) ? Number(urgency) : Number.MAX_SAFE_INTEGER
+    });
   }
 
   /**