@torrent-tv/proxy 2.85.0 → 2.86.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.86.0
+
+- **Fix**: A LINK READING NO LONGER EXPIRES, and the thirty seconds that made it expire were a chosen number holding two facts at once: how fast the link is, and whether we are still hearing from the page. The speed persists — a link does not stop being what it was measured to be because nobody measured it for a minute, which is why the page keeps its own last figure rather than reporting nothing. It is measured once when the connection comes up and corrected by every transfer after that: one estimate, continuously refined, never a fact with a deadline. Whether a reading is still somebody's is PRESENCE, which has its own owner — a viewer who has gone is removed from the output, so the readings weighed for a decision are only those of people still there.
+- **Chore**: The worst reading across the viewers of one output moved to the viewer's own layer (`services/viewer/link-readings.js`), and skips anybody not present. With the expiry gone, `#linkCouldCarry` no longer takes a clock it cannot use.
+- **Chore**: Where a soundtrack must begin moved out too (`services/viewer/audio-start.js`) — it is a question about where the earliest PERSON stands across every rung of a picture, decided one parameter of an output, and had no business being answered inside the session manager. The manager is 199 lines shorter than before this work for both moves, and every line it gained is an import or a call outward.
+
+## 2.85.1
+
+- **Chore**: NOTHING IS ADDED TO THE SESSION MANAGER, and 2.85.0 added a delegation and an import to it. Both are gone, and what they were there for went with them: taking in a viewer's report is the VIEWER layer's own operation now (`services/viewer/report-intake.js`), the route calls it directly with the live sessions and the registry of viewers, and the manager has no method for it at all. Which output a viewer has on screen moved out with it (`services/viewer/active-output.js`) — it is a question about a person, not about an encoder, and eight call sites now ask it outward.
+- **Chore**: HOW LONG A LINK READING DESCRIBES A LINK is answered by the reading, once (`Viewer.linkReading`). It was a constant in the session manager consulted in four places, and three of those were conditions over a figure that had already passed that very filter — unreachable by construction. Nothing nulls a stale reading any more either: expiry is answered when it is read, so the write that existed only to make a later read correct is gone, and a viewer who has simply stopped reporting is untouched.
+- **Chore**: The session manager is 103 lines shorter for it, and gained one import and eight calls outward.
+
 ## 2.85.0
 
 - **Fix**: A VIEWER WHO HAS SAID NOTHING IS NOT ASSUMED TO BE WATCHING. `playing` started true on a viewer this proxy had never heard from, and the position is carried forward by the clock at that rate — so a page whose tab was hidden for 145 seconds, while it deliberately held start-up until it was shown, was placed **145.979 s** into a film it had not begun. Field 2026-09-14: that is the exact `-ss` the soundtrack's encoder was given, the browser was asking for segment #0, the map ranked #0 last of a hundred (`p1:#0..#13`), and the request was held 60 145 ms and answered 503. The moment the viewer left and the invented clock stopped, the plan asked for exactly the segment they had been asking for all along. A statement about somebody else's machine is theirs to make: until they make it the rate is zero.

package/package.json

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

package/routes/api/transcode-sessions/net-report/post.js

@@ -1,3 +1,5 @@
+import { recordViewerReport } from "../../../../services/viewer/report-intake.js";
+
 /**
  * Accept a viewer link report for a transcode session (adaptive bitrate).
  * The browser measures its own data-channel throughput per segment fetch and
@@ -17,10 +19,13 @@
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @param {{ sessions: { get: (id: string) => object | undefined }, viewers: object }} deps -
+ *   The live sessions and the registry of viewers. The VIEWER layer takes the
+ *   statement from here; this route's whole job is turning a request into that
+ *   one call and its answer into a status code.
  * @returns {Promise<void>}
  */
-export async function handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager }) {
+export async function handleApiTranscodeSessionNetReportPost(req, reply, { sessions, viewers }) {
   const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
   const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
   // WHAT THIS REPORT IS. A statement by one viewer about itself: where the
@@ -66,16 +71,21 @@ export async function handleApiTranscodeSessionNetReportPost(req, reply, { hlsSe
   const inPictureInPicture =
     typeof body.inPictureInPicture === "boolean" ? body.inPictureInPicture : undefined;
   const positionSeconds = Number(body.positionSeconds);
-  const recorded = hlsSessionManager.recordNetReport(sessionId, {
-    linkMbps: Number.isFinite(linkMbps) && linkMbps > 0 ? linkMbps : undefined,
-    waiting,
-    bufferedAheadSec,
-    consumerId,
-    playing,
-    onScreen,
-    inPictureInPicture,
-    positionSeconds:
-      Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
+  const recorded = recordViewerReport({
+    sessions,
+    viewers,
+    sessionId,
+    report: {
+      linkMbps: Number.isFinite(linkMbps) && linkMbps > 0 ? linkMbps : undefined,
+      bufferedAheadSec,
+      consumerId,
+      playing,
+      waiting,
+      onScreen,
+      inPictureInPicture,
+      positionSeconds:
+        Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
+    }
   });
   if (!recorded) {
     return reply.code(404).send({ error: "Transcode session was not found." });

package/server.js

@@ -393,7 +393,13 @@ export async function startProxyServer({
     handleApiTranscodeSessionsProgressGet(req, reply, { hlsSessionManager })
   );
   app.post("/api/transcode-sessions/:sessionId/net-report", async (req, reply) =>
-    handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager })
+    // A viewer's statement about itself goes to the VIEWER layer, not through
+    // the session manager: what it needs is the live sessions and the registry
+    // of viewers, and nothing about encoding.
+    handleApiTranscodeSessionNetReportPost(req, reply, {
+      sessions: hlsSessionManager.sessionsById,
+      viewers: hlsSessionManager.viewers
+    })
   );
   app.post("/api/transcode-sessions/:sessionId/fragment-far", async (req, reply) =>
     handleApiTranscodeSessionFragmentFarPost(req, reply, { hlsSessionManager })

package/services/hls-session-manager.js

@@ -88,8 +88,10 @@ import {
 // — did not move when the code did.
 export { ffmpegSeconds, onKeyframeGridFor, seekLandingOffsetFor, segmentCutTimesFrom };
 import { viewersOf } from "./viewer/Viewer.js";
-import { earliestViewerSecondsOn, viewerSecondsOn, viewerSegmentsOn } from "./viewer/positions.js";
-import { takeViewerReport } from "./viewer/report-intake.js";
+import { activeOutputFor } from "./viewer/active-output.js";
+import { audioStartSecondsFor } from "./viewer/audio-start.js";
+import { worstLinkReading } from "./viewer/link-readings.js";
+import { viewerSecondsOn, viewerSegmentsOn } from "./viewer/positions.js";
 import { Viewers } from "./viewer/Viewers.js";
 import { LiveOutputs } from "./output/LiveOutputs.js";
 import { variantHeightsFor } from "./output/ladder.js";
@@ -524,7 +526,6 @@ const BUDGET_DOWNLOAD_OK_FACTOR = 1.0;
 // instead. Which of the two, and whether a viewer's own pick may be moved at
 // all, is decided where the viewer's choice lives: in the browser, which
 // honours the request only in automatic mode.
-const LINK_REPORT_FRESH_MS = 30_000;
 // Usable share of the reported link (protocol overhead + measurement noise).
 const LINK_SAFETY = 0.8;
 // Deficit must persist this long before acting (absorbs one slow segment).
@@ -3058,36 +3059,6 @@ export class HlsSessionManager {
    *
    * @returns {Promise<void>}
    */
-  /**
-   * Record the latest viewer link report for a session (adaptive bitrate).
-   * Returns false for an unknown/disposed session.
-   *
-   * Kept per viewer. A browser that does not say who it is lands under one
-   * shared key, which is exactly the old behaviour for that browser and no
-   * worse: with one viewer the two are the same thing.
-   *
-   * @param {string} sessionId
-   * @param {{ linkMbps: number, bufferedAheadSec: number, consumerId?: string, positionSeconds?: number }} report
-   * @returns {boolean}
-   */
-  recordNetReport(sessionId, report) {
-    const named = this.sessionsById.get(sessionId);
-    if (!named || named.state === "disposed") {
-      return false;
-    }
-    const consumerId = typeof report?.consumerId === "string" ? report.consumerId : "";
-    return takeViewerReport({
-      viewers: this.viewers,
-      // The stream on screen is the reporter's own: with two viewers on two
-      // rungs, one report says nothing about the other's encoder.
-      session: this.#activeVariant(named, consumerId),
-      consumerId,
-      report,
-      now: Date.now(),
-      linkFreshMs: LINK_REPORT_FRESH_MS
-    });
-  }
-
   /**
    * Record where one viewer of this session is, and answer with the furthest
    * any of them has reached.
@@ -3117,44 +3088,6 @@ export class HlsSessionManager {
     this.viewers.of(session, consumerId).seen();
   }
 
-  /**
-   * The worst of what the viewers of this session report, as one reading.
-   *
-   * The budget asks one question — is anybody failing to keep up — so both
-   * terms are the worst case: the slowest link and the emptiest buffer, which
-   * may belong to different people. That is deliberate. Taking the last report
-   * instead meant a session with two viewers acted on whichever of them
-   * happened to report most recently.
-   *
-   * @param {HlsSession} session
-   * @param {number} now
-   * @returns {{ linkMbps: number, bufferedAheadSec: number, at: number, viewers: number } | null}
-   *   Null when nothing fresh measures the link, which is the silence every
-   *   caller already treats as "no opinion".
-   */
-  #worstNetReport(session, now) {
-    let worst = null;
-    for (const viewer of viewersOf(session).values()) {
-      const report = viewer.netReport;
-      if (report === null || now - report.at > LINK_REPORT_FRESH_MS) {
-        continue;
-      }
-      if (worst === null) {
-        worst = {
-          linkMbps: report.linkMbps,
-          bufferedAheadSec: report.bufferedAheadSec,
-          at: report.at,
-          viewers: 1
-        };
-        continue;
-      }
-      worst.linkMbps = Math.min(worst.linkMbps, report.linkMbps);
-      worst.bufferedAheadSec = Math.min(worst.bufferedAheadSec, report.bufferedAheadSec);
-      worst.at = Math.max(worst.at, report.at);
-      worst.viewers += 1;
-    }
-    return worst;
-  }
 
   /**
    * Answer the player's report that a delivered fragment sits far from the edge
@@ -3186,7 +3119,7 @@ export class HlsSessionManager {
     // run and its own position, and that is exactly the pair this report exists
     // to tell apart. Answering an audio report from the picture's records would
     // state, confidently, something about the wrong stream.
-    const onScreen = this.#activeVariant(named);
+    const onScreen = activeOutputFor({ base: named, sessions: this.sessionsById, viewers: this.viewers });
     const session = track === "audio"
       ? ([...this.liveOutputs.familyOf(onScreen)].find((member) => member.audioOnly === true) ?? onScreen)
       : onScreen;
@@ -3274,9 +3207,9 @@ export class HlsSessionManager {
    * @returns {Promise<boolean>}
    */
   async #checkLinkBudget(session, now) {
-    const report = this.#worstNetReport(session, now);
-    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
-      session.linkSlowSince = 0; // no fresh data — old clients / stopped reporter
+    const report = worstLinkReading(session);
+    if (!report) {
+      session.linkSlowSince = 0; // nobody present has measured their link
       return false;
     }
     if (report.bufferedAheadSec >= LINK_LOW_BUFFER_SEC) {
@@ -4666,7 +4599,7 @@ export class HlsSessionManager {
       }
       return false;
     }
-    const playing = this.liveOutputs.variantHeightOf(this.#activeVariant(base));
+    const playing = this.liveOutputs.variantHeightOf(activeOutputFor({ base, sessions: this.sessionsById, viewers: this.viewers }));
     if (height === playing) {
       return false;
     }
@@ -4720,7 +4653,7 @@ export class HlsSessionManager {
       // top offered height has no next rung at all, and answering "nothing to
       // step to, so yes" is how a cap came off a link measured at a fifth of
       // what the picture needs.
-      if (!this.#linkCouldCarry(session, this.#peakMbpsForHeight(this.liveOutputs.pictureOf(session), current), now)) {
+      if (!this.#linkCouldCarry(session, this.#peakMbpsForHeight(this.liveOutputs.pictureOf(session), current))) {
         return;
       }
       session.budgetUpSince = 0;
@@ -4764,10 +4697,10 @@ export class HlsSessionManager {
     if (session.linkSlowSince !== 0 || session.budgetSlowSince !== 0) {
       return false;
     }
-    const report = this.#worstNetReport(session, now);
-    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
-      // Nothing fresh measures the link, so it has no opinion either way — the
-      // same silence that stops #checkLinkBudget from acting.
+    const report = worstLinkReading(session);
+    if (!report) {
+      // Nothing measures the link, so it has no opinion either way — the same
+      // silence that stops #checkLinkBudget from acting.
       return true;
     }
     const base = this.liveOutputs.pictureOf(session);
@@ -4775,25 +4708,24 @@ export class HlsSessionManager {
     if (next === undefined) {
       return true; // nothing to step to; only the cap decision is left
     }
-    return this.#linkCouldCarry(session, this.#peakMbpsForHeight(base, next), now);
+    return this.#linkCouldCarry(session, this.#peakMbpsForHeight(base, next));
   }
 
   /**
    * Whether the viewer's measured link can carry a given number of Mbit/s.
    *
-   * A link nobody has measured recently has no opinion either way — the same
+   * A link nobody has ever measured has no opinion either way — the same
    * silence that stops `#checkLinkBudget` from acting — so it answers yes.
    *
    * @param {HlsSession} session
    * @param {number} wantedMbps
-   * @param {number} now
    * @returns {boolean}
    */
-  #linkCouldCarry(session, wantedMbps, now) {
+  #linkCouldCarry(session, wantedMbps) {
     // The SLOWEST link among the viewers: a step up has to be carried by all of
     // them, not by whichever reported last.
-    const report = this.#worstNetReport(session, now);
-    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
+    const report = worstLinkReading(session);
+    if (!report) {
       return true;
     }
     return report.linkMbps * LINK_SAFETY >= wantedMbps;
@@ -7167,7 +7099,7 @@ export class HlsSessionManager {
     if (!ask) {
       return 0;
     }
-    if (ask.height === this.liveOutputs.variantHeightOf(this.#activeVariant(base))) {
+    if (ask.height === this.liveOutputs.variantHeightOf(activeOutputFor({ base, sessions: this.sessionsById, viewers: this.viewers }))) {
       base.qualityAsk = null; // the viewer is there; nothing left to ask for
       return 0;
     }
@@ -7182,45 +7114,6 @@ export class HlsSessionManager {
     return ask.height;
   }
 
-  /**
-   * The variant of a session that the viewer is watching right now.
-   *
-   * Every request that names the base session — seek, progress, link report,
-   * release — means the stream the viewer has on screen, and after a quality
-   * change that is another session. The browser is not told about the swap: it
-   * holds one session id for the whole file, which is what keeps the switch out
-   * of the state machine on that side.
-   *
-   * Kept per viewer, because one picture is shared by everyone watching it and
-   * a quality step is a session of its own: with one answer for the session, a
-   * step taken by one viewer would move the other one's stream, and that
-   * viewer's next seek would be forwarded to a rung they never chose. The
-   * session's own field remains the answer for a viewer who cannot name
-   * themselves, and the last one anybody moved to.
-   *
-   * @param {HlsSession} base
-   * @param {string} [consumerId]
-   * @returns {HlsSession}
-   */
-  #activeVariant(base, consumerId = "") {
-    const named = consumerId ? base.viewers?.get(consumerId)?.activeVariantId ?? null : null;
-    const activeId = named ?? base.activeVariantId;
-    if (!activeId || activeId === base.id) {
-      return base;
-    }
-    const active = this.sessionsById.get(activeId);
-    if (!active || active.state === "disposed") {
-      if (named) {
-        this.viewers.of(base, consumerId).activeVariantId = null;
-      }
-      if (base.activeVariantId === activeId) {
-        base.activeVariantId = base.id;
-      }
-      return base;
-    }
-    return active;
-  }
-
   /**
    * Every session of this family that a live viewer has on screen.
    *
@@ -7245,7 +7138,7 @@ export class HlsSessionManager {
       onScreen.add(viewer.activeVariantId);
     }
     if (onScreen.size === 0) {
-      onScreen.add(this.#activeVariant(base).id);
+      onScreen.add(activeOutputFor({ base, sessions: this.sessionsById, viewers: this.viewers }).id);
     }
     return onScreen;
   }
@@ -7278,7 +7171,7 @@ export class HlsSessionManager {
     if (Number.isInteger(wantedIndex) && wantedIndex >= 0) {
       return this.#segmentStartTime(base, wantedIndex);
     }
-    return viewerSecondsOn(this.#activeVariant(base, consumerId));
+    return viewerSecondsOn(activeOutputFor({ base, consumerId, sessions: this.sessionsById, viewers: this.viewers }));
   }
 
   /**
@@ -7350,54 +7243,6 @@ export class HlsSessionManager {
     return { earliestPosition, deepestBuffer, viewers };
   }
 
-  /**
-   * Where a soundtrack must begin: at the earliest film anybody is waiting on.
-   *
-   * ASKED OF THE MAP, NOT OF A VIEWER. Sound is produced for the same reason a
-   * picture is, and the map already states it — in seconds of film, merged over
-   * everybody watching, with the map's own order saying which of them is
-   * earliest. Reading it off a viewer put a person inside the encoding layer,
-   * and then every question about WHICH person had to be answered a second time
-   * here: the earliest of two, the one on this rung, the one who has not
-   * reported yet.
-   *
-   * The apparatus this replaced is worth naming so it is not rebuilt: three
-   * position sources ranked by priority, a function saying which had answered,
-   * a subtraction of the deepest reported buffer, and a special case for a
-   * session nobody had asked anything of. Each repaired a quantity that meant
-   * two things. It means one thing now.
-   *
-   * One segment back, and that is not a margin: a cut grid places the
-   * soundtrack's own boundaries where it will, so the piece holding a moment of
-   * film begins at or before it.
-   *
-   * @param {HlsSession} base
-   * @returns {number} Seconds.
-   */
-  #audioStartSecondsFor(base) {
-    // WHERE THE EARLIEST OF THEM STANDS, across every rung of this picture. A
-    // track begun at the leader has nothing to give the viewer behind them, and
-    // two viewers of one film may be on different rungs.
-    //
-    // NO SUBTRACTION, and that is the whole of the change. A viewer's position
-    // is where their PICTURE is, so the sound belongs exactly there — while the
-    // apparatus this replaced turned a request edge back into a playhead with
-    // three ranked sources, a name for which had answered, a subtraction of the
-    // deepest reported buffer, and a special case for a session nobody had
-    // asked anything of. Field 2026-08-31: a page opened at 588 s started its
-    // sound at 460 s, 131 seconds nobody would hear
-    // (`research/cold-open-audio-start-2026-08-31.md`).
-    //
-    // A fact about people, deciding one parameter of an output. It places no
-    // encoder: where an encoder works is the priority map's answer.
-    const earliest = earliestViewerSecondsOn(this.liveOutputs.familyOf(base));
-    const opened = Number(base.progress?.startPositionSeconds);
-    const from = earliest ?? (Number.isFinite(opened) ? opened : 0);
-    // One segment back, and that is not a margin: a cut grid places the
-    // soundtrack's own boundaries where it will, so the piece holding a moment
-    // of film begins at or before it.
-    return Math.max(0, from - this.segmentDurationSec);
-  }
 
 
   /**
@@ -7883,7 +7728,7 @@ export class HlsSessionManager {
     // buys it an encoder, and both halves are said here: a warmed rung is one
     // this person is watching for as long as the warm-up lasts, which is why
     // two encoders run through it.
-    if (variant.id !== this.#activeVariant(base, consumerId).id) {
+    if (variant.id !== activeOutputFor({ base, consumerId, sessions: this.sessionsById, viewers: this.viewers }).id) {
       this.viewers.of(variant, consumerId).moveTo(this.#segmentStartTime(base, index));
       this.planEncodersSoon();
     }
@@ -7908,7 +7753,7 @@ export class HlsSessionManager {
    * @returns {void}
    */
   #noteVariantActive(base, variant, wantedIndex = -1, consumerId = "") {
-    const previous = this.#activeVariant(base, consumerId);
+    const previous = activeOutputFor({ base, consumerId, sessions: this.sessionsById, viewers: this.viewers });
     if (previous.id === variant.id) {
       // The rung on screen asking for more of itself, which it does every few
       // seconds. Nothing is being decided here — and deciding anything was the
@@ -8333,7 +8178,11 @@ export class HlsSessionManager {
       // who seeked since then is somewhere else entirely — so an old one is
       // ignored and the whole look-ahead is subtracted instead, which cannot
       // leave the run ahead of them.
-      startPositionSeconds: this.#audioStartSecondsFor(base),
+      startPositionSeconds: audioStartSecondsFor({
+        family: this.liveOutputs.familyOf(base),
+        openedAtSeconds: base.progress?.startPositionSeconds,
+        segmentSeconds: this.segmentDurationSec
+      }),
       segmentFormatId: base.segmentFormat.id,
       // Cut where the picture is cut. Two streams meant to be played together
       // have to be divided at the same times, and the grid is the base's — the
@@ -9431,7 +9280,7 @@ export class HlsSessionManager {
     // change is another session. Touching the named one as well is what keeps
     // the family alive: only the ACTIVE variant gets segment requests, so
     // without this the base session would idle out from under its own variants.
-    const session = this.#activeVariant(named, consumerId);
+    const session = activeOutputFor({ base: named, consumerId, sessions: this.sessionsById, viewers: this.viewers });
     session.lastAccessedAt = Date.now();
     const warmupTotalSeconds = this.startupWaitMs / 1000;
     const warmupElapsedSeconds = Math.max(0, (Date.now() - session.startedAt) / 1000);

package/services/viewer/Viewer.js

@@ -321,6 +321,34 @@ export class Viewer {
    *
    * @returns {boolean}
    */
+  /**
+   * What this viewer's link was last measured to carry, or null when it has
+   * never been measured.
+   *
+   * IT DOES NOT EXPIRE, and the reasoning is the correction of 2026-09-14. A
+   * reading older than a chosen thirty seconds used to be discarded here, which
+   * put two facts under one number: how fast the link is, and whether we are
+   * still hearing from this page.
+   *
+   * The speed persists. A link does not stop being what it was measured to be
+   * because nobody measured it for a minute, and the page says as much by
+   * keeping its own last figure for ever rather than reporting nothing. It is
+   * measured once when the connection comes up and corrected by every transfer
+   * afterwards — one estimate, continuously refined, never a fact with a
+   * deadline.
+   *
+   * Whether the reading is still somebody's is PRESENCE, which has its own
+   * owner: a viewer who has gone is removed from the output, and the readings
+   * walked for a decision are only those of people still there. Answering both
+   * questions in one place is what stopped a soundtrack's encoder on
+   * 2026-09-05.
+   *
+   * @returns {{ linkMbps: number, bufferedAheadSec: number, positionSeconds: number | null, at: number } | null}
+   */
+  linkReading() {
+    return this.netReport;
+  }
+
   /**
    * Whether this viewer wants film NOW — either watching it or waiting for it.
    *

package/services/viewer/active-output.js

@@ -0,0 +1,54 @@
+/**
+ * @file Which output a viewer has on screen.
+ *
+ * Every request that names the picture's session — a seek, a progress poll, a
+ * link report, a release — means the stream the viewer is actually watching,
+ * and after a quality change that is another session. The browser is never told
+ * about the swap: it holds one session id for the whole file, which is what
+ * keeps the switch out of the state machine on that side.
+ *
+ * KEPT PER VIEWER, because one picture is shared by everyone watching it and a
+ * quality step is a session of its own. With one answer for the session, a step
+ * taken by one viewer moved the other one's stream, and that viewer's next seek
+ * was forwarded to a rung they never chose. The session's own field remains the
+ * answer for a viewer who cannot name themselves, and is the last rung anybody
+ * moved to.
+ *
+ * It is handed the picture, a name, the live sessions and the registry of
+ * viewers, and it HOLDS none of them — but it is not read-only: finding a rung
+ * that has been disposed, it puts both remembers back on the picture, or the
+ * next question gets the same dead answer. It lives in the VIEWER layer because
+ * the question is about a person — which of several equally live outputs is
+ * theirs — and it knows nothing of encoders, files or heights.
+ */
+
+/**
+ * @param {object} params
+ * @param {object} params.base - The picture's own session.
+ * @param {string} [params.consumerId] - Whose screen. Empty asks about the
+ *   session's own last answer, which is what an unnamed browser gets.
+ * @param {{ get: (id: string) => object | undefined }} params.sessions - Every live session, by id.
+ * @param {{ of: (session: object, consumerId: string) => { activeVariantId: string | null } }} params.viewers
+ * @returns {object} A live session, never a disposed one.
+ */
+export function activeOutputFor({ base, consumerId = "", sessions, viewers }) {
+  const named = consumerId ? base.viewers?.get(consumerId)?.activeVariantId ?? null : null;
+  const activeId = named ?? base.activeVariantId;
+  if (!activeId || activeId === base.id) {
+    return base;
+  }
+  const active = sessions.get(activeId);
+  if (!active || active.state === "disposed") {
+    // The rung is gone, so the viewer is watching the picture again. Said in
+    // both places that remember it, or the next question gets the same dead
+    // answer.
+    if (named) {
+      viewers.of(base, consumerId).activeVariantId = null;
+    }
+    if (base.activeVariantId === activeId) {
+      base.activeVariantId = base.id;
+    }
+    return base;
+  }
+  return active;
+}

package/services/viewer/audio-start.js

@@ -0,0 +1,45 @@
+/**
+ * @file Where a soundtrack must begin.
+ *
+ * ASKED OF THE PEOPLE, NOT OF A SESSION. Sound is produced for the same reason
+ * a picture is — somebody is going to hear it — so the question is where the
+ * earliest of them stands, across every rung of that picture: a track begun at
+ * the leader has nothing to give the viewer behind them, and two viewers of one
+ * film may be watching at different qualities.
+ *
+ * NO SUBTRACTION, and that is the whole of what this replaced: three position
+ * sources ranked by priority, a second function naming which had answered, a
+ * subtraction of the deepest reported buffer, and a special case for a session
+ * nobody had asked anything of. Each repaired a quantity that meant two things.
+ * A viewer's position is where their PICTURE is, so the sound belongs exactly
+ * there. Field 2026-08-31, what the subtraction cost: a page opened at 588 s
+ * started its sound at 460 s — 131 seconds nobody would hear
+ * (`research/cold-open-audio-start-2026-08-31.md`).
+ *
+ * It decides ONE PARAMETER of an output and places no encoder: where an encoder
+ * works is the priority map's answer. Pure over plain values — the outputs of
+ * one picture, where it was opened, and how long a piece is — so it knows
+ * nothing of ffmpeg, cut grids or the disk.
+ */
+
+import { earliestViewerSecondsOn } from "./positions.js";
+
+/**
+ * @param {object} params
+ * @param {Iterable<object>} params.family - Every output of one picture: the
+ *   picture itself and its quality steps. The viewers are spread across them.
+ * @param {number} params.openedAtSeconds - Where the picture was opened, which
+ *   is the answer while nobody has stated a position yet.
+ * @param {number} params.segmentSeconds - How long one piece is.
+ * @returns {number} Seconds, never negative.
+ */
+export function audioStartSecondsFor({ family, openedAtSeconds, segmentSeconds }) {
+  const earliest = earliestViewerSecondsOn(family);
+  const opened = Number(openedAtSeconds);
+  const from = earliest ?? (Number.isFinite(opened) ? opened : 0);
+  // ONE PIECE BACK, and that is not a margin: a cut grid places the
+  // soundtrack's own boundaries where it will, so the piece holding a moment of
+  // film begins at or before it.
+  const back = Number.isFinite(segmentSeconds) && segmentSeconds > 0 ? segmentSeconds : 0;
+  return Math.max(0, from - back);
+}

package/services/viewer/link-readings.js

@@ -0,0 +1,56 @@
+/**
+ * @file What the viewers of one output say about their links, as one reading.
+ *
+ * The budget asks one question — is anybody failing to keep up — so both terms
+ * are the worst case: the slowest link and the emptiest buffer, which may
+ * belong to different people. Taking the last report instead meant a session
+ * with two viewers acted on whichever of them happened to report most recently.
+ *
+ * NOTHING HERE EXPIRES, and that is the correction of 2026-09-14. A reading
+ * used to be discarded once it was older than a chosen thirty seconds, which
+ * conflated two facts under one number: how fast the link is, and whether we
+ * are still hearing from the page. The first persists — a link does not stop
+ * being what it was measured to be because nobody measured it for a minute,
+ * which is why the page itself keeps its last figure for ever. The second is
+ * PRESENCE, and presence has its own owner: a viewer who has gone is removed
+ * from the output, so what is walked here is only people who are still here.
+ *
+ * The reading is corrected continuously while material crosses the link, which
+ * is the whole shape: measured once when the connection comes up, corrected by
+ * every transfer after it.
+ */
+
+import { viewersOf } from "./Viewer.js";
+
+/**
+ * @param {object} output - The session whose viewers are asked.
+ * @returns {{ linkMbps: number, bufferedAheadSec: number, at: number, viewers: number } | null}
+ *   Null when nobody present has ever measured their link, which every caller
+ *   already treats as "no opinion either way".
+ */
+export function worstLinkReading(output) {
+  let worst = null;
+  for (const viewer of viewersOf(output).values()) {
+    if (!viewer.isPresent()) {
+      continue;
+    }
+    const reading = viewer.linkReading();
+    if (reading === null) {
+      continue;
+    }
+    if (worst === null) {
+      worst = {
+        linkMbps: reading.linkMbps,
+        bufferedAheadSec: reading.bufferedAheadSec,
+        at: reading.at,
+        viewers: 1
+      };
+      continue;
+    }
+    worst.linkMbps = Math.min(worst.linkMbps, reading.linkMbps);
+    worst.bufferedAheadSec = Math.min(worst.bufferedAheadSec, reading.bufferedAheadSec);
+    worst.at = Math.max(worst.at, reading.at);
+    worst.viewers += 1;
+  }
+  return worst;
+}