@torrent-tv/proxy 2.80.8 → 2.80.9

package/services/encode/CoverageMap.js

@@ -1,401 +1,428 @@
-/**
- * @file What has been made of one output, what is being made right now, and by
- * whom.
- *
- * One map per set of output parameters — never per session, never per viewer.
- * Every segment number is in exactly one of three states:
- *
- * 1. **ready** — a file that is closed and can be served to anybody;
- * 2. **being made** — claimed by a named live run, which has been given that
- *    stretch and is working forward through it;
- * 3. **free** — nobody has made it and nobody is making it.
- *
- * Two questions are asked of it constantly and both have to be cheap, because
- * one of them is on the path that answers a viewer:
- *
- * 1. is segment N ready — a set lookup;
- * 2. where is the first gap at or after N — a walk over numbers, never over the
- *    disk. The walk it replaces listed every run directory of a session on the
- *    thread carrying the data channel, 1350 files for a 90-minute film, on
- *    every segment request.
- *
- * **Claims are intervals, not heads.** A run says which stretch it was given,
- * so two runs on one output cannot be sent to the same numbers: the gap finder
- * skips what another run will reach. A run that only announced its current
- * position would leave the question "will anybody make #400" unanswerable
- * without guessing at its speed.
- *
- * **Nothing here touches a disk, a process or a clock**, so every decision it
- * makes can be exercised with numbers alone.
- */
-
-/** @typedef {"ready" | "making" | "free"} SegmentState */
-
-export class CoverageMap {
-  /** Numbers whose file is closed and servable. @type {Set<number>} */
-  #ready = new Set();
-
-  /** Run id → the stretch it was given, both ends inclusive. @type {Map<string, {from: number, to: number}>} */
-  #claims = new Map();
-
-  /** How many segments this output has in total. @type {number} */
-  #segmentCount;
-
-  /**
-   * @param {object} [params]
-   * @param {number} [params.segmentCount=0] - The length of the output, in
-   *   segments. Zero means it is not known yet, and then a gap search has to be
-   *   given its own bound by the caller.
-   */
-  constructor({ segmentCount = 0 } = {}) {
-    this.#segmentCount = Number.isInteger(segmentCount) && segmentCount > 0 ? segmentCount : 0;
-  }
-
-  /**
-   * The length of the output, once the playlist is known.
-   *
-   * @param {number} count
-   */
-  setSegmentCount(count) {
-    if (Number.isInteger(count) && count > 0) {
-      this.#segmentCount = count;
-    }
-  }
-
-  /** @returns {number} */
-  get segmentCount() {
-    return this.#segmentCount;
-  }
-
-  /**
-   * Record that a segment is closed and can be served.
-   *
-   * Idempotent, and deliberately independent of who made it: a segment made by
-   * a run that has since died is as good as one made by a run still going, and
-   * a segment left by a previous life of this process is as good as either.
-   *
-   * @param {number} index
-   */
-  markReady(index) {
-    if (Number.isInteger(index) && index >= 0) {
-      this.#ready.add(index);
-    }
-  }
-
-  /**
-   * @param {Iterable<number>} indexes
-   */
-  markReadyAll(indexes) {
-    for (const index of indexes) {
-      this.markReady(index);
-    }
-  }
-
-  /**
-   * Forget a segment: its file has gone, or was never closed.
-   *
-   * @param {number} index
-   */
-  markGone(index) {
-    this.#ready.delete(index);
-  }
-
-  /**
-   * A run has been given a stretch to fill.
-   *
-   * Replaces whatever that run claimed before, because a run has one stretch at
-   * a time: moved forward past ready material, it states the new one.
-   *
-   * @param {object} run - The run itself. A run has no name and needs none:
-   *   what identifies it here is that it IS itself, and what identifies it in a
-   *   log line is the stretch it was given, which no other live run of this
-   *   output can hold.
-   * @param {number} from - First segment number, inclusive.
-   * @param {number} to - Last segment number, inclusive. May be
-   *   `Number.POSITIVE_INFINITY` for a run with no end yet, which is what every
-   *   run was before ends existed.
-   */
-  claim(run, from, to) {
-    if (!run || !Number.isInteger(from) || from < 0) {
-      return;
-    }
-    const end = Number.isFinite(to) ? Math.max(from, Math.trunc(to)) : Number.POSITIVE_INFINITY;
-    this.#claims.set(run, { from, to: end });
-  }
-
-  /**
-   * A run has ended. Whatever it did not finish goes back to free.
-   *
-   * Nothing is un-marked: what it DID finish stays ready, because a closed file
-   * is closed whoever made it and whatever became of them afterwards.
-   *
-   * @param {object} run
-   */
-  release(run) {
-    this.#claims.delete(run);
-  }
-
-  /**
-   * How many numbers between two are already made.
-   *
-   * What an encoder driving from one to the other would produce a SECOND time,
-   * and therefore what the swarm would be asked to fetch a second time. It is a
-   * term of when that encoder arrives, not a separate question about whether to
-   * move it: an encoder that has to re-make three hundred pieces on its way is
-   * simply slower to get there, and the model compares arrivals.
-   *
-   * @param {number} from - Inclusive.
-   * @param {number} to - Inclusive.
-   * @returns {number}
-   */
-  madeBetween(from, to) {
-    const first = Number.isInteger(from) && from > 0 ? from : 0;
-    const last = Number.isInteger(to) ? to : -1;
-    let count = 0;
-    for (let index = first; index <= last; index += 1) {
-      if (this.isReady(index)) {
-        count += 1;
-      }
-    }
-    return count;
-  }
-
-  /**
-   * @param {number} index
-   * @returns {boolean}
-   */
-  isReady(index) {
-    return this.#ready.has(index);
-  }
-
-  /**
-   * The run that was given this number, if any.
-   *
-   * @param {number} index
-   * @returns {object | null}
-   */
-  makerOf(index) {
-    for (const [run, span] of this.#claims) {
-      if (index >= span.from && index <= span.to) {
-        return run;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * @param {number} index
-   * @returns {SegmentState}
-   */
-  stateOf(index) {
-    if (this.#ready.has(index)) {
-      return "ready";
-    }
-    return this.makerOf(index) === null ? "free" : "making";
-  }
-
-  /**
-   * The first number at or after `index` that nobody has made and nobody is
-   * making — where a new run belongs.
-   *
-   * @param {number} index
-   * @param {number} [bound] - Search no further than this number, inclusive.
-   *   Defaults to the last segment of the output; required while the length is
-   *   unknown.
-   * @param {object} [exceptRun] - The run asking. Its own claim does not make
-   *   a number taken as far as it is concerned: a run looking for where to move
-   *   would otherwise be blocked by the very stretch it is trying to leave, and
-   *   a run that had claimed the rest of the film could never move at all.
-   * @returns {number | null} Null when there is no gap in range, which is what
-   *   "everything ahead is already covered" looks like.
-   */
-  firstGapFrom(index, bound = undefined, exceptRun = null) {
-    const start = Number.isInteger(index) && index > 0 ? index : 0;
-    const last = Number.isInteger(bound) ? bound : this.#segmentCount - 1;
-    if (!Number.isInteger(last) || last < start) {
-      return null;
-    }
-    for (let at = start; at <= last; at += 1) {
-      if (this.#ready.has(at)) {
-        continue;
-      }
-      const maker = this.makerOf(at);
-      if (maker === null || CoverageMap.#isExcepted(maker, exceptRun)) {
-        return at;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * How many numbers from `index` onwards are already covered — ready, or
-   * claimed by a run other than `exceptRun`.
-   *
-   * This is what prices a decision: a run that has arrived at covered material
-   * either drives through it, paying its own encode time for every one of these
-   * numbers, or is moved to the gap beyond them, paying one restart. Both terms
-   * are measured elsewhere; this is the length.
-   *
-   * @param {number} index
-   * @param {object} [exceptRun] - The run asking. Its own claim does not
-   *   count as somebody else's coverage.
-   * @returns {number}
-   */
-  coveredRunFrom(index, exceptRun = null) {
-    const start = Number.isInteger(index) && index > 0 ? index : 0;
-    const last = this.#segmentCount > 0 ? this.#segmentCount - 1 : Number.MAX_SAFE_INTEGER;
-    let at = start;
-    while (at <= last) {
-      if (this.#ready.has(at)) {
-        at += 1;
-        continue;
-      }
-      const maker = this.makerOf(at);
-      if (maker !== null && !CoverageMap.#isExcepted(maker, exceptRun)) {
-        at += 1;
-        continue;
-      }
-      break;
-    }
-    return at - start;
-  }
-
-  /**
-   * How many numbers from `index` onward have NOT been made, claims ignored.
-   *
-   * The stretch an encoder placed here could work through before it would be
-   * re-making something that exists. Claims are deliberately left out: a claim
-   * says another encoder MEANS to make it, and where two encoders are being
-   * placed in one pass the claims of the moment are about to be re-cut — so
-   * asking about them here gives an answer that was true a step ago. Where one
-   * encoder's road ends because another begins is decided once, over all the
-   * placements together, after they are known.
-   *
-   * @param {number} index
-   * @returns {number} Zero when `index` is already made; the rest of the track
-   *   when nothing ahead is; `Infinity` when the length is not yet known.
-   */
-  unmadeRunFrom(index) {
-    const start = Number.isInteger(index) && index > 0 ? index : 0;
-    if (this.isReady(start)) {
-      return 0;
-    }
-    if (this.#segmentCount <= 0) {
-      return Number.POSITIVE_INFINITY;
-    }
-    let end = start;
-    while (end < this.#segmentCount && !this.isReady(end)) {
-      end += 1;
-    }
-    return end - start;
-  }
-
-  /**
-   * How many numbers from `index` onwards are free — nobody has made them and
-   * nobody is making them.
-   *
-   * This is what gives a run its END. A run handed the whole rest of the film
-   * would drive straight through the next stretch somebody else is making; a
-   * run handed exactly the free stretch stops where the covered material
-   * begins, which is also where it would have been moved to anyway.
-   *
-   * @param {number} index
-   * @param {object} [exceptRun] - The run asking, whose own claim does not
-   *   make a number unfree for it.
-   * @returns {number} Zero when `index` itself is not free.
-   */
-  freeRunFrom(index, exceptRun = null) {
-    const start = Number.isInteger(index) && index > 0 ? index : 0;
-    if (this.#segmentCount <= 0) {
-      // The length is not known, so how far the free stretch reaches is not
-      // known either, and the honest answer is "as far as there is film" — the
-      // caller turns that into a run with no end.
-      //
-      // Never walked one number at a time to find that out. It used to be, up to
-      // MAX_SAFE_INTEGER, with a scan of every claim at each step: on the addon
-      // host, 2026-09-05, the main thread spun at 100% from the look-ahead timer
-      // and the proxy stopped answering anything at all, its own log included.
-      // The length was missing because the field naming it had moved and three
-      // readers were left on the old name — but a walk whose end depends on a
-      // field being present must not be able to do this even then.
-      const covered = this.#firstCoveredFrom(start, exceptRun);
-      return covered === null ? Number.POSITIVE_INFINITY : covered - start;
-    }
-    const last = this.#segmentCount - 1;
-    let at = start;
-    while (at <= last) {
-      if (this.#ready.has(at)) {
-        break;
-      }
-      const maker = this.makerOf(at);
-      if (maker !== null && !CoverageMap.#isExcepted(maker, exceptRun)) {
-        break;
-      }
-      at += 1;
-    }
-    return at - start;
-  }
-
-  /**
-   * The first number at or after `index` that somebody has made or is making,
-   * or null when nobody has touched anything from there on.
-   *
-   * Asked of what the map HOLDS rather than by walking the numbers, so it can be
-   * answered without a length: the map knows every ready number and every claim,
-   * and both are finite however long the film is.
-   *
-   * @param {number} index
-   * @param {object | null} exceptRun
-   * @returns {number | null}
-   */
-  /**
-   * Is this claim one of the runs the caller is setting aside?
-   *
-   * A single run or a set of them: a pass that re-cuts several roads at once has
-   * to ask about all of them together, and asking once per run gave an answer
-   * true of no moment.
-   *
-   * @param {object} maker
-   * @param {object | Set<object> | null} except
-   * @returns {boolean}
-   */
-  static #isExcepted(maker, except) {
-    if (except === null || except === undefined) {
-      return false;
-    }
-    return except instanceof Set ? except.has(maker) : maker === except;
-  }
-
-  #firstCoveredFrom(index, exceptRun) {
-    let lowest = null;
-    for (const ready of this.#ready) {
-      if (ready >= index && (lowest === null || ready < lowest)) {
-        lowest = ready;
-      }
-    }
-    for (const [run, span] of this.#claims) {
-      if (CoverageMap.#isExcepted(run, exceptRun)) {
-        continue;
-      }
-      // A claim that has already begun covers `index` itself.
-      const covers = span.from <= index && index <= span.to ? index : span.from;
-      if (covers >= index && (lowest === null || covers < lowest)) {
-        lowest = covers;
-      }
-    }
-    return lowest;
-  }
-
-  /**
-   * What this map holds, for a log line.
-   *
-   * @returns {{ ready: number, claims: number, segmentCount: number }}
-   */
-  stats() {
-    return {
-      ready: this.#ready.size,
-      claims: this.#claims.size,
-      segmentCount: this.#segmentCount
-    };
-  }
-}
+/**
+ * @file What has been made of one output, what is being made right now, and by
+ * whom.
+ *
+ * One map per set of output parameters — never per session, never per viewer.
+ * Every segment number is in exactly one of three states:
+ *
+ * 1. **ready** — a file that is closed and can be served to anybody;
+ * 2. **being made** — claimed by a named live run, which has been given that
+ *    stretch and is working forward through it;
+ * 3. **free** — nobody has made it and nobody is making it.
+ *
+ * Two questions are asked of it constantly and both have to be cheap, because
+ * one of them is on the path that answers a viewer:
+ *
+ * 1. is segment N ready — a set lookup;
+ * 2. where is the first gap at or after N — a walk over numbers, never over the
+ *    disk. The walk it replaces listed every run directory of a session on the
+ *    thread carrying the data channel, 1350 files for a 90-minute film, on
+ *    every segment request.
+ *
+ * **READINESS IS A PROJECTION, NEVER A MEMORY.** What is ready is a fact of the
+ * disk, and the disk has one owner — the segment store. This map does not
+ * remember what it was once told: {@link CoverageMap#setReady} REPLACES the
+ * whole picture, so every number it calls ready was placed there by that one
+ * authority, whole, immediately before the answer was used.
+ *
+ * It used to accumulate. `markReadyAll` added and nothing ever took away — the
+ * word for taking away existed and was called from no line of the product — so
+ * a number stayed ready for the life of the process after its file had been
+ * discarded, dropped for room, or overwritten by a run restarting on it. Field
+ * 2026-09-07: this map said 482 of 482 segments were made while the directory
+ * held nothing a header could be lifted out of; the plan therefore scored every
+ * arrangement as equally perfect, took the one encoder away as unnecessary — its
+ * own words, "the film is no worse off without it" — and placed none for the
+ * rest of the session. Two sessions in a row ended with the viewer looking at an
+ * error card, and the second one never received a single byte.
+ *
+ * The remedy is not a way to un-mark. A second owner that is kept in step can
+ * fall out of step again; a projection cannot.
+ *
+ * **Claims are intervals, not heads.** A run says which stretch it was given,
+ * so two runs on one output cannot be sent to the same numbers: the gap finder
+ * skips what another run will reach. A run that only announced its current
+ * position would leave the question "will anybody make #400" unanswerable
+ * without guessing at its speed.
+ *
+ * **Nothing here touches a disk, a process or a clock**, so every decision it
+ * makes can be exercised with numbers alone.
+ */
+
+/** @typedef {"ready" | "making" | "free"} SegmentState */
+
+export class CoverageMap {
+  /** Numbers whose file is closed and servable. @type {Set<number>} */
+  #ready = new Set();
+
+  /** Run id → the stretch it was given, both ends inclusive. @type {Map<string, {from: number, to: number}>} */
+  #claims = new Map();
+
+  /** How many segments this output has in total. @type {number} */
+  #segmentCount;
+
+  /**
+   * @param {object} [params]
+   * @param {number} [params.segmentCount=0] - The length of the output, in
+   *   segments. Zero means it is not known yet, and then a gap search has to be
+   *   given its own bound by the caller.
+   */
+  constructor({ segmentCount = 0 } = {}) {
+    this.#segmentCount = Number.isInteger(segmentCount) && segmentCount > 0 ? segmentCount : 0;
+  }
+
+  /**
+   * The length of the output, once the playlist is known.
+   *
+   * @param {number} count
+   */
+  setSegmentCount(count) {
+    if (Number.isInteger(count) && count > 0) {
+      this.#segmentCount = count;
+    }
+  }
+
+  /** @returns {number} */
+  get segmentCount() {
+    return this.#segmentCount;
+  }
+
+  /**
+   * Record that a segment is closed and can be served.
+   *
+   * Idempotent, and deliberately independent of who made it: a segment made by
+   * a run that has since died is as good as one made by a run still going, and
+   * a segment left by a previous life of this process is as good as either.
+   *
+   * @param {number} index
+   */
+  markReady(index) {
+    if (Number.isInteger(index) && index >= 0) {
+      this.#ready.add(index);
+    }
+  }
+
+  /**
+   * State the WHOLE picture of what is ready, replacing whatever was here.
+   *
+   * The only way readiness enters this map in the product, and the reason it
+   * cannot drift: a number absent from `indexes` is not ready, whatever this map
+   * was told a moment ago. Its file may have been discarded with the run that
+   * had it open, dropped to make room, or reopened by a run restarting on it —
+   * none of which this map can see, and none of which it now has to.
+   *
+   * There is deliberately no way to take one number back. A retraction is a
+   * second owner keeping a copy in step, and a copy kept in step is what this
+   * replaced.
+   *
+   * @param {Iterable<number>} indexes
+   */
+  setReady(indexes) {
+    const stated = new Set();
+    for (const index of indexes) {
+      if (Number.isInteger(index) && index >= 0) {
+        stated.add(index);
+      }
+    }
+    this.#ready = stated;
+  }
+
+  /**
+   * A run has been given a stretch to fill.
+   *
+   * Replaces whatever that run claimed before, because a run has one stretch at
+   * a time: moved forward past ready material, it states the new one.
+   *
+   * @param {object} run - The run itself. A run has no name and needs none:
+   *   what identifies it here is that it IS itself, and what identifies it in a
+   *   log line is the stretch it was given, which no other live run of this
+   *   output can hold.
+   * @param {number} from - First segment number, inclusive.
+   * @param {number} to - Last segment number, inclusive. May be
+   *   `Number.POSITIVE_INFINITY` for a run with no end yet, which is what every
+   *   run was before ends existed.
+   */
+  claim(run, from, to) {
+    if (!run || !Number.isInteger(from) || from < 0) {
+      return;
+    }
+    const end = Number.isFinite(to) ? Math.max(from, Math.trunc(to)) : Number.POSITIVE_INFINITY;
+    this.#claims.set(run, { from, to: end });
+  }
+
+  /**
+   * A run has ended. Whatever it did not finish goes back to free.
+   *
+   * Nothing is un-marked: what it DID finish stays ready, because a closed file
+   * is closed whoever made it and whatever became of them afterwards.
+   *
+   * @param {object} run
+   */
+  release(run) {
+    this.#claims.delete(run);
+  }
+
+  /**
+   * How many numbers between two are already made.
+   *
+   * What an encoder driving from one to the other would produce a SECOND time,
+   * and therefore what the swarm would be asked to fetch a second time. It is a
+   * term of when that encoder arrives, not a separate question about whether to
+   * move it: an encoder that has to re-make three hundred pieces on its way is
+   * simply slower to get there, and the model compares arrivals.
+   *
+   * @param {number} from - Inclusive.
+   * @param {number} to - Inclusive.
+   * @returns {number}
+   */
+  madeBetween(from, to) {
+    const first = Number.isInteger(from) && from > 0 ? from : 0;
+    const last = Number.isInteger(to) ? to : -1;
+    let count = 0;
+    for (let index = first; index <= last; index += 1) {
+      if (this.isReady(index)) {
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * @param {number} index
+   * @returns {boolean}
+   */
+  isReady(index) {
+    return this.#ready.has(index);
+  }
+
+  /**
+   * The run that was given this number, if any.
+   *
+   * @param {number} index
+   * @returns {object | null}
+   */
+  makerOf(index) {
+    for (const [run, span] of this.#claims) {
+      if (index >= span.from && index <= span.to) {
+        return run;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * @param {number} index
+   * @returns {SegmentState}
+   */
+  stateOf(index) {
+    if (this.#ready.has(index)) {
+      return "ready";
+    }
+    return this.makerOf(index) === null ? "free" : "making";
+  }
+
+  /**
+   * The first number at or after `index` that nobody has made and nobody is
+   * making — where a new run belongs.
+   *
+   * @param {number} index
+   * @param {number} [bound] - Search no further than this number, inclusive.
+   *   Defaults to the last segment of the output; required while the length is
+   *   unknown.
+   * @param {object} [exceptRun] - The run asking. Its own claim does not make
+   *   a number taken as far as it is concerned: a run looking for where to move
+   *   would otherwise be blocked by the very stretch it is trying to leave, and
+   *   a run that had claimed the rest of the film could never move at all.
+   * @returns {number | null} Null when there is no gap in range, which is what
+   *   "everything ahead is already covered" looks like.
+   */
+  firstGapFrom(index, bound = undefined, exceptRun = null) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    const last = Number.isInteger(bound) ? bound : this.#segmentCount - 1;
+    if (!Number.isInteger(last) || last < start) {
+      return null;
+    }
+    for (let at = start; at <= last; at += 1) {
+      if (this.#ready.has(at)) {
+        continue;
+      }
+      const maker = this.makerOf(at);
+      if (maker === null || CoverageMap.#isExcepted(maker, exceptRun)) {
+        return at;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * How many numbers from `index` onwards are already covered — ready, or
+   * claimed by a run other than `exceptRun`.
+   *
+   * This is what prices a decision: a run that has arrived at covered material
+   * either drives through it, paying its own encode time for every one of these
+   * numbers, or is moved to the gap beyond them, paying one restart. Both terms
+   * are measured elsewhere; this is the length.
+   *
+   * @param {number} index
+   * @param {object} [exceptRun] - The run asking. Its own claim does not
+   *   count as somebody else's coverage.
+   * @returns {number}
+   */
+  coveredRunFrom(index, exceptRun = null) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    const last = this.#segmentCount > 0 ? this.#segmentCount - 1 : Number.MAX_SAFE_INTEGER;
+    let at = start;
+    while (at <= last) {
+      if (this.#ready.has(at)) {
+        at += 1;
+        continue;
+      }
+      const maker = this.makerOf(at);
+      if (maker !== null && !CoverageMap.#isExcepted(maker, exceptRun)) {
+        at += 1;
+        continue;
+      }
+      break;
+    }
+    return at - start;
+  }
+
+  /**
+   * How many numbers from `index` onward have NOT been made, claims ignored.
+   *
+   * The stretch an encoder placed here could work through before it would be
+   * re-making something that exists. Claims are deliberately left out: a claim
+   * says another encoder MEANS to make it, and where two encoders are being
+   * placed in one pass the claims of the moment are about to be re-cut — so
+   * asking about them here gives an answer that was true a step ago. Where one
+   * encoder's road ends because another begins is decided once, over all the
+   * placements together, after they are known.
+   *
+   * @param {number} index
+   * @returns {number} Zero when `index` is already made; the rest of the track
+   *   when nothing ahead is; `Infinity` when the length is not yet known.
+   */
+  unmadeRunFrom(index) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    if (this.isReady(start)) {
+      return 0;
+    }
+    if (this.#segmentCount <= 0) {
+      return Number.POSITIVE_INFINITY;
+    }
+    let end = start;
+    while (end < this.#segmentCount && !this.isReady(end)) {
+      end += 1;
+    }
+    return end - start;
+  }
+
+  /**
+   * How many numbers from `index` onwards are free — nobody has made them and
+   * nobody is making them.
+   *
+   * This is what gives a run its END. A run handed the whole rest of the film
+   * would drive straight through the next stretch somebody else is making; a
+   * run handed exactly the free stretch stops where the covered material
+   * begins, which is also where it would have been moved to anyway.
+   *
+   * @param {number} index
+   * @param {object} [exceptRun] - The run asking, whose own claim does not
+   *   make a number unfree for it.
+   * @returns {number} Zero when `index` itself is not free.
+   */
+  freeRunFrom(index, exceptRun = null) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    if (this.#segmentCount <= 0) {
+      // The length is not known, so how far the free stretch reaches is not
+      // known either, and the honest answer is "as far as there is film" — the
+      // caller turns that into a run with no end.
+      //
+      // Never walked one number at a time to find that out. It used to be, up to
+      // MAX_SAFE_INTEGER, with a scan of every claim at each step: on the addon
+      // host, 2026-09-05, the main thread spun at 100% from the look-ahead timer
+      // and the proxy stopped answering anything at all, its own log included.
+      // The length was missing because the field naming it had moved and three
+      // readers were left on the old name — but a walk whose end depends on a
+      // field being present must not be able to do this even then.
+      const covered = this.#firstCoveredFrom(start, exceptRun);
+      return covered === null ? Number.POSITIVE_INFINITY : covered - start;
+    }
+    const last = this.#segmentCount - 1;
+    let at = start;
+    while (at <= last) {
+      if (this.#ready.has(at)) {
+        break;
+      }
+      const maker = this.makerOf(at);
+      if (maker !== null && !CoverageMap.#isExcepted(maker, exceptRun)) {
+        break;
+      }
+      at += 1;
+    }
+    return at - start;
+  }
+
+  /**
+   * The first number at or after `index` that somebody has made or is making,
+   * or null when nobody has touched anything from there on.
+   *
+   * Asked of what the map HOLDS rather than by walking the numbers, so it can be
+   * answered without a length: the map knows every ready number and every claim,
+   * and both are finite however long the film is.
+   *
+   * @param {number} index
+   * @param {object | null} exceptRun
+   * @returns {number | null}
+   */
+  /**
+   * Is this claim one of the runs the caller is setting aside?
+   *
+   * A single run or a set of them: a pass that re-cuts several roads at once has
+   * to ask about all of them together, and asking once per run gave an answer
+   * true of no moment.
+   *
+   * @param {object} maker
+   * @param {object | Set<object> | null} except
+   * @returns {boolean}
+   */
+  static #isExcepted(maker, except) {
+    if (except === null || except === undefined) {
+      return false;
+    }
+    return except instanceof Set ? except.has(maker) : maker === except;
+  }
+
+  #firstCoveredFrom(index, exceptRun) {
+    let lowest = null;
+    for (const ready of this.#ready) {
+      if (ready >= index && (lowest === null || ready < lowest)) {
+        lowest = ready;
+      }
+    }
+    for (const [run, span] of this.#claims) {
+      if (CoverageMap.#isExcepted(run, exceptRun)) {
+        continue;
+      }
+      // A claim that has already begun covers `index` itself.
+      const covers = span.from <= index && index <= span.to ? index : span.from;
+      if (covers >= index && (lowest === null || covers < lowest)) {
+        lowest = covers;
+      }
+    }
+    return lowest;
+  }
+
+  /**
+   * What this map holds, for a log line.
+   *
+   * @returns {{ ready: number, claims: number, segmentCount: number }}
+   */
+  stats() {
+    return {
+      ready: this.#ready.size,
+      claims: this.#claims.size,
+      segmentCount: this.#segmentCount
+    };
+  }
+}