@torrent-tv/proxy 2.89.5 → 2.89.7

package/services/encode/output/OutputCatalog.js

@@ -1,414 +1,414 @@
-/**
- * @file The one catalog of the outputs that exist, and every question about
- * them.
- *
- * It replaces two classes that held two views of one collection: a registry of
- * the live outputs and their entry times, and a set of queries walking that
- * same registry — which outputs belong to one file, which is the picture and
- * which are its steps and soundtracks, what a step's height is. An output is
- * found by what it IS, never by a list of ids somebody keeps.
- *
- * Presence is the only statement that an output exists. Creation and access
- * times describe the catalog entry, not the media, the viewer or the encoder,
- * so they are kept here and never copied onto the output. What has been
- * produced is not here either: that is the segment store's, and which runs are
- * going is the encoding orchestrator's.
- */
-
-import { variantHeightsFor } from "./ladder.js";
-
-import { masterRateArgs } from "./rates.js";
-
-export class OutputCatalog {
-  #steps = new WeakSet();
-  /** The heights each picture can be spliced to, derived once from its file. @type {WeakMap<object, number[]>} */
-  #splicable = new WeakMap();
-
-  #byId = new Map();
-  #lifetime = new Map();
-  #now;
-
-  /**
-   * @param {object} [params]
-   * @param {() => number} [params.now]
-   * @param {(output: object) => number} [params.fileLengthOf] - How many bytes a
-   *   source file is, which the torrent reports.
-   * @param {(address: string) => { index: number, size: number }} [params.largestPieceOf]
-   *   The biggest piece an output has made, which the disk knows.
-   */
-  constructor({
-    now = Date.now,
-    fileLengthOf = () => 0,
-    largestPieceOf = () => ({ index: -1, size: 0 })
-  } = {}) {
-    this.#now = now;
-    // Two facts this catalog needs and does not own, taken as plain functions
-    // so nothing of their layers is held here: the torrent's byte length and
-    // the store's largest piece. The bitrate limit is not among them any more:
-    // it is part of the output itself (`OutputSpec`).
-    this.fileLengthOf = fileLengthOf;
-    this.largestPieceOf = largestPieceOf;
-  }
-
-  set(id, output) {
-    const known = this.#byId.get(id);
-    this.#byId.set(id, output);
-    if (known !== output) {
-      const at = this.#now();
-      this.#lifetime.set(id, { startedAt: at, lastAccessedAt: at });
-    }
-    return this;
-  }
-
-  get(id) {
-    return this.#byId.get(id);
-  }
-
-  has(id) {
-    return this.#byId.has(id);
-  }
-
-  delete(id) {
-    this.#lifetime.delete(id);
-    return this.#byId.delete(id);
-  }
-
-  clear() {
-    this.#lifetime.clear();
-    this.#byId.clear();
-  }
-
-  touch(outputOrId, at = this.#now()) {
-    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
-    const lifetime = this.#lifetime.get(id);
-    if (!lifetime || !Number.isFinite(at)) {
-      return false;
-    }
-    lifetime.lastAccessedAt = at;
-    return true;
-  }
-
-  startedAt(outputOrId) {
-    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
-    return this.#lifetime.get(id)?.startedAt ?? null;
-  }
-
-  lastAccessedAt(outputOrId) {
-    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
-    return this.#lifetime.get(id)?.lastAccessedAt ?? null;
-  }
-
-  expiredBefore(cutoff) {
-    const ids = [];
-    for (const [id, lifetime] of this.#lifetime) {
-      if (lifetime.lastAccessedAt < cutoff) {
-        ids.push(id);
-      }
-    }
-    return ids;
-  }
-
-  keys() {
-    return this.#byId.keys();
-  }
-
-  values() {
-    return this.#byId.values();
-  }
-
-  entries() {
-    return this.#byId.entries();
-  }
-
-  get size() {
-    return this.#byId.size;
-  }
-
-  [Symbol.iterator]() {
-    return this.#byId[Symbol.iterator]();
-  }
-
-  /**
-   * Every live record producing ONE output.
-   *
-   * The output is the address the encoding layer works in: two sessions whose
-   * output parameters agree ARE the same output, so what one of them measured
-   * about the machine is true of the other.
-   *
-   * @param {string} address
-   * @returns {object[]}
-   */
-  outputsOn(address) {
-    const found = [];
-    for (const session of this.values()) {
-      if (session.outputKey === address) {
-        found.push(session);
-      }
-    }
-    return found;
-  }
-
-  /**
-   * Every live session of one file: the picture, its quality steps, and the
-   * soundtracks published separately.
-   *
-   * The file is what they share, so the file is what this asks about. Where the
-   * sums this feeds are concerned that is also the right question: two pictures
-   * of one file are two encoders on one machine whether or not anybody thinks
-   * of them as one film.
-   *
-   * @param {object} session
-   * @returns {object[]}
-   */
-  familyOf(session) {
-    const family = [session];
-    const key = session?.file?.key;
-    for (const other of this.values()) {
-      if (other === session || other.file?.key !== key) {
-        continue;
-      }
-      family.push(other);
-    }
-    return family;
-  }
-
-  /**
-   * The soundtracks published separately for this picture, live ones only.
-   *
-   * @param {object} base
-   * @returns {object[]}
-   */
-  renditionsOf(base) {
-    return this.familyOf(base).filter((session) => session !== base && session.spec.carries === "audio-only");
-  }
-
-  /**
-   * The quality steps of this picture, live ones only.
-   *
-   * A step is a session made as one — `isStep`, written where it is created —
-   * and not merely "another session of this file that carries a picture". The
-   * difference is the second picture: one file can hold two — a browser that
-   * understands rendition groups and one that needs the sound muxed in produce
-   * two — and calling one of them a step of the other would let a switch away
-   * from a step stop the encoder of somebody else's picture.
-   *
-   * @param {object} base
-   * @returns {object[]}
-   */
-  stepsOf(base) {
-    return this.familyOf(base).filter((session) => session !== base && this.#steps.has(session));
-  }
-
-  markStep(output) {
-    this.#steps.add(output);
-  }
-
-  /**
-   * The picture a step belongs to, or the session itself when it is not a step.
-   *
-   * How a session came to be is a fact about it, not a link to another session
-   * — so a step whose picture has gone answers for itself rather than following
-   * a dead reference, and nothing has to be cleaned from the other side when
-   * one of them ends.
-   *
-   * One file can carry two pictures at once, and then this returns whichever
-   * was made first. Everything asked of the answer is a fact of the FILE and of
-   * this host: what heights can be offered, what a step costs, when the budget
-   * last acted. Two pictures of one file answer all of those alike.
-   *
-   * @param {object} session
-   * @returns {object}
-   */
-  pictureOf(session) {
-    if (!session || !this.#steps.has(session)) {
-      return session;
-    }
-    for (const other of this.familyOf(session)) {
-      if (!this.#steps.has(other) && other.spec.carries !== "audio-only") {
-        return other;
-      }
-    }
-    return session;
-  }
-
-  /**
-   * Whether this output has been SUPERSEDED by the step named here.
-   *
-   * A question about the shape of a film and nothing else: one picture, its
-   * steps, its soundtracks. A step supersedes only the picture it is a step of
-   * — never another step, never a soundtrack, which are produced or not
-   * according to whether anybody asked for them.
-   *
-   * The step arrives as a plain id. Which step is on somebody's screen is a fact
-   * about a PERSON, and this layer neither holds a person nor knows what one
-   * looks like; whoever asks holds both and states the id.
-   *
-   * It is asked while the priority map of one output is built, and it is what
-   * makes the difference between a picture somebody is watching and a picture
-   * they stepped off. Without it every output of a film was handed the film's
-   * whole map, the plan wanted an encoder on each, the session manager killed
-   * the ones it judged unwatched, and the viewer's own move started them again
-   * — the two authorities of 2026-09-08.
-   *
-   * @param {object} session
-   * @param {string | null} [stepOnScreen] - The step being watched, or null for
-   *   "the height the film was opened at", which supersedes nothing.
-   * @returns {boolean}
-   */
-  supersededBy(session, stepOnScreen = null) {
-    if (!session || this.#steps.has(session) || session.spec.carries === "audio-only") {
-      return false;
-    }
-    // The picture. A step of it on screen says outright that this is not what
-    // is being looked at; a step merely being made READY supersedes nothing,
-    // because through a warm-up both are genuinely being produced.
-    return typeof stepOnScreen === "string" && stepOnScreen !== session.id;
-  }
-
-  /**
-   * Which variant a session IS, as a height. Zero encode height means "keep the
-   * source", so the source's own height is the answer.
-   *
-   * Settled once and then kept, because it is a NAME — the player addresses the
-   * variant by it for the whole session, having fetched the master exactly
-   * once. The height a session encodes at is not stable: the realtime budget
-   * steps it down when the host cannot keep up. Deriving the name afresh each
-   * time would mean a downshift silently renames the variant the viewer is
-   * watching, and the next segment request under the old name would build a
-   * SECOND session at the height the host had just proved it could not manage.
-   * A downshift changes the picture inside the variant instead, which is what
-   * it has always done.
-   *
-   * @param {object} session
-   * @returns {number}
-   */
-  variantHeightOf(session) {
-    if (Number.isInteger(session.variantHeight) && session.variantHeight > 0) {
-      return session.variantHeight;
-    }
-    const encodeHeight = Number(session.output.encodeHeight) || 0;
-    session.variantHeight = encodeHeight > 0
-      ? encodeHeight
-      : Math.round(Number(session.file.height) || 0);
-    return session.variantHeight;
-  }
-
-  /**
-   * The height a session's encoder is actually producing, or 0 when it produces
-   * no encoded picture of its own (a copy, or a soundtrack).
-   *
-   * A COPY must never be adopted: it costs no encoder at all, so handing it to
-   * a request for a re-encoded rung would give away the one thing this host can
-   * always serve.
-   *
-   * @param {object} session
-   * @returns {number}
-   */
-  producedHeightOf(session) {
-    if (!session || !session.spec.transcodesVideo || session.spec.carries === "audio-only") {
-      return 0;
-    }
-    return Math.round(Number(session.output.encodeHeight) || 0);
-  }
-
-  /**
-   * The heights this file's variants CAN be spliced at — a fact about the
-   * source and the cut grid, settled once and never moved.
-   *
-   * Separate from which of them are worth OFFERING to the viewer right now, on
-   * a machine whose load moves every five seconds. Both were the same list
-   * until 2026-08-18, and that is what broke playback outright: the browser is
-   * told at session creation that a master playlist exists, and 192 ms later —
-   * after the session's own encoder had started and the first supply reading
-   * had arrived — the live list had fallen from five rungs to one,
-   * `buildMasterPlaylist` returned null for having fewer than two, and the
-   * master answered 404 to the very session that had just published it. hls.js
-   * treats that as fatal and unrecoverable, so nothing played at all (session
-   * `4ef731d8`, "Moana (2016).mkv", 17:43:01).
-   *
-   * A live figure may decide what to offer. It may not decide whether a
-   * published document exists.
-   *
-   * @param {object} session
-   * @returns {number[]} Largest first.
-   */
-  splicableHeights(session) {
-    const owner = this.pictureOf(session);
-    const known = this.#splicable.get(owner);
-    if (known) {
-      return known;
-    }
-    const heights = new Set(variantHeightsFor(Number(owner.file.height) || 0));
-    const own = this.variantHeightOf(owner);
-    if (own > 0) {
-      heights.add(own);
-    }
-    const sorted = [...heights].sort((left, right) => right - left);
-    this.#splicable.set(owner, sorted);
-    return sorted;
-  }
-
-  /**
-   * Whether this stream publishes a master playlist at all — that is, whether
-   * there is anything for a player to move BETWEEN.
-   *
-   * Asked in one place because two callers depend on the same answer and used
-   * to compute it differently: the builder refused a copied stream whose cut
-   * grid is a fiction, while the budget looked only at how many heights could
-   * in principle be spliced. A copy with no readable keyframe index therefore
-   * had requests recorded against it — asking a player with no variants to
-   * change variant, once every window, for the whole film.
-   *
-   * @param {object} session
-   * @returns {boolean}
-   */
-  publishesVariants(session) {
-    const owner = this.pictureOf(session);
-    // A copy can only be cut where the source already has a keyframe, so a rung
-    // meant to splice into it has to be cut at exactly those times. A copy that
-    // fell back to an even grid ffmpeg does not cut on has nothing to align to.
-    if (!owner.spec.transcodesVideo && owner.timeline.cutGrid !== "keyframe") {
-      return false;
-    }
-    return this.splicableHeights(owner).length >= 2;
-  }
-  /**
-   * Everything the master playlist needs of a session except its soundtracks.
-   *
-   * The shape of the film — which heights can be spliced, how big the source
-   * is, how the pieces are packaged — and the rates it carries. All of it is a
-   * fact about the OUTPUT, and it was assembled at the call site in the session
-   * manager, which is the file that is being taken apart.
-   *
-   * The soundtracks are not here on purpose: which of them is marked default is
-   * the asking VIEWER'S business, and that belongs to whoever holds viewers.
-   *
-   * @param {object} session
-   * @returns {object}
-   */
-  masterFactsOf(session) {
-    return {
-      playlistVersion: session.segmentFormat.playlistVersion,
-      heights: this.splicableHeights(session),
-      sourceWidth: Number(session.file?.width) || 0,
-      sourceHeight: Number(session.file?.height) || 0,
-      ...masterRateArgs({
-        // FROM WHOEVER KNOWS IT. A source file does not carry its own byte
-        // length — the torrent reports it — and reading a field that does not
-        // exist is what declared every variant at the floor in 2.80.14.
-        fileLength: Number(this.fileLengthOf(session)) || 0,
-        durationSeconds: Number(session.file?.durationSeconds) || 0,
-        // The probe's own reading of the video stream, which is known from the
-        // moment the session exists and covers the gap before the torrent has
-        // reported a length.
-        streamBitsPerSecond: (Number(session.file?.decode?.megabitsPerSecond) || 0) * 1_000_000,
-        largest: this.largestPieceOf(session.outputKey ?? ""),
-        boundaries: session.timeline?.published ?? session.timeline?.boundaries ?? null,
-        producedHeight: this.producedHeightOf(session),
-        // The peak the encoder is held to, which is what BANDWIDTH declares.
-        // Zero where nothing bounds it — a copy, or a hardware encoder.
-        capKbps: Number(session.spec?.video?.encode?.rateControl?.maxrateKbps) || 0
-      })
-    };
-  }
-}
+/**
+ * @file The one catalog of the outputs that exist, and every question about
+ * them.
+ *
+ * It replaces two classes that held two views of one collection: a registry of
+ * the live outputs and their entry times, and a set of queries walking that
+ * same registry — which outputs belong to one file, which is the picture and
+ * which are its steps and soundtracks, what a step's height is. An output is
+ * found by what it IS, never by a list of ids somebody keeps.
+ *
+ * Presence is the only statement that an output exists. Creation and access
+ * times describe the catalog entry, not the media, the viewer or the encoder,
+ * so they are kept here and never copied onto the output. What has been
+ * produced is not here either: that is the segment store's, and which runs are
+ * going is the encoding orchestrator's.
+ */
+
+import { variantHeightsFor } from "./ladder.js";
+
+import { masterRateArgs } from "./rates.js";
+
+export class OutputCatalog {
+  #steps = new WeakSet();
+  /** The heights each picture can be spliced to, derived once from its file. @type {WeakMap<object, number[]>} */
+  #splicable = new WeakMap();
+
+  #byId = new Map();
+  #lifetime = new Map();
+  #now;
+
+  /**
+   * @param {object} [params]
+   * @param {() => number} [params.now]
+   * @param {(output: object) => number} [params.fileLengthOf] - How many bytes a
+   *   source file is, which the torrent reports.
+   * @param {(address: string) => { index: number, size: number }} [params.largestPieceOf]
+   *   The biggest piece an output has made, which the disk knows.
+   */
+  constructor({
+    now = Date.now,
+    fileLengthOf = () => 0,
+    largestPieceOf = () => ({ index: -1, size: 0 })
+  } = {}) {
+    this.#now = now;
+    // Two facts this catalog needs and does not own, taken as plain functions
+    // so nothing of their layers is held here: the torrent's byte length and
+    // the store's largest piece. The bitrate limit is not among them any more:
+    // it is part of the output itself (`OutputSpec`).
+    this.fileLengthOf = fileLengthOf;
+    this.largestPieceOf = largestPieceOf;
+  }
+
+  set(id, output) {
+    const known = this.#byId.get(id);
+    this.#byId.set(id, output);
+    if (known !== output) {
+      const at = this.#now();
+      this.#lifetime.set(id, { startedAt: at, lastAccessedAt: at });
+    }
+    return this;
+  }
+
+  get(id) {
+    return this.#byId.get(id);
+  }
+
+  has(id) {
+    return this.#byId.has(id);
+  }
+
+  delete(id) {
+    this.#lifetime.delete(id);
+    return this.#byId.delete(id);
+  }
+
+  clear() {
+    this.#lifetime.clear();
+    this.#byId.clear();
+  }
+
+  touch(outputOrId, at = this.#now()) {
+    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
+    const lifetime = this.#lifetime.get(id);
+    if (!lifetime || !Number.isFinite(at)) {
+      return false;
+    }
+    lifetime.lastAccessedAt = at;
+    return true;
+  }
+
+  startedAt(outputOrId) {
+    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
+    return this.#lifetime.get(id)?.startedAt ?? null;
+  }
+
+  lastAccessedAt(outputOrId) {
+    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
+    return this.#lifetime.get(id)?.lastAccessedAt ?? null;
+  }
+
+  expiredBefore(cutoff) {
+    const ids = [];
+    for (const [id, lifetime] of this.#lifetime) {
+      if (lifetime.lastAccessedAt < cutoff) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  }
+
+  keys() {
+    return this.#byId.keys();
+  }
+
+  values() {
+    return this.#byId.values();
+  }
+
+  entries() {
+    return this.#byId.entries();
+  }
+
+  get size() {
+    return this.#byId.size;
+  }
+
+  [Symbol.iterator]() {
+    return this.#byId[Symbol.iterator]();
+  }
+
+  /**
+   * Every live record producing ONE output.
+   *
+   * The output is the address the encoding layer works in: two sessions whose
+   * output parameters agree ARE the same output, so what one of them measured
+   * about the machine is true of the other.
+   *
+   * @param {string} address
+   * @returns {object[]}
+   */
+  outputsOn(address) {
+    const found = [];
+    for (const session of this.values()) {
+      if (session.outputKey === address) {
+        found.push(session);
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Every live session of one file: the picture, its quality steps, and the
+   * soundtracks published separately.
+   *
+   * The file is what they share, so the file is what this asks about. Where the
+   * sums this feeds are concerned that is also the right question: two pictures
+   * of one file are two encoders on one machine whether or not anybody thinks
+   * of them as one film.
+   *
+   * @param {object} session
+   * @returns {object[]}
+   */
+  familyOf(session) {
+    const family = [session];
+    const key = session?.file?.key;
+    for (const other of this.values()) {
+      if (other === session || other.file?.key !== key) {
+        continue;
+      }
+      family.push(other);
+    }
+    return family;
+  }
+
+  /**
+   * The soundtracks published separately for this picture, live ones only.
+   *
+   * @param {object} base
+   * @returns {object[]}
+   */
+  renditionsOf(base) {
+    return this.familyOf(base).filter((session) => session !== base && session.spec.carries === "audio-only");
+  }
+
+  /**
+   * The quality steps of this picture, live ones only.
+   *
+   * A step is a session made as one — `isStep`, written where it is created —
+   * and not merely "another session of this file that carries a picture". The
+   * difference is the second picture: one file can hold two — a browser that
+   * understands rendition groups and one that needs the sound muxed in produce
+   * two — and calling one of them a step of the other would let a switch away
+   * from a step stop the encoder of somebody else's picture.
+   *
+   * @param {object} base
+   * @returns {object[]}
+   */
+  stepsOf(base) {
+    return this.familyOf(base).filter((session) => session !== base && this.#steps.has(session));
+  }
+
+  markStep(output) {
+    this.#steps.add(output);
+  }
+
+  /**
+   * The picture a step belongs to, or the session itself when it is not a step.
+   *
+   * How a session came to be is a fact about it, not a link to another session
+   * — so a step whose picture has gone answers for itself rather than following
+   * a dead reference, and nothing has to be cleaned from the other side when
+   * one of them ends.
+   *
+   * One file can carry two pictures at once, and then this returns whichever
+   * was made first. Everything asked of the answer is a fact of the FILE and of
+   * this host: what heights can be offered, what a step costs, when the budget
+   * last acted. Two pictures of one file answer all of those alike.
+   *
+   * @param {object} session
+   * @returns {object}
+   */
+  pictureOf(session) {
+    if (!session || !this.#steps.has(session)) {
+      return session;
+    }
+    for (const other of this.familyOf(session)) {
+      if (!this.#steps.has(other) && other.spec.carries !== "audio-only") {
+        return other;
+      }
+    }
+    return session;
+  }
+
+  /**
+   * Whether this output has been SUPERSEDED by the step named here.
+   *
+   * A question about the shape of a film and nothing else: one picture, its
+   * steps, its soundtracks. A step supersedes only the picture it is a step of
+   * — never another step, never a soundtrack, which are produced or not
+   * according to whether anybody asked for them.
+   *
+   * The step arrives as a plain id. Which step is on somebody's screen is a fact
+   * about a PERSON, and this layer neither holds a person nor knows what one
+   * looks like; whoever asks holds both and states the id.
+   *
+   * It is asked while the priority map of one output is built, and it is what
+   * makes the difference between a picture somebody is watching and a picture
+   * they stepped off. Without it every output of a film was handed the film's
+   * whole map, the plan wanted an encoder on each, the session manager killed
+   * the ones it judged unwatched, and the viewer's own move started them again
+   * — the two authorities of 2026-09-08.
+   *
+   * @param {object} session
+   * @param {string | null} [stepOnScreen] - The step being watched, or null for
+   *   "the height the film was opened at", which supersedes nothing.
+   * @returns {boolean}
+   */
+  supersededBy(session, stepOnScreen = null) {
+    if (!session || this.#steps.has(session) || session.spec.carries === "audio-only") {
+      return false;
+    }
+    // The picture. A step of it on screen says outright that this is not what
+    // is being looked at; a step merely being made READY supersedes nothing,
+    // because through a warm-up both are genuinely being produced.
+    return typeof stepOnScreen === "string" && stepOnScreen !== session.id;
+  }
+
+  /**
+   * Which variant a session IS, as a height. Zero encode height means "keep the
+   * source", so the source's own height is the answer.
+   *
+   * Settled once and then kept, because it is a NAME — the player addresses the
+   * variant by it for the whole session, having fetched the master exactly
+   * once. The height a session encodes at is not stable: the realtime budget
+   * steps it down when the host cannot keep up. Deriving the name afresh each
+   * time would mean a downshift silently renames the variant the viewer is
+   * watching, and the next segment request under the old name would build a
+   * SECOND session at the height the host had just proved it could not manage.
+   * A downshift changes the picture inside the variant instead, which is what
+   * it has always done.
+   *
+   * @param {object} session
+   * @returns {number}
+   */
+  variantHeightOf(session) {
+    if (Number.isInteger(session.variantHeight) && session.variantHeight > 0) {
+      return session.variantHeight;
+    }
+    const encodeHeight = Number(session.output.encodeHeight) || 0;
+    session.variantHeight = encodeHeight > 0
+      ? encodeHeight
+      : Math.round(Number(session.file.height) || 0);
+    return session.variantHeight;
+  }
+
+  /**
+   * The height a session's encoder is actually producing, or 0 when it produces
+   * no encoded picture of its own (a copy, or a soundtrack).
+   *
+   * A COPY must never be adopted: it costs no encoder at all, so handing it to
+   * a request for a re-encoded rung would give away the one thing this host can
+   * always serve.
+   *
+   * @param {object} session
+   * @returns {number}
+   */
+  producedHeightOf(session) {
+    if (!session || !session.spec.transcodesVideo || session.spec.carries === "audio-only") {
+      return 0;
+    }
+    return Math.round(Number(session.output.encodeHeight) || 0);
+  }
+
+  /**
+   * The heights this file's variants CAN be spliced at — a fact about the
+   * source and the cut grid, settled once and never moved.
+   *
+   * Separate from which of them are worth OFFERING to the viewer right now, on
+   * a machine whose load moves every five seconds. Both were the same list
+   * until 2026-08-18, and that is what broke playback outright: the browser is
+   * told at session creation that a master playlist exists, and 192 ms later —
+   * after the session's own encoder had started and the first supply reading
+   * had arrived — the live list had fallen from five rungs to one,
+   * `buildMasterPlaylist` returned null for having fewer than two, and the
+   * master answered 404 to the very session that had just published it. hls.js
+   * treats that as fatal and unrecoverable, so nothing played at all (session
+   * `4ef731d8`, "Moana (2016).mkv", 17:43:01).
+   *
+   * A live figure may decide what to offer. It may not decide whether a
+   * published document exists.
+   *
+   * @param {object} session
+   * @returns {number[]} Largest first.
+   */
+  splicableHeights(session) {
+    const owner = this.pictureOf(session);
+    const known = this.#splicable.get(owner);
+    if (known) {
+      return known;
+    }
+    const heights = new Set(variantHeightsFor(Number(owner.file.height) || 0));
+    const own = this.variantHeightOf(owner);
+    if (own > 0) {
+      heights.add(own);
+    }
+    const sorted = [...heights].sort((left, right) => right - left);
+    this.#splicable.set(owner, sorted);
+    return sorted;
+  }
+
+  /**
+   * Whether this stream publishes a master playlist at all — that is, whether
+   * there is anything for a player to move BETWEEN.
+   *
+   * Asked in one place because two callers depend on the same answer and used
+   * to compute it differently: the builder refused a copied stream whose cut
+   * grid is a fiction, while the budget looked only at how many heights could
+   * in principle be spliced. A copy with no readable keyframe index therefore
+   * had requests recorded against it — asking a player with no variants to
+   * change variant, once every window, for the whole film.
+   *
+   * @param {object} session
+   * @returns {boolean}
+   */
+  publishesVariants(session) {
+    const owner = this.pictureOf(session);
+    // A copy can only be cut where the source already has a keyframe, so a rung
+    // meant to splice into it has to be cut at exactly those times. A copy that
+    // fell back to an even grid ffmpeg does not cut on has nothing to align to.
+    if (!owner.spec.transcodesVideo && owner.timeline.cutGrid !== "keyframe") {
+      return false;
+    }
+    return this.splicableHeights(owner).length >= 2;
+  }
+  /**
+   * Everything the master playlist needs of a session except its soundtracks.
+   *
+   * The shape of the film — which heights can be spliced, how big the source
+   * is, how the pieces are packaged — and the rates it carries. All of it is a
+   * fact about the OUTPUT, and it was assembled at the call site in the session
+   * manager, which is the file that is being taken apart.
+   *
+   * The soundtracks are not here on purpose: which of them is marked default is
+   * the asking VIEWER'S business, and that belongs to whoever holds viewers.
+   *
+   * @param {object} session
+   * @returns {object}
+   */
+  masterFactsOf(session) {
+    return {
+      playlistVersion: session.segmentFormat.playlistVersion,
+      heights: this.splicableHeights(session),
+      sourceWidth: Number(session.file?.width) || 0,
+      sourceHeight: Number(session.file?.height) || 0,
+      ...masterRateArgs({
+        // FROM WHOEVER KNOWS IT. A source file does not carry its own byte
+        // length — the torrent reports it — and reading a field that does not
+        // exist is what declared every variant at the floor in 2.80.14.
+        fileLength: Number(this.fileLengthOf(session)) || 0,
+        durationSeconds: Number(session.file?.durationSeconds) || 0,
+        // The probe's own reading of the video stream, which is known from the
+        // moment the session exists and covers the gap before the torrent has
+        // reported a length.
+        streamBitsPerSecond: (Number(session.file?.decode?.megabitsPerSecond) || 0) * 1_000_000,
+        largest: this.largestPieceOf(session.outputKey ?? ""),
+        boundaries: session.timeline?.published ?? session.timeline?.boundaries ?? null,
+        producedHeight: this.producedHeightOf(session),
+        // The peak the encoder is held to, which is what BANDWIDTH declares.
+        // Zero where nothing bounds it — a copy, or a hardware encoder.
+        capKbps: Number(session.spec?.video?.encode?.rateControl?.maxrateKbps) || 0
+      })
+    };
+  }
+}