@torrent-tv/proxy 2.70.0 → 2.71.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2.71.0
+
+- **Fix**: The torrent thread's log lines never reached the log file. A worker thread loads its own instance of every module, so the logger's file handle — set once, on the main thread — was null there for the life of the process. Measured over a whole 49 938-line file: zero lines from the piece reader and zero from the torrent pool, against 52 and 36 of them in the container's output, which every release destroys. That is why the comparison of the two claim strategies could never be read: it was being printed into a place we wipe ourselves. The worker now sends its lines to the main thread, which is the only writer — two threads appending to one file would race on the rotation and could interleave mid-line.
+- **New**: `services/demand/` — what anybody wants, stated once and in BYTES. `Window` (claimant, file, byte range, urgency), `Urgency`, `DemandRegister` (live windows by claimant), and `pieces.js`, the one place bytes become piece numbers. Nothing in it knows about WebTorrent, the piece store or pieces. The rounding it removes is where a real failure lived: with 16 MiB pieces a 64 MB allowance is four places while two readers asking for 96 MB each want six, and both figures had already been floored before anything could notice.
+- **New**: `services/download/SwarmSelection.js` is the only thing in the proxy that calls `select`, `deselect` or `critical`. There were four callers before and their comments record them fighting: a whole-file read undid a seek that had just happened and the swarm walked forward from the first hole — on a 4.7 GB film, 2.47 GB over 93 s before the segment could be served.
+- **Fix**: Urgency is no longer a number handed to the library, because the library does not keep it. Measured against the vendored 2.8.5: selections are sorted by priority only when one is inserted, and `shufflePriority` then moves the selection just served to the back of the whole non-zero group — so distinct numbers give an order once and a round robin thereafter. Five levels are kept here instead, and a level is stated only while every level above it is satisfied. The library is given the one distinction it honours: non-zero for what is wanted now, zero for the speculative tail.
+- **Fix**: The speculative levels are withdrawn rather than lowered. A peer that cannot help with anything urgent falls through the selection list to whatever is below it, and with a permanently low priority would spend the shared link on pieces nobody is waiting for — about a second of its own throughput at a time. A withdrawn window is not in the download set at all. The condition is global across torrents: two films on one proxy share the link.
+- **Fix**: Nothing is fetched until somebody states a need — the torrent is added with `deselect: true`. WebTorrent's own default is to select the whole torrent, and this proxy used to undo that afterwards by deselecting the files nobody had opened, so on a season pack every episode was fetched for as long as the viewer took to choose one.
+- **Fix**: The background fill is stated per FILE, from the furthest window in that file to that file's end. It used to take the furthest window across all files and the last piece across all files and claim everything between: with two viewers on two episodes of one release, that claimed every episode lying between them.
+- **Chore**: The two claim strategies are one. Each read was assigned at random to a single band or four, and the waits sorted by which; the split halved the sample and the ten-wait threshold was never reached in either arm — nine reads against three on 2026-08-28, and forty waits against one on 2026-08-29, the only day both arms printed. Waits are recorded by the LEVEL the reader was stopped in now, which says whether a band is too narrow rather than whether banding is the wrong idea. `TORRENT_TV_READ_MODE` is gone.
+- **Chore**: `setActiveFile` deleted — no caller anywhere in the repository. `#reassertReaderWindows`, `#updateBackgroundFill`, `#tailAfterWindows` and `#syncSelections` deleted with the mechanisms they patched over; `claimWindow`, `releaseWindow`, `markCritical` and `clearCritical` deleted from the reader.
+- **New**: `askFastestWiresFor` counts the requests refused because every block of the piece was already reserved and displacement did not happen. WebTorrent's displacement thresholds are constants, not settings — the asker must be above 16 KB/s, the holder below 48 KB/s and twice as slow — so a holder at 50 KB/s is never displaced however long the piece has been waited for. That counter is what would justify replacing the rule; a zero says the thresholds are not what we are short of.
+- **Chore**: `docs/download-architecture.md`, in the shape of `docs/container-architecture.md`: the two axes, what is not a third, the layers as a diagram, and what was deleted with the reason. 19 checks in `test/demand-register.test.js` and `test/swarm-selection.test.js`.
+
 ## 2.70.0
 
 - **New**: The piece store keeps a pool of memory blocks instead of allocating one per piece. A block is one piece's worth of memory; it is taken from the free list, and put back there when its piece is written out. Field 2026-09-02: 7575 allocations of 4 MiB in 44 minutes, each released only when the collector reached it, which is why the process held 1.86 GB while the store's own accounting said 352 MB. A block goes back for re-use only AFTER the spill write has finished, because that write reads out of it; a block whose piece is re-put while a reader holds it is given up rather than recycled, and a counter says if one ever is not.

package/CLAUDE.md

@@ -25,6 +25,14 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     long-polls while a segment is being produced, returns retryable 503 (never
     202 — hls.js can't consume it).
 - `services/`:
+  - `demand/` — what anybody wants, in BYTES: `Window` (claimant, file, byte
+    range, urgency), `Urgency` (BLOCKED / NEAR / AHEAD / TAIL / BEHIND),
+    `DemandRegister` (live windows by claimant), `pieces.js` (the one place
+    bytes become piece numbers). No WebTorrent, no piece store, no pieces.
+  - `download/` — `SwarmSelection`, the ONLY thing that calls `select`,
+    `deselect` or `critical`, and `registry.js`, which holds one per torrent and
+    owns the cross-torrent rule that withholds the speculative levels while
+    anything urgent is missing anywhere. See `docs/download-architecture.md`.
   - `container/` — domain layer: `Container` (abstract, RFC 9559 / ISO 14496-12),
     `MatroskaContainer` / `Mp4Container` / `AviContainer`, `ContainerFactory`
     (sniff 16 bytes → precise subclass). See `docs/container-architecture.md`.
@@ -42,6 +50,10 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     `routes/*` are now thin HTTP translators.
   - `container-index/` — legacy readers (ebml-reader, matroska/mp4/avi keyframe and
     subtitle tables) — used internally by `container/*`, deprecated as direct import.
+  - `docs/download-architecture.md` — the two axes of downloading: what is
+    wanted (`demand/`) against what the swarm is told (`download/`), why urgency
+    is not a number given to the library, and why the speculative levels are
+    withdrawn rather than lowered.
   - `docs/logs.md` — where to find logs (HA `docker logs` + `/data/proxy.log`, DO
     `infra-server-1` with forwarded frontend `POST /api/client-logs`). Browser
     console not needed.

package/docs/download-architecture.md

@@ -0,0 +1,175 @@
+# Download architecture — what is wanted, and what the swarm is told
+
+Two questions, kept apart, and neither of them is "which file".
+
+## Two axes, and what is NOT a third
+
+**What somebody needs** — a claimant, a file, a byte range, a level of urgency.
+Stated in `services/demand/`. Knows nothing about WebTorrent, nothing about
+pieces, nothing about the piece store: it is numbers and rules, and it is
+testable without a torrent.
+
+**What the swarm is told** — one class, `services/download/SwarmSelection.js`,
+which reads the register and calls `select`, `deselect` and `critical`. It is
+the only thing in this proxy that calls them.
+
+"Which file" is not a third axis. A file nobody has stated a need for is simply
+absent from the register, and a torrent is added with `deselect: true` so
+nothing is fetched until something is stated. Before 2026-09-02 the library's
+own default selected the whole torrent and this proxy undid that afterwards by
+deselecting the files nobody had opened — so on a season pack every episode was
+being fetched for as long as the viewer took to choose one.
+
+## Layers
+
+```mermaid
+flowchart TB
+  subgraph Statements["services/demand — what is wanted"]
+    W[Window<br/>claimant, file, bytes, urgency]
+    U[Urgency<br/>BLOCKED NEAR AHEAD TAIL BEHIND]
+    R[DemandRegister<br/>live windows by claimant]
+    P[pieces.js<br/>the one bytes to pieces conversion]
+  end
+
+  subgraph Swarm["services/download — what the swarm is told"]
+    S[SwarmSelection<br/>select / deselect / critical]
+    G[registry<br/>one per torrent + the cross-torrent rule]
+  end
+
+  subgraph Claimants["who states needs"]
+    PR[piece-reader<br/>four bands per read]
+    BF[torrent-pool<br/>background fill, per file]
+  end
+
+  PR -->|state / withdraw| R
+  BF -->|state / withdraw| R
+  W --> R
+  U --> R
+  R --> S
+  P --> S
+  G --> S
+  S -->|the only caller| WT[(WebTorrent)]
+```
+
+## The five levels
+
+| level | what it is | stated |
+|---|---|---|
+| `BLOCKED` | the bytes a reader is stopped on | always; may take a block from a slow peer |
+| `NEAR` | the rest of that reader's window | always |
+| `AHEAD` | the lead the encoder will reach | always |
+| `TAIL` | to the end of the file | only while nothing urgent is missing, anywhere |
+| `BEHIND` | the gap left by a forward seek | only while nothing urgent is missing, anywhere |
+
+## Why urgency is not a number handed to the library
+
+Measured against the vendored WebTorrent 2.8.5. Selections are sorted by
+priority **only when one is inserted**:
+
+```js
+this._selections.sort((a, b) => b.priority - a.priority)
+```
+
+and after a wire's pipeline is filled from a selection, that selection is moved
+to the back of the whole non-zero group:
+
+```js
+function shufflePriority (i) {
+  let last = i
+  for (let j = i; j < self._selections.length && self._selections.get(j).priority; j++) last = j
+  self._selections.swap(i, last)
+}
+```
+
+So distinct non-zero numbers give an order once and a round robin thereafter.
+Two things hold: non-zero rotates fairly, zero is always last.
+
+The ordering is therefore kept in `DemandRegister.levelsToState`, by choosing
+what to state at all, and the library is given only the distinction it honours —
+`1` for anything wanted now, `0` for the speculative tail.
+
+The rotation is wanted, not merely tolerated: with two viewers of one film both
+stopped, both needs sit at `BLOCKED` and the swarm alternates between them
+instead of always serving whoever asked first.
+
+## Why the speculative levels are withdrawn rather than lowered
+
+A peer that cannot help with anything urgent — it lacks those pieces, or every
+block of them is reserved by somebody else — falls through the selection list to
+whatever is below. With a permanently low priority it would then spend the
+shared link on pieces nobody is waiting for, about a second of its own
+throughput at a time (`PIPELINE_MAX_DURATION = 1`).
+
+A withdrawn window is not in the download set at all, so there is nothing to
+fall through to.
+
+The condition is **global**, in `services/download/registry.js`, and not per
+torrent: two films on one proxy share the link, so filling the tail of one while
+a viewer of the other has a still picture spends the same bandwidth twice over.
+
+## `select` against `critical` — two different things
+
+`select(from, to, priority)` decides **what is asked for next**: it inserts into
+the sorted selection list the picker walks.
+
+`critical(from, to)` decides **whom it is asked of**. Every block of a piece is
+reserved to exactly one wire; `piece.reserve()` returns `-1` once they all are,
+and a fast idle peer walks past. The flag lets `_hotswap` take a block from the
+slowest holder and give it to the asker:
+
+```js
+if (reservation === -1 && hotswap && self._hotswap(wire, index)) {
+  reservation = piece.reserve()
+}
+```
+
+Its thresholds are constants in the library, not settings: the asker must be
+above 16 KB/s, the holder below 48 KB/s and at least twice as slow. So a holder
+at 50 KB/s is never displaced, however long the piece has been waited for.
+Whether that costs us anything is measured rather than assumed — `askFastestWiresFor`
+counts the requests refused while every block was reserved, and the wait line
+prints it. A number there would justify replacing `_hotswap` on the torrent
+object; a zero says the thresholds are not what we are short of.
+
+## Several viewers
+
+- **Same file.** Each reader is its own claimant. Two stopped viewers put two
+  disjoint ranges at `BLOCKED`, and the library's rotation alternates between
+  them. Two readers wanting the same pieces are merged into one instruction.
+- **Same torrent, different files.** The background fill is stated **per file**,
+  from the furthest window in that file to that file's end. It used to take the
+  furthest window across all files and the last piece across all files and claim
+  everything between — with two viewers on two episodes of one release, that
+  claimed every episode lying between them.
+- **Different torrents.** One register and one selection each, and the
+  speculative condition spans all of them.
+
+## What was deleted, and why
+
+- `claimWindow`, `releaseWindow`, `markCritical`, `clearCritical` in
+  `piece-reader.js` — the reader no longer speaks to the library.
+- `#reassertReaderWindows` in `torrent-pool.js` — it read the piece store's
+  MEMORY claims and rebuilt download claims from them, because WebTorrent
+  deletes a selection once satisfied. `SwarmSelection.reconcile` does that from
+  the register, which is where the statement lives.
+- `#updateBackgroundFill` and `#tailAfterWindows` — replaced by a stated need at
+  the `TAIL` level, per file.
+- `#syncSelections` — obsolete once nothing is selected by default.
+- `setActiveFile` — dead: no caller anywhere in the repository.
+- The two claim strategies and the environment variable that chose between them
+  (`TORRENT_TV_READ_MODE`). Each read was assigned at random to one of them and
+  the waits were sorted by which, and the comparison never decided anything: the
+  split halved the sample, so on 2026-08-28 there were nine reads in one arm and
+  three in the other against a threshold of ten, and on 2026-08-29 the two arms
+  printed together for the first and only time as forty waits against one. Waits
+  are now recorded by the LEVEL the reader was stopped in, which says whether a
+  band is too narrow rather than whether banding is the wrong idea.
+
+## What this does NOT do
+
+The piece store keeps its own list of protected ranges for memory
+(`protectRange` / `protectedRanges`). It is fed by the same readers with the
+same windows, but it is a second list, and one of the two could still drift from
+the other. Making the store read this register instead is the remaining half of
+the deduplication; it was left out of the first release because the memory path
+had just been rewritten and had not yet been seen in the field.

package/docs/logs.md

@@ -7,6 +7,14 @@ All logs are visible via container `docker logs`, no browser console copy-paste
 Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
 
 - Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
+- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
+  A worker thread loads its own instance of every module, so the logger's file
+  handle — set once, on the main thread — was null in the worker for the life of
+  the process. Measured over a whole 49 938-line file: zero lines from the piece
+  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
+  torrent pool, against 52 and 36 of them in `docker logs`, which every release
+  destroys. The worker now sends its lines to the main thread, which is the only
+  writer; a line from there reads `torrent-worker: …`.
 - Via container:
   ```bash
   ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"

package/package.json

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

package/services/demand/DemandRegister.js

@@ -0,0 +1,182 @@
+/**
+ * @file What is wanted from one torrent right now, and by whom.
+ *
+ * **One statement, two consumers.** Until 2026-09-02 the same intent was
+ * written down twice and reconciled by a third piece of code. A reader told the
+ * piece store `protectRange(readerId, from, to)` so its bytes would not be
+ * evicted from memory; it separately told the torrent `select(from, to, 1)` so
+ * they would be fetched; and the pool then read the store's memory claims every
+ * few seconds to rebuild the download claims WebTorrent had dropped once
+ * satisfied. One want, three places, and a sweeper between two of them.
+ *
+ * Here it is stated once. Memory reads this to decide what to keep resident;
+ * the swarm layer reads it to decide what to ask peers for. Neither owns it and
+ * neither can drift from the other.
+ *
+ * Knows nothing about WebTorrent, nothing about the piece store, and nothing
+ * about pieces — so it is testable with numbers alone.
+ */
+
+import { isConditional, Urgency, URGENCY_ORDER } from "./Urgency.js";
+import { unionOf, Window } from "./Window.js";
+
+export class DemandRegister {
+  /** Claimant → the one window it currently states. */
+  #windows = new Map();
+
+  /**
+   * State a need, replacing whatever that claimant said before.
+   *
+   * Replacing rather than adding is the point: a reader walking a film restates
+   * a moving window many times a second, and if those accumulated the download
+   * set would grow to the whole file within a minute.
+   *
+   * @param {object} params
+   * @param {string} params.claimant
+   * @param {number} params.fileIndex
+   * @param {number} params.byteStart
+   * @param {number} params.byteEnd
+   * @param {number} params.urgency
+   * @returns {Window}
+   */
+  state({ claimant, fileIndex, byteStart, byteEnd, urgency }) {
+    const window = new Window({ claimant, fileIndex, byteStart, byteEnd, urgency });
+    this.#windows.set(claimant, window);
+    return window;
+  }
+
+  /**
+   * Withdraw what a claimant said.
+   *
+   * Named by claimant, so a release that arrives twice, or after the claimant
+   * has gone, withdraws nothing rather than somebody else's window. Must be
+   * called from a `finally`: a reader that ends without withdrawing keeps the
+   * swarm fetching for somebody who is no longer there.
+   *
+   * @param {string} claimant
+   * @returns {boolean} Whether there was anything to withdraw.
+   */
+  withdraw(claimant) {
+    return this.#windows.delete(claimant);
+  }
+
+  /** How many claimants are stating something. */
+  get size() {
+    return this.#windows.size;
+  }
+
+  /**
+   * Every stated window, most urgent first.
+   *
+   * @returns {Window[]}
+   */
+  windows() {
+    return [...this.#windows.values()].sort((left, right) => left.urgency - right.urgency);
+  }
+
+  /**
+   * The windows at one level of urgency.
+   *
+   * @param {number} urgency
+   * @returns {Window[]}
+   */
+  at(urgency) {
+    return this.windows().filter((window) => window.urgency === urgency);
+  }
+
+  /**
+   * The union of what is wanted of one file at one level, in byte ranges.
+   *
+   * @param {number} fileIndex
+   * @param {number} urgency
+   * @returns {Array<{ byteStart: number, byteEnd: number }>}
+   */
+  unionFor(fileIndex, urgency) {
+    return unionOf(
+      this.windows().filter((window) => window.fileIndex === fileIndex && window.urgency === urgency)
+    );
+  }
+
+  /**
+   * The union of everything wanted of one file, whatever the urgency.
+   *
+   * This is what memory is sized against: a piece inside any stated window will
+   * be read, and evicting it means fetching it back from disk moments later.
+   *
+   * @param {number} [fileIndex] - Every file when omitted.
+   * @returns {Array<{ byteStart: number, byteEnd: number }>}
+   */
+  union(fileIndex) {
+    const wanted = fileIndex === undefined
+      ? this.windows()
+      : this.windows().filter((window) => window.fileIndex === fileIndex);
+    // Ranges of different files must not be merged: byte 100 of file 0 and byte
+    // 100 of file 1 are different bytes.
+    const byFile = new Map();
+    for (const window of wanted) {
+      const list = byFile.get(window.fileIndex) ?? [];
+      list.push(window);
+      byFile.set(window.fileIndex, list);
+    }
+    return [...byFile.values()].flatMap((list) => unionOf(list));
+  }
+
+  /** Which files anybody is stating a need for. */
+  files() {
+    return [...new Set(this.windows().map((window) => window.fileIndex))].sort((a, b) => a - b);
+  }
+
+  /**
+   * The most urgent level anybody is stating, or null when nothing is stated.
+   *
+   * @returns {number | null}
+   */
+  mostUrgent() {
+    const windows = this.windows();
+    return windows.length === 0 ? null : windows[0].urgency;
+  }
+
+  /**
+   * Which levels should be stated to the swarm, given what is still missing.
+   *
+   * The three urgent levels always. The two speculative ones only while
+   * everything above them is complete — and withdrawn whole the moment one is
+   * not, because a withdrawn window is not in the download set at all and a
+   * peer with nothing urgent to give cannot fall through to it. That is the
+   * difference from a permanently low priority, which is exactly what lets a
+   * peer fall through and spend the shared link on a piece nobody is waiting
+   * for.
+   *
+   * @param {(window: Window) => boolean} isSatisfied - Whether a window has
+   *   everything it asked for. Given from outside because only the torrent
+   *   knows what has arrived.
+   * @param {boolean} [speculativeAllowed] - Whether anything ELSEWHERE is still
+   *   waiting for something urgent. False holds the speculative levels back
+   *   even when this torrent has everything it needs: two films on one proxy
+   *   share the link, so filling the tail of one while a viewer of the other
+   *   has a still picture spends the same bandwidth twice over.
+   * @returns {number[]} Levels to state, most urgent first.
+   */
+  levelsToState(isSatisfied, speculativeAllowed = true) {
+    const stating = [];
+    let everythingAboveIsSatisfied = speculativeAllowed;
+    for (const urgency of URGENCY_ORDER) {
+      if (isConditional(urgency) && !everythingAboveIsSatisfied) {
+        break;
+      }
+      stating.push(urgency);
+      const level = this.at(urgency);
+      if (level.some((window) => !isSatisfied(window))) {
+        everythingAboveIsSatisfied = false;
+      }
+    }
+    return stating;
+  }
+
+  /** Forget everything. The torrent is going. */
+  clear() {
+    this.#windows.clear();
+  }
+}
+
+export { Urgency };

package/services/demand/Urgency.js

@@ -0,0 +1,137 @@
+/**
+ * @file How urgent a stated need is, and what follows from that.
+ *
+ * Five levels, ordered. The ordering is not a set of numbers handed to
+ * WebTorrent — measured 2026-09-02, the library does not keep them. Its picker
+ * sorts selections by priority only at the moment one is inserted, and then, on
+ * every wire it fills, moves the selection it just served to the BACK of the
+ * whole group with a non-zero priority:
+ *
+ * ```js
+ * function shufflePriority (i) {
+ *   let last = i
+ *   for (let j = i; j < self._selections.length && self._selections.get(j).priority; j++) last = j
+ *   self._selections.swap(i, last)
+ * }
+ * ```
+ *
+ * So distinct non-zero numbers give an order once and a round robin thereafter.
+ * Only two things hold: non-zero rotates fairly, zero is always last.
+ *
+ * Therefore urgency here is expressed by WHETHER a need is stated to the swarm
+ * at all. A level is stated only while every level above it is satisfied, and
+ * withdrawn the moment one is not — a withdrawn need is not in the download set
+ * at all, so a peer with nothing urgent to give cannot fall through to it and
+ * spend the shared link on it. A permanently low priority does exactly that,
+ * which is why it is not what this does.
+ *
+ * The rotation is not merely tolerated, it is wanted: with two viewers of one
+ * film both stopped, both their needs sit at {@link Urgency.BLOCKED} and the
+ * swarm alternates between them instead of always serving whoever asked first.
+ */
+
+/**
+ * The levels, most urgent first. The value is the position, so `<` compares
+ * urgency and nothing else may be read into it.
+ *
+ * @enum {number}
+ */
+export const Urgency = {
+  /**
+   * The bytes a reader is stopped on. The picture is not moving until they
+   * arrive.
+   */
+  BLOCKED: 0,
+  /**
+   * The rest of that reader's own window — the cushion being built. Late here
+   * and the picture stops in a few seconds.
+   */
+  NEAR: 1,
+  /**
+   * Further along the file, as far as the encoder will reach. Late here costs
+   * nothing yet.
+   */
+  AHEAD: 2,
+  /**
+   * To the end of the file. Wanted for certain if the viewer watches on, and
+   * not before anything above is satisfied.
+   */
+  TAIL: 3,
+  /**
+   * The gap behind the playhead, left by a forward seek. Wanted only if the
+   * viewer seeks back, so it is last — but it is real: a backward seek into a
+   * hole is the longest wait this proxy produces (field: 93 s).
+   */
+  BEHIND: 4
+};
+
+/** Every level, most urgent first. */
+export const URGENCY_ORDER = [
+  Urgency.BLOCKED,
+  Urgency.NEAR,
+  Urgency.AHEAD,
+  Urgency.TAIL,
+  Urgency.BEHIND
+];
+
+/**
+ * Whether a level may take a block away from a slow peer and give it to a fast
+ * one — WebTorrent's `critical`.
+ *
+ * Only the level that is being waited on. Displacement throws away the part of
+ * the block the slow peer had already fetched, so it buys time exactly where
+ * time is what is short, and wastes bandwidth everywhere else.
+ *
+ * @param {number} urgency
+ * @returns {boolean}
+ */
+export function mayDisplaceSlowPeer(urgency) {
+  return urgency === Urgency.BLOCKED;
+}
+
+/**
+ * Whether a level is stated to the swarm only while the levels above it want
+ * nothing.
+ *
+ * The three urgent levels are always stated: they are what the viewer is
+ * waiting for. The two speculative ones are stated only in the room the urgent
+ * ones leave.
+ *
+ * @param {number} urgency
+ * @returns {boolean}
+ */
+export function isConditional(urgency) {
+  return urgency >= Urgency.TAIL;
+}
+
+/**
+ * The number handed to `torrent.select`.
+ *
+ * Two values only, because two is all the library keeps: everything urgent
+ * shares one non-zero priority and rotates fairly among itself; the
+ * speculative levels take zero, which the library always places last and never
+ * rotates into the group above.
+ *
+ * @param {number} urgency
+ * @returns {number}
+ */
+export function selectionPriority(urgency) {
+  return isConditional(urgency) ? 0 : 1;
+}
+
+/**
+ * A level's name, for the log.
+ *
+ * @param {number} urgency
+ * @returns {string}
+ */
+export function urgencyName(urgency) {
+  switch (urgency) {
+    case Urgency.BLOCKED: return "blocked";
+    case Urgency.NEAR: return "near";
+    case Urgency.AHEAD: return "ahead";
+    case Urgency.TAIL: return "tail";
+    case Urgency.BEHIND: return "behind";
+    default: return `urgency-${urgency}`;
+  }
+}