@torrent-tv/proxy 2.80.11 → 2.80.12

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.80.12
+
+- **Chore**: The predicate that decides whether an output is the one somebody is consuming asks each layer only for what it owns. Written first as `LiveOutputs.watchedBy(session, viewer)`, it had the output layer reading a viewer's fields — a coupling in the wrong direction, however plain the values. It is `supersededBy(session, stepOnScreen)` now, taking a plain id: which step is on somebody's screen belongs to the person, which output a step supersedes belongs to the film's shape, and the one place that legitimately holds both puts them together.
+- **New**: `docs/encode-architecture.md` — who decides where encoders go, with the shape drawn: viewers become a map and the map is the whole crossing, the four things the plan decides from, why the map is read at two scopes, and a table of what each of the eight other places used to do against what it now states. `docs/download-architecture.md` gains the priority map as a claimant, which it has been since 2026-09-05 and was never drawn as, and a section saying what each claimant knows — a read states only the piece it is stopped on, which is a fact and not a forecast.
+
 ## 2.80.11
 
 - **Fix**: ONE authority over where encoders go, and it is the plan. Eight other places placed or killed them, each by a rule of its own: the first run of a session, a viewer joining it further in, a quality step or a soundtrack being warmed, a step being switched to, a hardware encoder falling back to software, an input coming back, the cut table correcting itself, and a settled seek. The plan is arithmetic over what is made, what is being made and what is wanted; beside eight other answers it was one opinion among nine. Every one of them now states the FACT it knows — this person is here, this output is nobody's, this encoder's arguments are stale — and the plan places what follows. `this.#startEncodeRun` has exactly one caller.

package/CLAUDE.md

@@ -72,6 +72,12 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     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/encode-architecture.md` — who decides where encoders go, and the
+    answer is one authority: `EncodePlan`, from what is made, what is being
+    made, what is wanted and what the host can hold. Why no viewer reaches it,
+    why the priority map is read at two scopes (per FILE for the swarm, per
+    OUTPUT for the encoders), and what each of the eight other places that used
+    to place or kill an encoder now states instead.
   - `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

@@ -37,10 +37,12 @@ flowchart TB
   end
 
   subgraph Claimants["who states needs"]
-    PR[piece-reader<br/>four bands per read]
+    PM[priority map<br/>where the viewers are, per FILE]
+    PR[piece-reader<br/>the piece it is stopped on]
     BF[torrent-pool<br/>background fill, per file]
   end
 
+  PM -->|state / withdraw| R
   PR -->|state / withdraw| R
   BF -->|state / withdraw| R
   W --> R
@@ -51,6 +53,25 @@ flowchart TB
   S -->|the only caller| WT[(WebTorrent)]
 ```
 
+## Who the claimants are, and what each of them knows
+
+**The priority map** states what should be downloaded AHEAD of the viewers, once
+per file, built in `services/priority/` from where they are and from nothing
+else. It is the same map the encoding reads — the encoding reads it per OUTPUT
+and in segment numbers, this layer reads it per FILE and in bytes, and both
+scopes are right for what asks them (`encode-architecture.md`).
+
+**A read** states only the piece it is STOPPED ON. That is not a forecast but the
+fact that somebody is waiting there, and it is what keeps working for the reads
+the viewers' map does not cover: a container header at open, the subtitle walk, a
+soundtrack being fetched whole. Until 2026-09-02 each read built four bands
+around its own head instead, so fifteen reads were fifteen forecasts on a store
+holding sixteen pieces, half of all evictions took a piece a reader had said it
+wanted, and two thirds of reads came back from disk.
+
+**The background fill** states one file at a time — a soundtrack pulled whole
+once the cushion is full, and no further.
+
 ## The five levels
 
 | level | what it is | stated |

package/docs/encode-architecture.md

@@ -0,0 +1,150 @@
+# Encode architecture — who decides where encoders go
+
+One question, one answer, and the answer is arithmetic.
+
+> Viewers are always independent and always reuse what can be reused. The
+> number of encoders is however many are needed; how many are needed follows
+> from which sets of output parameters are wanted and where the viewers stand
+> inside each. Segments produced by ANY encoder are available to ANY viewer, and
+> which viewer asked never enters the question.
+
+## The one authority
+
+`services/encode/EncodePlan.js` decides. Nothing else places an encoder,
+nothing else takes one away for scheduling reasons, and there is exactly one
+call to `#startEncodeRun` in the whole proxy — the one the plan asks through.
+
+It decides from four things and no others:
+
+| what | where it comes from |
+|---|---|
+| what is already made | the segment store, asked afresh before every decision |
+| what is being made | the coverage map's live claims |
+| what is wanted | the priority map of that output |
+| how many the machine can hold | `run-budget.js`, from measurements of this host |
+
+**No viewer reaches it.** `services/encode/` and
+`services/orchestrators/EncodeOrchestrator.js` do not import the viewer layer,
+name a consumer id, or hold a person. What crosses is a priority map: zones of
+segment numbers with a rank and a real time, and nobody's name on it.
+
+## Viewers become a map, and that is the whole crossing
+
+```mermaid
+flowchart TB
+  subgraph V["services/viewer — where people are"]
+    VW[Viewer<br/>position, playing, buffered, chosen track]
+    VS[Viewers<br/>the relation, indexed from both ends]
+  end
+
+  subgraph P["services/priority — one fact, two scopes"]
+    PM[PriorityMap<br/>seconds of film to a rank]
+    PO[PriorityOrchestrator<br/>merge, publish, keep]
+  end
+
+  subgraph E["services/encode — where encoders go"]
+    CM[CoverageMap<br/>ready / making / free]
+    EP[EncodePlan<br/>argmin over arrangements]
+    RB[run-budget<br/>what this host can hold]
+    ER[EncodeRun<br/>one process, one interval]
+  end
+
+  subgraph D["services/demand + download — what the swarm is told"]
+    DR[DemandRegister]
+    SS[SwarmSelection]
+  end
+
+  VW --> VS
+  VS -->|"positions, presence"| PO
+  PM --> PO
+  PO -->|"per FILE, in bytes"| DR
+  DR --> SS
+  PO -->|"per OUTPUT, in segments"| EO[EncodeOrchestrator]
+  EO --> EP
+  CM --> EP
+  RB --> EP
+  EP -->|"start / stop / move"| ER
+  ST[(SegmentStore<br/>the disk)] -->|"what is ready"| CM
+```
+
+## Two scopes of one map, and both are right
+
+The map is built from where the viewers are, once, and read at two scopes.
+
+**Per FILE, for the swarm.** The picture, a quality step and a soundtrack of one
+film read the same bytes, so every viewer of any of them wants that file's
+bytes. This is what `PriorityOrchestrator.mapFor(sourceKey, fileIndex)`
+answers, and what is published to the download layer.
+
+**Per OUTPUT, for the encoders.** A person watching 480p wants nothing of the
+1080p output at all. This is `mapForOutput(address)`.
+
+One map for both was the second authority over encoders. Handed the film's map,
+the plan wanted an encoder on every output of the film; what actually stopped
+the ones nobody was watching was the session manager killing them by its own
+judgement — and since a viewer moving between steps announces itself, the plan
+started them again on the very next pass. Two parties answering "should this
+encoder exist" by different rules, several times a second.
+
+An output nobody is on gets a map with **nothing in it**, which is a statement
+and not an absence: the walk writes one for every output a session exists for,
+including the ones everybody has left. That is how the plan is told to stop what
+is on it.
+
+## Which output a person is consuming
+
+A person holds a record on more outputs than they are consuming. The picture is
+where their record lives — the browser addresses it, their chosen soundtrack is
+written on it, their position is read from it — so they are never let go of it;
+but the moment they step down to 480p, the 1080p output is producing for nobody.
+
+That distinction is answered where the two facts meet, and neither layer is
+handed the other:
+
+- **which step is on their screen** is a fact about a PERSON, read off the
+  viewer as one field;
+- **which output a step supersedes** is a fact about the FILM'S SHAPE, answered
+  by `LiveOutputs.supersededBy(session, stepOnScreen)`, which takes a plain id
+  and has never seen a viewer.
+
+A step, a soundtrack, and a step being warmed are consumed by whoever is
+registered on them — everywhere but the picture, a person who stops watching is
+let go of, so being known to an output is consuming it. Through a warm-up both
+the step on screen and the step being made ready are genuinely produced, which
+is the price of the switch not being visible.
+
+## What each of the eight other places used to do
+
+Before 2026-09-08 the plan was one opinion among nine. Each of these placed or
+killed encoders by a rule of its own; each now states the fact it knows.
+
+| it knows | it used to do | it now says |
+|---|---|---|
+| a session was created | start a run at the viewer's position, worked out again | the viewer is placed; the plan reads that |
+| a viewer joined further in | start a run there if nothing was being made | as above |
+| a step or soundtrack is being warmed | point that session at the switch and start it | this person is at N seconds on it |
+| a step was switched to | stop the one left, point the new one | this person is on this step now |
+| a step or track was abandoned | stop its encoder | this person has left that output |
+| the hardware encoder failed | start a run at the dead one's start | what this host encodes with has changed |
+| the input came back | start a run at the last requested segment | decide again |
+| the cut table was corrected | restart the members at the measured instant | this run is producing in the wrong place; the instant is in the file's table |
+| the bitrate cap changed | restart at where the encoder had got to | this run's arguments are stale |
+
+A **seek** is not in that list because it was already reduced to one thing: it
+puts the viewer where they are. The settle timer behind it, its cooldown and its
+one-segment backoff are gone — a second debounce on a signal the browser had
+already debounced, and every millisecond of it was dead time in front of the
+viewer.
+
+## What is checked
+
+`test/one-authority.test.js` holds the shape: one caller of `#startEncodeRun`,
+no encoder stopped for being unwatched, the settle machinery absent, each output
+reading its own map, and the soundtrack's start instant read off the table
+rather than handed in.
+
+`test/priority-map-per-output.test.js` holds the two scopes, over the real
+viewer registry, the real `LiveOutputs` and the real `PriorityOrchestrator`.
+
+`test/encode-plan.test.js` holds the arithmetic, including that every encoder
+stops when nobody is watching the output.

package/package.json

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

package/services/hls-session-manager.js

@@ -1563,7 +1563,11 @@ export class HlsSessionManager {
         ).catch(() => {});
       },
       viewersOf: (session) => viewersOf(session),
-      watchedBy: (session, viewer) => this.liveOutputs.watchedBy(session, viewer),
+      // WHERE THE TWO FACTS MEET, and this is the only place that holds both.
+      // Which step is on somebody's screen belongs to the person; which output
+      // a step supersedes belongs to the film's shape. Neither layer is handed
+      // the other — one gets a plain id, the other is read for one field.
+      watchedBy: (session, viewer) => !this.liveOutputs.supersededBy(session, viewer.activeVariantId ?? null),
       allowanceFor: (session) => minimumBufferFrom({
         segmentSeconds: this.segmentDurationSec,
         worstSupplyWaitSec: session.supplyFigures?.worstWaitSec

package/services/output/LiveOutputs.js

@@ -1,282 +1,267 @@
-/**
- * @file Which outputs of one file exist right now, and what each of them is.
- *
- * Every question here is answered by walking the live sessions and looking at
- * what they ARE — the same file, a step, a soundtrack, this height — and not by
- * following a list of ids anybody keeps. A list of ids is a link between
- * sessions: it ties their lifetimes together, it goes stale when one of them is
- * disposed, and it has to be cleaned from the other side. What an output is is
- * enough to find it, which is the rule `OutputSpec` exists for.
- *
- * Nothing here writes anything except the two answers a session memoizes about
- * itself, and nothing here knows about encoders, viewers, the torrent or the
- * disk. It is the layer the quality budget and the serving path both stand on,
- * and it is separated first for that reason.
- */
-
-import { variantHeightsFor } from "./ladder.js";
-
-export class LiveOutputs {
-  /**
-   * @param {object} params
-   * @param {Map<string, object>} params.sessionsById - The live sessions. Read,
-   *   never written.
-   */
-  constructor({ sessionsById }) {
-    this.sessionsById = sessionsById;
-  }
-
-  /**
-   * Every live session 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[]}
-   */
-  sessionsOn(address) {
-    const found = [];
-    for (const session of this.sessionsById.values()) {
-      if (session.outputKey === address && session.state !== "disposed") {
-        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.sessionsById.values()) {
-      if (other === session || other.state === "disposed" || 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.audioOnly === true);
-  }
-
-  /**
-   * 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 && session.isStep === true);
-  }
-
-  /**
-   * 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 || session.isStep !== true) {
-      return session;
-    }
-    for (const other of this.familyOf(session)) {
-      if (other.isStep !== true && other.audioOnly !== true) {
-        return other;
-      }
-    }
-    return session;
-  }
-
-  /**
-   * Whether this output is the one that person is CONSUMING.
-   *
-   * A person holds a record on more outputs than they are watching, and the two
-   * are different facts. The picture is where their record lives — the browser
-   * addresses it, their chosen soundtrack is written on it, their position is
-   * read from it — so they never stop being known to it; but the moment they
-   * step down to 480p, the 1080p output is producing for nobody.
-   *
-   * Which is why this exists and why it is here. It is asked when the priority
-   * map of one output is built, and it decides whether an encoder on that output
-   * is wanted at all. 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 announced itself and
-   * started them again — the two authorities of 2026-09-08.
-   *
-   * The viewer arrives as PLAIN FIELDS. This layer knows the shape of a film — a
-   * picture, its steps, its soundtracks — and the viewer layer knows where a
-   * person stands; neither holds the other.
-   *
-   * STATED AS A REFUSAL, and deliberately only where the refusal is certain.
-   * Being known to an output is watching it everywhere except one case, because
-   * everywhere else a person who stops watching is let go of: a soundtrack
-   * nobody chose, a step nobody is on. The exception is the picture itself,
-   * which they are never let go of — and which therefore had no way at all of
-   * knowing it was producing for nobody.
-   *
-   * So a step, a soundtrack, a step being warmed, a step whose init has just
-   * been asked for: all watched, as before. The picture: watched unless this
-   * person is on a step of it.
-   *
-   * @param {object} session
-   * @param {{ activeVariantId?: string | null, warmingVariantId?: string | null }} viewer
-   * @returns {boolean}
-   */
-  watchedBy(session, viewer) {
-    if (!session || !viewer) {
-      return false;
-    }
-    if (session.isStep === true || session.audioOnly === true) {
-      return true;
-    }
-    // The picture. A step of it on their screen is a statement that they are
-    // not looking at this; a step merely being made ready for them is not, and
-    // during a warm-up both are genuinely being produced.
-    const step = viewer.activeVariantId ?? null;
-    return step === null || step === 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.transcodeVideo !== true || session.audioOnly === true) {
-      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);
-    if (Array.isArray(owner.splicableHeights)) {
-      return owner.splicableHeights;
-    }
-    const heights = new Set(variantHeightsFor(Number(owner.file.height) || 0));
-    const own = this.variantHeightOf(owner);
-    if (own > 0) {
-      heights.add(own);
-    }
-    owner.splicableHeights = [...heights].sort((left, right) => right - left);
-    return owner.splicableHeights;
-  }
-
-  /**
-   * 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.transcodeVideo && owner.timeline.cutGrid !== "keyframe") {
-      return false;
-    }
-    return this.splicableHeights(owner).length >= 2;
-  }
-}
+/**
+ * @file Which outputs of one file exist right now, and what each of them is.
+ *
+ * Every question here is answered by walking the live sessions and looking at
+ * what they ARE — the same file, a step, a soundtrack, this height — and not by
+ * following a list of ids anybody keeps. A list of ids is a link between
+ * sessions: it ties their lifetimes together, it goes stale when one of them is
+ * disposed, and it has to be cleaned from the other side. What an output is is
+ * enough to find it, which is the rule `OutputSpec` exists for.
+ *
+ * Nothing here writes anything except the two answers a session memoizes about
+ * itself, and nothing here knows about encoders, viewers, the torrent or the
+ * disk. It is the layer the quality budget and the serving path both stand on,
+ * and it is separated first for that reason.
+ */
+
+import { variantHeightsFor } from "./ladder.js";
+
+export class LiveOutputs {
+  /**
+   * @param {object} params
+   * @param {Map<string, object>} params.sessionsById - The live sessions. Read,
+   *   never written.
+   */
+  constructor({ sessionsById }) {
+    this.sessionsById = sessionsById;
+  }
+
+  /**
+   * Every live session 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[]}
+   */
+  sessionsOn(address) {
+    const found = [];
+    for (const session of this.sessionsById.values()) {
+      if (session.outputKey === address && session.state !== "disposed") {
+        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.sessionsById.values()) {
+      if (other === session || other.state === "disposed" || 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.audioOnly === true);
+  }
+
+  /**
+   * 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 && session.isStep === true);
+  }
+
+  /**
+   * 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 || session.isStep !== true) {
+      return session;
+    }
+    for (const other of this.familyOf(session)) {
+      if (other.isStep !== true && other.audioOnly !== true) {
+        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 || session.isStep === true || session.audioOnly === true) {
+      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.transcodeVideo !== true || session.audioOnly === true) {
+      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);
+    if (Array.isArray(owner.splicableHeights)) {
+      return owner.splicableHeights;
+    }
+    const heights = new Set(variantHeightsFor(Number(owner.file.height) || 0));
+    const own = this.variantHeightOf(owner);
+    if (own > 0) {
+      heights.add(own);
+    }
+    owner.splicableHeights = [...heights].sort((left, right) => right - left);
+    return owner.splicableHeights;
+  }
+
+  /**
+   * 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.transcodeVideo && owner.timeline.cutGrid !== "keyframe") {
+      return false;
+    }
+    return this.splicableHeights(owner).length >= 2;
+  }
+}

package/test/priority-map-per-output.test.js

@@ -66,7 +66,7 @@ function over(sessions) {
     publish: () => {},
     viewersOf: (session) => viewersOf(session),
     allowanceFor: () => 10,
-    watchedBy: (session, viewer) => live.watchedBy(session, viewer)
+    watchedBy: (session, viewer) => !live.supersededBy(session, viewer.activeVariantId ?? null)
   });
   return {
     priority,
@@ -162,7 +162,7 @@ test("a viewer nothing has been heard from is not watching anything", () => {
     publish: () => {},
     viewersOf: (session) => viewersOf(session),
     allowanceFor: () => 10,
-    watchedBy: (session, viewer) => live.watchedBy(session, viewer)
+    watchedBy: (session, viewer) => !live.supersededBy(session, viewer.activeVariantId ?? null)
   });
   const person = viewers.of(picture, "p");
   person.moveTo(300);
@@ -201,11 +201,11 @@ test("the picture is watched by a person who never moved off it", () => {
   const { viewers, live } = over([picture]);
   const person = viewers.of(picture, "p");
 
-  assert.equal(live.watchedBy(picture, person), true, "no step is active");
+  assert.equal(live.supersededBy(picture, null), false, "no step is active");
   person.activeVariantId = "pic";
   assert.equal(
-    live.watchedBy(picture, person),
-    true,
+    live.supersededBy(picture, person.activeVariantId),
+    false,
     "and naming the picture itself as the step is the same statement"
   );
 });

package/test/quality-variants.test.js

@@ -302,13 +302,13 @@ test("a segment request hands the encoder to the variant the viewer moved to", a
   // handed the whole film's priority map — started it again on the very next
   // pass, which this viewer's own move had just triggered.
   assert.equal(
-    manager.liveOutputs.watchedBy(base, viewerOf(base, "")),
-    false,
+    manager.liveOutputs.supersededBy(base, viewerOf(base, "").activeVariantId),
+    true,
     "the picture they stepped off is nobody's now"
   );
   assert.equal(
-    manager.liveOutputs.watchedBy(variant, viewerOf(variant, "")),
-    true,
+    manager.liveOutputs.supersededBy(variant, viewerOf(variant, "").activeVariantId),
+    false,
     "and the rung they moved to is theirs"
   );
   assert.deepEqual(encoder.signals, [], "stopping it is the plan's, from that fact, and not this path's");