@torrent-tv/proxy 2.107.56 → 2.107.58

package/services/encode/EncodeInputResolution.js

@@ -0,0 +1,157 @@
+/**
+ * @file What an encoder run reads: the input of a piece's run and the sound's
+ * packets walked from the picture's copy. Moved from the composition root
+ * (torrent-tv/meta#275, step 5 of #270); every collaborator is a port, so this
+ * file imports nothing.
+ */
+
+export class EncodeInputResolution {
+  #paramsFor;
+  #sourceRanges;
+  #selectTracks;
+  #readingInterval;
+  #trackFor;
+  #declaredTracks;
+  #known;
+  #outputs;
+  #log;
+  #warn;
+  #now;
+
+  /**
+   * @param {object} ports
+   * @param {(request: object) => Promise<object | null>} ports.paramsFor MediaReadParams#paramsFor
+   * @param {object} ports.sourceRanges SegmentSourceRanges (tracksOf, shiftOf, navigable, readInput)
+   * @param {Function} ports.selectTracks segment-reading
+   * @param {Function} ports.readingInterval segment-reading
+   * @param {Function} ports.trackFor segment-reading
+   * @param {(sourceKey: string, fileIndex: number) => object[] | undefined} ports.declaredTracks
+   * @param {(sourceKey: string, fileIndex: number) => object | null | undefined} ports.known
+   * @param {() => Iterable<object>} ports.outputs the output catalog's values
+   * @param {(line: string) => void} ports.log
+   * @param {(line: string) => void} ports.warn
+   * @param {() => number} [ports.now]
+   */
+  constructor({ paramsFor, sourceRanges, selectTracks, readingInterval, trackFor, declaredTracks, known, outputs, log, warn, now = Date.now }) {
+    this.#paramsFor = paramsFor;
+    this.#sourceRanges = sourceRanges;
+    this.#selectTracks = selectTracks;
+    this.#readingInterval = readingInterval;
+    this.#trackFor = trackFor;
+    this.#declaredTracks = declaredTracks;
+    this.#known = known;
+    this.#outputs = outputs;
+    this.#log = log;
+    this.#warn = warn;
+    this.#now = now;
+  }
+
+  // `timing`, when given, is told how long each read of a file waited behind
+  // the reads asked before it and how long it took (torrent-tv/meta#166).
+  async resolve(output, fromIndex, toIndex, timing = null, isCurrent = null, signal = null, readPriority = null) {
+    const grid = output.timeline?.published ?? output.timeline?.boundaries;
+    const from = grid?.[fromIndex], to = grid?.[toIndex + 1];
+    if (!Number.isFinite(from) || !(to > from)) return { kind: "terminal", reason: "output-interval-not-declared" };
+    const selected = new Map();
+    for (const type of ["video", "audio"]) {
+      const spec = output.spec[type];
+      if (!spec) continue;
+      const list = selected.get(spec.fileIndex) ?? [];
+      list.push({ type, index: type === "video" ? null : spec.trackIndex,
+        mode: type === "video" ? spec.encode ? "transcode" : "copy" : spec.transcode ? "transcode" : "copy" });
+      selected.set(spec.fileIndex, list);
+    }
+    // Every selected file is read the same way in one run: from the original
+    // file when each container can name the bytes the interval needs, from
+    // reassembled packets otherwise.
+    const files = [];
+    for (const [fileIndex, choices] of selected) {
+      const params = await this.#paramsFor({ sourceKey: output.file.sourceKey, fileIndex,
+        requestId: readPriority?.requestId, readPriority, signal });
+      if (!params) return { kind: "needs-source" };
+      if (isCurrent) params.isCurrent = isCurrent;
+      if (signal) params.signal = signal;
+      if (timing) {
+        params.walkAccount = timing.walk ??= { lockMs: 0, reads: 0, bytes: 0 };
+        params.onTimed = (statement, waitedMs, readMs) => {
+          timing.reads += 1;
+          timing.queuedMs += waitedMs;
+          timing.readMs += readMs;
+          const measured = timing.readsByStatement[statement] ??= { queuedMs: 0, readMs: 0 };
+          measured.queuedMs += waitedMs;
+          measured.readMs += readMs;
+        };
+      }
+      const tracks = await this.#sourceRanges.tracksOf(params);
+      if (tracks.kind !== "result") return tracks;
+      const selection = this.#selectTracks(tracks.trackList, choices);
+      if (!selection) return { kind: "terminal", reason: "selected-track-is-absent" };
+      const { wanted, modes } = selection;
+      const media = await this.#sourceRanges.shiftOf(params);
+      if (media.kind !== "result") return media;
+      const timeShiftSeconds = media.shift;
+      const sourceInterval = output.timeline.sourceInterval(fromIndex, toIndex, timeShiftSeconds);
+      params.packetInterval = this.#readingInterval(selection, sourceInterval);
+      const navigation = await this.#sourceRanges.navigable(params);
+      if (navigation.kind !== "result") return navigation;
+      files.push({ fileIndex, choices, params, wanted, modes, timeShiftSeconds, sourceInterval, navigable: navigation.value });
+    }
+    const original = output.segmentFormat.supportsOriginalInput === true && files.every(file => file.navigable);
+    const sources = [];
+    for (const { fileIndex, choices, params, wanted, modes, timeShiftSeconds, sourceInterval } of files) {
+      const read = await this.#sourceRanges.readInput(params, { original, tracks: wanted, modes, interval: sourceInterval });
+      if (read.kind !== "result") return read.answer;
+      if (original) {
+        sources.push({ sourceKey: params.sourceKey, fileIndex, timeShiftSeconds,
+          input: { ...read.input, original: true, selections: wanted.map(track => ({ track,
+            index: track.declaredIndex ?? choices.find(choice => choice.type === track.type)?.index ?? 0 })) } });
+        continue;
+      }
+      sources.push({ sourceKey: params.sourceKey, fileIndex, input: read.input, timeShiftSeconds });
+    }
+    return { kind: "result", sources };
+  }
+
+  // THE SOUND'S PACKETS FROM THE PICTURE'S COPY. A Matroska soundtrack is
+  // fed to its encoder packet by packet, and finding its packets walks the
+  // clusters the Cues name for the piece — picture and sound together,
+  // about 20 MB for 0.3 MB of sound on the field's 1080p film. The picture's
+  // input copies those same clusters through the torrent thread first, and
+  // walked a second time there each soundtrack piece took 6-11 s, slower
+  // than the film plays (r61, torrent-tv/meta#178). Walked from the copy
+  // while it is held, the sound reads only its own packets later.
+  stretchCopied(output, from, to, input) {
+    for (const source of input.sources ?? []) {
+      const container = this.#known(source.sourceKey, source.fileIndex);
+      const tracks = this.#declaredTracks(source.sourceKey, source.fileIndex);
+      if (typeof container?.learnPackets !== "function" || !Array.isArray(tracks)) continue;
+      const carried = new Set((source.input.selections ?? []).map(selection => selection.track?.trackNumber));
+      const sounds = new Set();
+      for (const other of this.#outputs()) {
+        const sound = other.spec?.audio;
+        if (other.spec?.video || !sound || other.file?.sourceKey !== source.sourceKey || sound.fileIndex !== source.fileIndex) continue;
+        const track = this.#trackFor(tracks, { type: "audio", index: sound.trackIndex });
+        if (track && !carried.has(track.trackNumber)) sounds.add(track.trackNumber);
+      }
+      if (!sounds.size || !Number.isFinite(source.input.from) || !(source.input.to > source.input.from)) continue;
+      const read = (start, end) => {
+        const answer = input.read(source.fileIndex, start, end);
+        return answer && typeof answer.then !== "function" && answer.end === end ? answer.bytes : null;
+      };
+      const holdsUntil = start => {
+        if (input.heldUntil) return input.heldUntil(source.fileIndex, start);
+        const range = source.input.ranges.find(([first, last]) => first <= start && start <= last);
+        return range ? range[1] + 1 : null;
+      };
+      const startedAt = this.#now();
+      const releaseInput = input.retain?.();
+      void container.learnPackets({ from: source.input.from, to: source.input.to, trackIds: [...sounds] }, read, holdsUntil).then(learned =>
+        this.#log(`encode input #${from}..#${to} of ${output.outputKey}: soundtrack packets of track(s) ${[...sounds].join(",")} ` +
+          `over ${source.input.from.toFixed(3)}-${source.input.to.toFixed(3)}s ` +
+          (learned === "walked" ? "walked" : `not all walked (${learned === "memory" ? "memory refused" : "the copy does not hold the rest"})`) +
+          ` from its copy in ${this.#now() - startedAt}ms`),
+      error => this.#warn(`encode input #${from}..#${to} of ${output.outputKey}: walking the soundtrack from its copy failed: ${error?.message ?? error}`))
+        .finally(() => releaseInput?.());
+    }
+  }
+}

package/services/encode/LocalObservations.js

@@ -48,6 +48,19 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { configurationKeyOf, kindOfEncoderName } from "./fingerprint.js";
 
+/**
+ * The writer used when none is handed in (a check that only wants the file).
+ * The proxy always hands in the atomic one from `utils/atomic-json.js`, which
+ * this layer may not import.
+ *
+ * @param {string} filePath
+ * @param {unknown} value
+ * @returns {void}
+ */
+function writeInPlace(filePath, value) {
+  writeFileSync(filePath, JSON.stringify(value));
+}
+
 /**
  * The directory of the installed proxy, where these observations are kept when
  * the deployment names no state directory. Deliberately not the working
@@ -84,6 +97,8 @@ export class LocalObservations {
 
   /** @type {{ info: (m: string) => void, warn: (m: string) => void }} */
   #logger;
+  /** @type {(filePath: string, value: unknown) => void} */
+  #writeJson;
 
   /** @type {() => number} */
   #now;
@@ -99,16 +114,19 @@ export class LocalObservations {
    * @param {import("./fingerprint.js").HostFingerprint} params.fingerprint
    * @param {string} params.filePath - Where the readings are kept; empty keeps
    *   them for this process only.
+   * @param {(filePath: string, value: unknown) => void} [params.writeJson] - How
+   *   the file is saved; throws on failure. The atomic writer is handed in.
    * @param {{ info: (m: string) => void, warn: (m: string) => void }} [params.logger]
    * @param {() => number} [params.now]
    */
-  constructor({ fingerprint, filePath, logger = null, now = Date.now }) {
+  constructor({ fingerprint, filePath, writeJson = writeInPlace, logger = null, now = Date.now }) {
     if (!fingerprint || typeof fingerprint !== "object") {
       throw new TypeError("LocalObservations requires the host's fingerprint");
     }
     this.#fingerprint = fingerprint;
     this.#filePath = typeof filePath === "string" ? filePath : "";
     this.#logger = logger ?? { info: () => {}, warn: () => {} };
+    this.#writeJson = writeJson;
     this.#now = now;
   }
 
@@ -367,7 +385,7 @@ export class LocalObservations {
       return;
     }
     try {
-      writeFileSync(this.#filePath, JSON.stringify({ version: FILE_VERSION, entries: this.#entries }));
+      this.#writeJson(this.#filePath, { version: FILE_VERSION, entries: this.#entries });
     } catch (error) {
       // A read-only install keeps what it learned for this process only.
       this.#logger.warn(

package/services/encode/measure-host.js

@@ -0,0 +1,147 @@
+/**
+ * @file What this host does, measured once at startup before any viewer
+ * exists: the encoder, what decoding and a second job cost, the calibrated
+ * modes, the copy speed, audio, a start and a stop, and tone-mapping.
+ *
+ * Moved out of `server.js` verbatim (torrent-tv/meta#280): the same awaits in
+ * the same order. `measures` defaults to the real functions; a test passes
+ * fakes so that no ffmpeg runs.
+ */
+
+import {
+  detectVideoEncoder,
+  benchmarkDecodeCost,
+  benchmarkContention,
+  benchmarkCopySpeed,
+  detectTonemapSupport,
+  softwareDescriptor
+} from "./hwaccel.js";
+import { calibrateEncoder, HostCalibration } from "./calibration.js";
+import { readHostFingerprint } from "./fingerprint.js";
+import { measureStartAndStop } from "./start-stop-cost.js";
+import { benchmarkAudio } from "./audio-calibration.js";
+
+const DEFAULT_MEASURES = {
+  detectVideoEncoder,
+  benchmarkDecodeCost,
+  benchmarkContention,
+  readHostFingerprint,
+  calibrateEncoder,
+  softwareDescriptor,
+  benchmarkCopySpeed,
+  benchmarkAudio,
+  measureStartAndStop,
+  detectTonemapSupport
+};
+
+/**
+ * @param {object} params
+ * @param {string} params.ffmpegBin
+ * @param {{ info: Function, warn: Function }} params.logger
+ * @param {boolean} params.transcode - Whether transcoding can occur; false measures nothing.
+ * @param {number} params.processorCores - The cores this process may use (a container's quota or CPU set).
+ * @param {typeof DEFAULT_MEASURES} [params.measures]
+ */
+export async function measureHost({ ffmpegBin, logger, transcode, processorCores, measures = DEFAULT_MEASURES }) {
+  const {
+    detectVideoEncoder, benchmarkDecodeCost, benchmarkContention, readHostFingerprint, calibrateEncoder,
+    softwareDescriptor, benchmarkCopySpeed, benchmarkAudio, measureStartAndStop, detectTonemapSupport
+  } = measures;
+    // Auto-detect the best available H.264 encoder (hardware-accelerated or
+    // software) once at startup, with a real test-encode and graceful fallback.
+    // Only needed when transcoding can occur.
+    let videoEncoder = transcode
+      ? await detectVideoEncoder({ ffmpegBin, logger })
+      : null;
+    // WHAT THIS HOST DOES, measured before any viewer exists. Every one of these
+    // was gated on the chosen encoder being SOFTWARE, and two of the three are
+    // not about the encoder at all: a host with a GPU decodes in software just
+    // the same — no hardware decoder is asked for anywhere — and what a second
+    // job costs is a property of the machine. So a GPU host had no decode cost,
+    // no contention penalty and no encoder throughput, and the quality offer,
+    // which is arithmetic over those three, had nothing to compute from.
+    //
+    // The decode model first and the throughput second — they are independent
+    // (the rungs are timed on raw frames), but the order keeps the two figures
+    // side by side in the log.
+    const decodeCostModel = transcode
+      ? await benchmarkDecodeCost({ ffmpegBin, logger, processorCores })
+      : null;
+    // What a second job costs on this host. Measured because the budget adds
+    // independent prices and this host says two jobs that each fit alone do not
+    // fit together — 2.6× on the addon box (2026-08-18).
+    const contentionPenalties = transcode
+      ? await benchmarkContention({ ffmpegBin, logger })
+      : null;
+    // WHICH MODES THIS HOST MAY ENCODE WITH, AND WHAT EACH COSTS AT EVERY SIZE
+    // (roadmap item 97, step 14). Every setting an output can actually be
+    // encoded at is put through the product's own arguments and its segments
+    // decoded, then timed at the sizes of the ladder; a mode that fails either is
+    // not used, and a size nothing was timed at is not offered. Software is
+    // calibrated too when detection chose a device: it is what a failing device
+    // falls back to for the rest of the process, and it must not be priced by
+    // the device's figures.
+    //
+    // And WHICH CONFIGURATION all of it describes — the ffmpeg and x264 builds,
+    // the processor and the threads, the device and its driver — which is what
+    // decides whether anything kept from an earlier run still applies.
+    const fingerprint = videoEncoder
+      ? await readHostFingerprint({ ffmpegBin, encoder: videoEncoder, processorCores })
+      : null;
+    /** @type {Record<string, object[]>} */
+    const calibratedModes = {};
+    if (videoEncoder) {
+      const selectedCalibration = await calibrateEncoder({ ffmpegBin, encoder: videoEncoder, logger, processorCores });
+      if (selectedCalibration.assessmentComplete) {
+        calibratedModes[videoEncoder.kind] = selectedCalibration.modes;
+      }
+      if (videoEncoder.kind !== "software") {
+        const softwareCalibration = await calibrateEncoder({ ffmpegBin, encoder: softwareDescriptor(), logger, processorCores });
+        if (softwareCalibration.assessmentComplete) {
+          calibratedModes.software = softwareCalibration.modes;
+        }
+        // A device that passed detection's own test and then none of whose modes
+        // passed the product's is not used: detection encodes a synthetic pattern
+        // with arguments of its own, and it is the product's arguments a viewer
+        // is served with.
+        if (Array.isArray(calibratedModes[videoEncoder.kind]) && calibratedModes[videoEncoder.kind].length === 0) {
+          logger.warn(
+            `calibration: ${videoEncoder.name} passed detection but none of its modes produced correct segments ` +
+            "through the product's own arguments; encoding in software instead"
+          );
+          videoEncoder = softwareDescriptor();
+        }
+      }
+    }
+    const calibration = videoEncoder ? new HostCalibration({ byKind: calibratedModes, fingerprint }) : null;
+    // What this host does with a picture it does NOT re-encode. Every other
+    // startup measurement prices encoding or decoding, and a copied picture does
+    // neither — it reads packets and writes them out again — so that whole branch
+    // had no speed until its own run had been running long enough to report one.
+    // The encoding layer decides where encoders go from arrivals, and an arrival
+    // cannot be computed without a speed, so the moment it mattered most was the
+    // moment nothing was known. Measured whatever the encoder is: copying does not
+    // touch it.
+    const copySpeedX = transcode
+      ? await benchmarkCopySpeed({ ffmpegBin, logger })
+      : null;
+    const audioCalibration = transcode
+      ? await benchmarkAudio({ ffmpegBin, logger })
+      : [];
+    // WHAT A START AND A STOP COST HERE, before any viewer exists. Both decide one
+    // thing — leave an encoder where it stands, or kill it and start another —
+    // and both used to be learned only from runs that had ENDED, so at a cold
+    // open they were zero. Zero does not read as "not measured": it reads as
+    // "free", and a free move is always taken. Field 2026-09-08: an encoder moved
+    // between two adjacent numbers every half second and produced nothing.
+    const startStopCost = transcode
+      ? await measureStartAndStop({ ffmpegBin, encoder: videoEncoder, logger })
+      : null;
+    // Whether this ffmpeg build can tone-map HDR→SDR (zscale + tonemap filters).
+    // Detected once; the session manager applies the tonemap chain only for HDR
+    // sources on the software path when available.
+    const tonemapSupported = transcode
+      ? await detectTonemapSupport({ ffmpegBin, logger })
+      : false;
+  return { videoEncoder, decodeCostModel, contentionPenalties, calibration, copySpeedX, audioCalibration, startStopCost, tonemapSupported };
+}

package/services/identity/installation-id.js

@@ -1,9 +1,14 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { writeJsonAtomic } from "../../utils/atomic-json.js";
+import { logger } from "../../utils/logger.js";
 
 const ID_FILE = "proxy-identity.json";
 
+/** Ids that could not be written, by identity file: kept so the process keeps one id. */
+const unsavedIds = new Map();
+
 /**
  * Resolve this installation's registry id. Without a state directory the id
  * remains ephemeral; with one, the id survives process restarts.
@@ -27,12 +32,18 @@ export function installationId({ stateDir, explicitId, makeId = randomUUID } = {
     }
   }
 
-  const id = requestedId || savedId || makeId();
+  const id = requestedId || savedId || unsavedIds.get(file) || makeId();
   if (id !== savedId) {
-    mkdirSync(stateDir, { recursive: true });
-    const temporary = `${file}.${process.pid}.tmp`;
-    writeFileSync(temporary, `${JSON.stringify({ id })}\n`, { mode: 0o600 });
-    renameSync(temporary, file);
+    try {
+      mkdirSync(stateDir, { recursive: true });
+      writeJsonAtomic(file, { id }, { mode: 0o600 });
+      unsavedIds.delete(file);
+    } catch (error) {
+      if (unsavedIds.get(file) !== id) {
+        logger.warn(`Cannot save the proxy identity file ${file} (${error.message}); the installation id lasts only until this process exits`);
+      }
+      unsavedIds.set(file, id);
+    }
   }
   return id;
 }

package/services/media/SegmentSourceRanges.js

@@ -0,0 +1,95 @@
+/**
+ * @file One resolver of a segment's source byte ranges (torrent-tv/meta#272).
+ *
+ * The chain tracks, media-info, source-navigation, then the direct index, the
+ * container's source ranges or its packets, with the cache of what was worked
+ * out, was in `server.js` and repeated by the encoder's input. The method names
+ * are those of wait-trace P4.1.
+ */
+import { directSegmentInput } from "./direct-segment-input.js";
+import { SegmentInputs } from "./SegmentInputs.js";
+
+const FALLBACK = "container-index-fallback";
+
+export class SegmentSourceRanges {
+  /** @type {Map<string, Array<[number, number]>>} */
+  #ranges = new Map();
+  #orchestrator;
+
+  /** @param {{ orchestrator: { inspect(params: object, statement: string): Promise<object>, known(sourceKey: string, fileIndex: number): object | null | undefined } }} ports */
+  constructor({ orchestrator }) {
+    this.#orchestrator = orchestrator;
+  }
+
+  keyOf(sourceKey, fileIndex, interval) {
+    return `${sourceKey}:${fileIndex}:${JSON.stringify(interval)}`;
+  }
+
+  cached(rangesKey) {
+    const ranges = this.#ranges.get(rangesKey);
+    return ranges ? { kind: "result", ranges, method: "source-range-cache" } : null;
+  }
+
+  async tracksOf(params, isCurrent = () => true) {
+    const answer = await this.#orchestrator.inspect(params, "tracks");
+    if (!isCurrent()) return { kind: "stale" };
+    if (answer.kind !== "result") return answer;
+    const container = this.#orchestrator.known(params.sourceKey, params.fileIndex);
+    if (typeof container?.readSourceRanges !== "function" && typeof container?.readPacketIndex !== "function") {
+      return { kind: "needs-index", reason: "packet-index-not-yet-available" };
+    }
+    return { kind: "result", trackList: answer.value, container };
+  }
+
+  async shiftOf(params, isCurrent = () => true) {
+    const answer = await this.#orchestrator.inspect(params, "media-info");
+    if (!isCurrent()) return { kind: "stale" };
+    if (answer.kind !== "result") return answer;
+    return { kind: "result", shift: Number(answer.value?.startTimeSeconds) || 0 };
+  }
+
+  async navigable(params, isCurrent = () => true) {
+    const answer = await this.#orchestrator.inspect(params, "source-navigation");
+    if (!isCurrent()) return { kind: "stale" };
+    if (answer.kind !== "result") return answer;
+    return { kind: "result", value: answer.value === true };
+  }
+
+  async readInput(params, { original, tracks, modes, interval }, isCurrent = () => true) {
+    const answer = await this.#orchestrator.inspect(params, original ? "source-ranges" : "packets");
+    if (!isCurrent()) return { kind: "stale", step: "packets" };
+    if (answer.kind !== "result") return { kind: answer.kind, step: "packets", answer };
+    const input = original ? answer.value
+      : new SegmentInputs({ index: answer.value, tracks }).forInterval({ ...interval, mode: track => modes.get(track) });
+    if (input.kind !== "result") return { kind: input.kind, step: "input", answer: input };
+    return { kind: "result", method: original ? "container-source-ranges" : "packet-index", input };
+  }
+
+  async resolve({ rangesKey, direct, interval, tracks, modes, intervalParams, isCurrent = () => true, whenBuilt = () => {} }) {
+    if (direct) {
+      let value = null;
+      try {
+        value = await directSegmentInput(direct, { interval, tracks, mode: track => modes.get(track) }, whenBuilt);
+      } catch { value = null; }
+      if (value?.kind === "pending") return { kind: "pending", method: "direct-source-index", step: "direct" };
+      if (value?.kind === "result") {
+        this.#ranges.set(rangesKey, value.ranges);
+        return { kind: "result", ranges: value.ranges, method: "direct-source-index" };
+      }
+    }
+    const params = await intervalParams();
+    if (!isCurrent()) return { kind: "stale", method: FALLBACK, step: "params" };
+    if (!params) return { kind: "needs-source", method: FALLBACK, step: "params" };
+    const navigation = await this.navigable(params, isCurrent);
+    if (navigation.kind === "stale") return { kind: "stale", method: FALLBACK, step: "navigation" };
+    if (navigation.kind !== "result") return { kind: navigation.kind, method: FALLBACK, step: "navigation", answer: navigation };
+    const read = await this.readInput(params, { original: navigation.value, tracks, modes, interval }, isCurrent);
+    if (read.kind !== "result") return { ...read, method: FALLBACK };
+    this.#ranges.set(rangesKey, read.input.ranges);
+    return { kind: "result", ranges: read.input.ranges, method: read.method };
+  }
+
+  forget(sourceKey) {
+    for (const key of this.#ranges.keys()) if (key.startsWith(`${sourceKey}:`)) this.#ranges.delete(key);
+  }
+}

package/services/media/SubtitleWalk.js

@@ -0,0 +1,172 @@
+/**
+ * @file The walk that finds new subtitle cues in what a torrent has downloaded
+ * and pushes them to the viewers.
+ *
+ * Subtitles are two layers put together, and this is the one place that knows
+ * about both: what a file STATES about its subtitle tracks and how a cue is
+ * written out is the media layer's, while which clusters may be read, where
+ * the cursor stands and what one walk at a time means are the TORRENT's own
+ * rules. The media layer used to import the second directly.
+ *
+ * Moved out of `server.js` verbatim (torrent-tv/meta#280): every free variable
+ * is a port.
+ */
+
+import { SubtitleOrchestrator } from "./SubtitleOrchestrator.js";
+import {
+  warmSubtitleCues,
+  cuesHeldFor,
+  subtitleTracksOf,
+  declaredSubtitleTracksOf,
+  forgetSubtitles
+} from "./SubtitleCues.js";
+import { CONTAINER_HEAD_BYTES } from "./ContainerOrchestrator.js";
+import { coalescing } from "../../utils/coalesce.js";
+
+export class SubtitleWalk {
+  /** The orchestrator the walk feeds; `server.js` reads it where it read `subtitles`. */
+  subtitles;
+  #torrents;
+  #containers;
+  #paramsFor;
+  #wantedSeconds;
+  #publish;
+  #log;
+  #warn;
+  #walk;
+
+  /**
+   * @param {object} ports
+   * @param {{ knownTorrent: Function, heldRangesOf: Function, readHeldOf: Function }} ports.torrents
+   * @param {{ known: Function, containerFor: Function }} ports.containers - The container orchestrator.
+   * @param {(request: object) => Promise<object | null>} ports.paramsFor
+   * @param {(sourceKey: string, fileIndex: number) => number[]} ports.wantedSeconds
+   *   Where the viewers of a file stand: the start of every urgent stretch of
+   *   its priority map, ascending whole seconds; `[]` when there is none.
+   * @param {(entry: object) => void} ports.publish
+   * @param {(line: string) => void} ports.log
+   * @param {(line: string) => void} ports.warn
+   */
+  constructor({ torrents, containers, paramsFor, wantedSeconds, publish, log, warn }) {
+    this.#torrents = torrents;
+    this.#containers = containers;
+    this.#paramsFor = paramsFor;
+    this.#wantedSeconds = wantedSeconds;
+    this.#publish = publish;
+    this.#log = log;
+    this.#warn = warn;
+    this.#walk = coalescing((sourceKey, fileIndex) => this.#walkFile(sourceKey, fileIndex));
+    this.subtitles = new SubtitleOrchestrator(containers, {
+      publish: entry => this.#publish(entry),
+      warm: async (torrent, fileIndex, sourceKey) => {
+        const file = await this.heldFileFor(sourceKey, fileIndex, torrent);
+        return file ? warmSubtitleCues(file) : [];
+      },
+      held: async (torrent, fileIndex, sourceKey, trackNumber) => {
+        const file = await this.heldFileFor(sourceKey, fileIndex, torrent);
+        return file ? cuesHeldFor(file, trackNumber) : null;
+      },
+      tracksOf: async (torrent, fileIndex, sourceKey) => {
+        const file = await this.heldFileFor(sourceKey, fileIndex, torrent);
+        return file ? subtitleTracksOf(file) : [];
+      },
+      declaredTracksOf: async (torrent, fileIndex, sourceKey) => {
+        const file = await this.heldFileFor(sourceKey, fileIndex, torrent);
+        return file ? declaredSubtitleTracksOf(file) : [];
+      },
+      forget: forgetSubtitles
+    });
+  }
+
+  /**
+   * One file of one torrent, reduced to what the subtitle walk may know: a
+   * name, a length, its one container, which ranges are downloaded whole, how
+   * to read one of those without asking the swarm, the portion one read may
+   * span, and where the viewers stand. File offsets and the bitfield stay in
+   * the torrent's thread; the piece length crosses as a plain number.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @param {object} [known] - The torrent handle when the caller already has it.
+   * @returns {Promise<import("./SubtitleCues.js").HeldFile | null>}
+   */
+  heldFileFor = async (sourceKey, fileIndex, known = null) => {
+    let torrent = known;
+    if (!torrent) {
+      torrent = this.#torrents.knownTorrent(sourceKey);
+      if (!torrent) return null;
+    }
+    const file = torrent?.files?.[fileIndex];
+    if (!file || !(file.length > 0)) {
+      return null;
+    }
+    return {
+      sourceKey,
+      fileIndex,
+      name: String(file.name ?? ""),
+      length: file.length,
+      portionBytes: Number(torrent.pieceLength) > 0 ? Number(torrent.pieceLength) : undefined,
+      // The file's ONE container — the one the track table, the media info and
+      // the keyframe table are read from. Built here only when nobody has built
+      // it yet, so a pass of the walk does not fetch the file's edges again.
+      container: async () => {
+        const known = this.#containers.known(sourceKey, fileIndex);
+        if (known !== undefined) {
+          return known;
+        }
+        const params = await this.#paramsFor({ sourceKey, fileIndex, tailBytes: CONTAINER_HEAD_BYTES });
+        return params ? this.#containers.containerFor(params) : null;
+      },
+      heldRanges: () => this.#torrents.heldRangesOf(torrent, fileIndex),
+      readHeld: (start, end) => this.#torrents.readHeldOf(torrent, fileIndex, start, end),
+      // Where the viewers of this file stand: the start of every urgent stretch
+      // of its priority map, which is where each viewer's own need begins.
+      wantedSeconds: () => this.#wantedSeconds(sourceKey, fileIndex),
+      // A pass left readable clusters for the next one: run it.
+      askAgain: () => {
+        void this.pushFreshCues(sourceKey, fileIndex);
+      }
+    };
+  };
+
+  /**
+   * Walk whatever new cues a file now holds and push them to the viewers.
+   *
+   * One walk of a file at a time, and one more after it whenever pieces
+   * arrived meanwhile (`coalescing`): `verified` fires per piece, so a queue of
+   * identical passes would only postpone the one with something new to find,
+   * and dropping them — as this used to — lost the pass that would have found
+   * the last pieces of a file.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @returns {Promise<void>}
+   */
+  pushFreshCues(sourceKey, fileIndex) {
+    return this.#walk(`${sourceKey}:${fileIndex}`, sourceKey, fileIndex);
+  }
+
+  async #walkFile(sourceKey, fileIndex) {
+    try {
+      const file = await this.heldFileFor(sourceKey, fileIndex);
+      if (!file) {
+        return;
+      }
+      for (const entry of await warmSubtitleCues(file)) {
+        if (this.subtitles.hasPacketCues(sourceKey, fileIndex, entry.trackIndex)) continue;
+        const span = entry.spanStartSeconds === null
+          ? "empty"
+          : `${entry.spanStartSeconds.toFixed(1)}-${entry.spanEndSeconds.toFixed(1)}s`;
+        this.#log(
+          `subtitle push ${sourceKey.slice(0, 8)}:${fileIndex} track ${entry.trackIndex}: ` +
+          `${entry.cues.length} new cue(s) covering ${span}` +
+          (entry.withdrawn.length > 0 ? `, ${entry.withdrawn.length} taken back` : "") +
+          `, clusters walked ${entry.walkedClusters}/${entry.indexedClusters}, cursor ${entry.cursor}`
+        );
+        this.#publish({ sourceKey, fileIndex, ...entry });
+      }
+    } catch (error) {
+      this.#warn(`subtitle push ${sourceKey.slice(0, 8)}:${fileIndex} failed: ${error?.message ?? error}`);
+    }
+  }
+}