@torrent-tv/proxy 2.107.55 → 2.107.57

package/services/server/MediaReadParams.js

@@ -0,0 +1,134 @@
+/**
+ * @file The parameters of a media read, and the metadata demand of an encode
+ * input, which lasts as long as the signal of its request.
+ */
+
+export class MediaReadParams {
+  #heldFile;
+  #packetMemory;
+  #readProbe;
+  #probePackets;
+  #baseUrl;
+  #observeWait;
+  #reads;
+  #maps;
+  #learnKeyframes;
+  #formatOf;
+  #warn;
+  /** @type {WeakMap<AbortSignal, Map<string, { statements: Set<string>, abort: () => void }>>} */
+  #trackers = new WeakMap();
+
+  constructor({ heldFile, packetMemory, readProbe, probePackets, baseUrl, observeWait, reads, maps,
+    learnKeyframes, formatOf, warn }) {
+    this.#heldFile = heldFile;
+    this.#packetMemory = packetMemory;
+    this.#readProbe = readProbe;
+    this.#probePackets = probePackets;
+    this.#baseUrl = baseUrl;
+    this.#observeWait = observeWait;
+    this.#reads = reads;
+    this.#maps = maps;
+    this.#learnKeyframes = learnKeyframes;
+    this.#formatOf = formatOf;
+    this.#warn = warn;
+  }
+
+  async paramsFor({ sourceKey, fileIndex, requestId, packetInterval, demand, readPriority, signal }) {
+    const file = this.#heldFile(sourceKey, fileIndex);
+    if (!file) {
+      return null;
+    }
+    const metadataTracker = readPriority?.requestId && signal
+      ? this.#trackerFor(signal, sourceKey, fileIndex) : null;
+    const maps = this.#maps;
+    const params = {
+      sourceKey,
+      fileIndex,
+      requestId,
+      signal,
+      packetInterval,
+      readPriority,
+      packetMemory: this.#packetMemory(sourceKey, fileIndex),
+      downloadInterval: demand ? { from: demand.from, to: demand.to } : null,
+      readRange: (start, end) => file.readHeld(start, Math.min(end, file.length - 1)),
+      fileSize: file.length,
+      probe: (statement, onRecord) => this.#readProbe({ sourceKey, fileIndex, statement: `ffprobe:${statement}`,
+        probe: ({ requestId, signal }) => {
+          const url = new URL("/media", this.#baseUrl());
+          url.searchParams.set("sourceKey", sourceKey);
+          url.searchParams.set("fileIndex", String(fileIndex));
+          url.searchParams.set("readId", requestId);
+          return this.#probePackets({ url: url.toString(), statement, signal, onRecord });
+        } }),
+      label: file.name,
+      fileOffset: file.offset,
+      onObserved: fields => {
+        const process = fields.statement === "keyframes" ? "P5"
+          : String(fields.statement).startsWith("ffprobe:") ? "X1" : "P2";
+        const details = { process, fileIndex, requestId, statement: fields.statement, cached: fields.cached,
+          result: fields.result, reason: fields.reason, ranges: fields.ranges,
+          queuedMs: fields.queuedMs, readMs: fields.readMs };
+        this.#observeWait(sourceKey, "process", { ...details, phase: "begin", at: fields.askedAt });
+        this.#observeWait(sourceKey, "process", { ...details, phase: "end", at: fields.endedAt,
+          startedAt: fields.askedAt, endedAt: fields.endedAt });
+      },
+      onTracks: tracks => file.noteVideo(tracks.some(track => track.type === "video")),
+      onReadStart: () => ({ storage: this.#reads.revision(sourceKey, fileIndex), memory: this.#reads.memoryRevision(),
+        demand: maps.epoch(sourceKey, fileIndex) }),
+      onReadResult: async (statement, result, revision) => {
+        if (revision.demand !== maps.epoch(sourceKey, fileIndex)) return;
+        if (demand && !maps.wantsInterval(sourceKey, fileIndex, demand)) return;
+        if (statement === "keyframes" && result.kind === "result") {
+          this.#learnKeyframes(params, { times: result.value?.times ?? null, tolerance: result.value?.tolerance ?? 0,
+            format: this.#formatOf(sourceKey, fileIndex) });
+        }
+        const finished = this.#reads.record(params, statement, result, revision.storage, revision.memory);
+        if (statement === "chapters" && result.passive) await maps.withdrawMetadata(sourceKey, fileIndex, statement);
+        else {
+          const metadataStatement = requestId ? `${statement}:${requestId}` : statement;
+          if (metadataTracker && result.kind === "needs-ranges") metadataTracker.statements.add(metadataStatement);
+          if (metadataTracker && result.kind !== "needs-ranges") metadataTracker.statements.delete(metadataStatement);
+          await maps.metadata({ sourceKey, fileIndex, statement: metadataStatement, result,
+            ...(statement === "chapters" ? { priority: 1, urgent: false, deadlineAt: null } : {}),
+            ...(demand ? { priority: demand.priority, urgent: demand.urgent, deadlineAt: demand.deadlineAt, interval: demand, leadSeconds: demand.leadSeconds ?? 0 } : {}),
+            ...(readPriority?.requestId ? { priority: readPriority.rank, urgent: readPriority.urgent === true,
+              deadlineAt: Number.isFinite(readPriority.deadlineAt) ? readPriority.deadlineAt : Number.POSITIVE_INFINITY,
+              scope: "preparation" } : {}),
+            // Neither a viewer's interval nor an encode input asked for it: the
+            // file read itself, and that read is wanted while the file is.
+            ...(!demand && !readPriority?.requestId ? { owner: "file" } : {}) });
+        }
+        if (finished && result.kind === "result") {
+          void maps.refresh(sourceKey, fileIndex).catch(error =>
+            this.#warn(`download map source=${sourceKey} file=${fileIndex} metadata refresh failed: ${error?.message ?? error}`));
+        }
+      },
+      portionBytes: file.portionBytes
+    };
+    return params;
+  }
+
+  #trackerFor(signal, sourceKey, fileIndex) {
+    const trackerKey = `${sourceKey}:${fileIndex}`;
+    let trackersForSignal = this.#trackers.get(signal);
+    if (!trackersForSignal) this.#trackers.set(signal, trackersForSignal = new Map());
+    let metadataTracker = trackersForSignal.get(trackerKey);
+    if (!metadataTracker) {
+      metadataTracker = { statements: new Set(), abort: null };
+      const tracker = metadataTracker;
+      tracker.abort = () => {
+        for (const statement of tracker.statements) {
+          void this.#maps.withdrawMetadata(sourceKey, fileIndex, statement).catch(error =>
+            this.#warn(`encode input demand withdrawal failed: ${error.message}`));
+        }
+        tracker.statements.clear();
+        trackersForSignal.delete(trackerKey);
+        if (trackersForSignal.size === 0) this.#trackers.delete(signal);
+      };
+      trackersForSignal.set(trackerKey, tracker);
+      if (signal.aborted) tracker.abort();
+      else signal.addEventListener("abort", tracker.abort, { once: true });
+    }
+    return metadataTracker;
+  }
+}

package/services/server/PreparationReads.js

@@ -0,0 +1,175 @@
+/**
+ * @file The reads a source preparation makes: its `inspect` port, and the
+ * publication of the native source map that follows a read.
+ *
+ * Moved out of `server.js` verbatim (torrent-tv/meta#280): every free variable
+ * is a port, and the preparation it reports to is passed with each call, since
+ * it is built after this owner.
+ */
+
+export class PreparationReads {
+  #paramsFor;
+  #containers;
+  #subtitles;
+  #fileLengthOf;
+  #viewersOf;
+  #segmentSeconds;
+  #preparationInterval;
+  #segmentInputs;
+  #nativeMaps;
+  #maps;
+  #record;
+  #planEncodersSoon;
+
+  /**
+   * @param {object} ports
+   * @param {(work: object) => Promise<object | null>} ports.paramsFor - MediaReadParams#paramsFor.
+   * @param {{ inspect: Function, containerFor: Function }} ports.containers
+   * @param {{ inspectFile: Function, inspectPackets: Function }} ports.subtitles
+   * @param {(sourceKey: string, fileIndex: number) => number | undefined} ports.fileLengthOf
+   * @param {(sourceKey: string) => object[]} ports.viewersOf - Viewers#forSource.
+   * @param {number} ports.segmentSeconds
+   * @param {(role: string, from: number, segmentSeconds: number) => object} ports.preparationInterval
+   * @param {(input: { index: object, tracks: object[] }) => { forInterval: Function }} ports.segmentInputs
+   * @param {{ packets: Function, original: Function }} ports.nativeMaps
+   * @param {{ metadata: Function, native: Function }} ports.maps
+   * @param {(params: object, statement: string, result: object, storage: unknown, memory: unknown) => boolean} ports.record
+   * @param {() => void} ports.planEncodersSoon
+   */
+  constructor({ paramsFor, containers, subtitles, fileLengthOf, viewersOf, segmentSeconds, preparationInterval,
+    segmentInputs, nativeMaps, maps, record, planEncodersSoon }) {
+    this.#paramsFor = paramsFor;
+    this.#containers = containers;
+    this.#subtitles = subtitles;
+    this.#fileLengthOf = fileLengthOf;
+    this.#viewersOf = viewersOf;
+    this.#segmentSeconds = segmentSeconds;
+    this.#preparationInterval = preparationInterval;
+    this.#segmentInputs = segmentInputs;
+    this.#nativeMaps = nativeMaps;
+    this.#maps = maps;
+    this.#record = record;
+    this.#planEncodersSoon = planEncodersSoon;
+  }
+
+  /**
+   * The native source map of a work whose input has been read.
+   *
+   * @param {object} work
+   * @param {object} preparation - `{ accepts, urgentReadyFor, ... }`, the source preparation.
+   */
+  async publishNative(work, preparation) {
+    if (!work.nativeInput || !preparation.accepts(work)) return Promise.resolve();
+    const watching = this.#viewersOf(work.sourceKey)
+      .filter(viewer => viewer.source.selectedFileIndex === work.fileIndex && viewer.outputs.size === 0);
+    const convert = work.nativeInput.container ? this.#nativeMaps.original : this.#nativeMaps.packets;
+    const zones = await convert({ ...work.nativeInput, viewers: watching,
+      allowanceSeconds: this.#segmentSeconds,
+      urgentReadyFor: viewer => preparation.urgentReadyFor(viewer) });
+    if (!preparation.accepts(work)) return;
+    return this.#maps.native({ sourceKey: work.sourceKey, fileIndex: work.fileIndex, zones });
+  }
+
+  /**
+   * Reads what the work asks for, and publishes what each read finds.
+   *
+   * @param {object} work
+   * @param {object} preparation
+   * @returns {Promise<object>} The answer the source preparation takes.
+   */
+  async inspect(work, preparation) {
+    const params = await this.#paramsFor(work);
+    if (!params) return { kind: "needs-source" };
+    params.isCurrent = () => preparation.accepts(work);
+    const originalContainer = work.statement === "packets" ? await this.#containers.containerFor(params) : null;
+    const navigation = work.statement === "packets" && work.role !== "subtitle-embedded"
+      ? await this.#containers.inspect(params, "source-navigation") : { kind: "result", value: false };
+    if (navigation.kind !== "result") return navigation;
+    const originalRanges = navigation.value;
+    if (!originalRanges && work.statement === "packets" && work.role === "source-rest" && preparation.accepts(work)) {
+      const length = this.#fileLengthOf(work.sourceKey, work.fileIndex);
+      if (length > 0) {
+        const statement = `${work.statement}:${work.requestId}:input`;
+        await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex, statement,
+          result: { kind: "needs-ranges", ranges: [[0, length - 1]], requestId: statement },
+          scope: "preparation", ...preparation.demandFor(work) });
+      }
+    }
+    if ((work.statement === "packets" && (work.role !== "source-rest" || originalRanges)) || work.role === "subtitle-embedded" && work.statement === "subtitle-cues") {
+      const info = await this.#containers.inspect({ ...params, onReadResult: undefined }, "media-info");
+      if (info.kind !== "result") return info;
+      const positions = this.#viewersOf(work.sourceKey)
+        .filter(viewer => viewer.source.selectedFileIndex === work.fileIndex &&
+          (work.ownerId === undefined || viewer.id === work.ownerId))
+        .map(viewer => viewer.positionSeconds() ?? 0);
+      const from = (positions.length ? Math.min(...positions) : 0) + (Number(info.value?.startTimeSeconds) || 0);
+      params.packetInterval = this.#preparationInterval(work.role, from, this.#segmentSeconds);
+      if (work.role === "subtitle-embedded") {
+        const tracks = await this.#containers.containerFor(params).then(container => container.readTracks());
+        const track = tracks.find(track => track.type === "subtitle" && track.declaredIndex === work.trackIndex);
+        if (!track || track.isTextBased?.() !== true) return { kind: "terminal", reason: "subtitle-track-not-supported" };
+        params.packetInterval.trackIds = [track.trackNumber];
+        params.subtitleTrackIndex = work.trackIndex;
+      }
+    }
+    params.onReadResult = async (statement, result, revision) => {
+      if (!preparation.accepts(work)) return;
+      this.#record(params, statement, result, revision.storage, revision.memory);
+      const inputStatement = `${work.statement}:${work.requestId}:input`;
+      if (statement === "source-ranges" && result.kind === "result") {
+        if (work.selected) work.inputRanges = result.value.ranges;
+        if (work.role === "source-rest") {
+          const info = await this.#containers.inspect({ ...params, onReadResult: undefined }, "media-info");
+          if (!preparation.accepts(work)) return;
+          if (info.kind === "result") {
+            work.nativeInput = { container: originalContainer, durationSeconds: info.value.durationSeconds,
+              startTimeSeconds: info.value.startTimeSeconds ?? 0 };
+            await this.publishNative(work, preparation);
+          }
+        } else {
+          await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex,
+            statement: inputStatement, result: { kind: "needs-ranges", ranges: result.value.ranges, requestId: inputStatement },
+            scope: "preparation", ...preparation.demandFor(work) });
+          if (work.selected) await preparation.bytesChanged(work.sourceKey, work.fileIndex);
+        }
+      }
+      if (statement === "packets" && work.role === "source-rest" && result.kind === "result") {
+        const tracks = await this.#containers.containerFor(params).then(container => container.readTracks());
+        const info = await this.#containers.inspect({ ...params, onReadResult: undefined }, "media-info");
+        if (!preparation.accepts(work)) return;
+        if (info.kind === "result") {
+          work.nativeInput = { index: result.value, tracks, durationSeconds: info.value.durationSeconds,
+            startTimeSeconds: info.value.startTimeSeconds ?? 0 };
+          await this.publishNative(work, preparation);
+        }
+      }
+      if (statement === "packets" && work.role !== "source-rest" && result.kind === "result" && (work.selected || work.ownerFileIndex !== undefined)) {
+        const tracks = await this.#containers.containerFor(params).then(container => container.readTracks());
+        if (!preparation.accepts(work)) return;
+        const bounds = tracks.filter(track => ["video", "audio"].includes(track.type))
+          .map(track => result.value.boundsOf(track.trackNumber)).filter(Boolean);
+        const interval = params.packetInterval ?? (bounds.length ? {
+          from: Math.max(0, Math.min(...bounds.map(bound => bound.start))), to: Math.max(...bounds.map(bound => bound.end))
+        } : null);
+        if (interval && interval.to > interval.from) {
+          const input = work.role === "subtitle-embedded"
+            ? result.value.inputFor({ trackId: params.packetInterval.trackIds[0], ...interval })
+            : this.#segmentInputs({ index: result.value, tracks }).forInterval(interval);
+          if (work.selected) work.inputRanges = input.kind === "result" ? input.ranges : null;
+          await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex,
+            statement: inputStatement, result: input.kind === "result" ? { kind: "needs-ranges", ranges: input.ranges, requestId: inputStatement } : input,
+            scope: "preparation", ...preparation.demandFor(work) });
+          if (work.selected) await preparation.bytesChanged(work.sourceKey, work.fileIndex);
+        }
+      }
+      if (!preparation.accepts(work)) return;
+      await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex,
+        statement: `${work.statement}:${work.requestId}`, result, scope: "preparation", ...preparation.demandFor(work) });
+      preparation.result(work, result);
+      if (["subtitle-file", "subtitle-cues"].includes(statement)) this.#planEncodersSoon();
+    };
+    return work.statement === "subtitle-file"
+      ? this.#subtitles.inspectFile(params) : work.statement === "subtitle-cues"
+        ? this.#subtitles.inspectPackets(params) : this.#containers.inspect(params, originalRanges ? "source-ranges" : work.statement);
+  }
+}

package/services/server/ViewerRequests.js

@@ -108,7 +108,7 @@ function sourceCaptureOf(stats, actionId, generation) {
   return { ...source, actionId: actionId ?? null, generation: Number.isSafeInteger(generation) ? generation : null };
 }
 
-function encoderCaptureOf(sampleCaptures, liveRuns, actionId, generation) {
+export function encoderCaptureOf(sampleCaptures, liveRuns, actionId, generation) {
   const runCaptures = (liveRuns ?? []).map(run => ({ owner: "proxy-encoder", clock: "performance",
     clockEpoch: run.progress?.clockEpoch, startedAt: run.progress?.updatedAtMonotonic,
     completedAt: run.progress?.updatedAtMonotonic, revision: run.progress?.updatedAtMonotonic,
@@ -117,19 +117,56 @@ function encoderCaptureOf(sampleCaptures, liveRuns, actionId, generation) {
         Number.isFinite(run.progress?.updatedAtMonotonic) ? null : "encoder-progress-capture-unavailable" }));
   const captures = [...(Array.isArray(sampleCaptures) ? sampleCaptures : []), ...runCaptures];
   const epoch = captures[0]?.clockEpoch;
-  const valid = captures.length > 0 && epoch === performance.timeOrigin && captures.every(capture =>
-    capture.owner === "proxy-encoder" && capture.clock === "performance" &&
+  const samplesOrdered = (Array.isArray(sampleCaptures) ? sampleCaptures : []).every((capture, index, samples) =>
+    index === 0 || capture.revision >= samples[index - 1].revision);
+  const valid = captures.length > 0 && samplesOrdered && epoch === performance.timeOrigin && captures.every(capture =>
+    capture.owner === "proxy-encoder" && capture.clock === "performance" && capture.validity === "valid" &&
     Number.isFinite(capture.clockEpoch) && capture.clockEpoch === epoch && Number.isFinite(capture.startedAt) &&
     Number.isFinite(capture.completedAt) && capture.completedAt >= capture.startedAt &&
     Number.isFinite(capture.revision));
-  if (!valid) return unknownCapture("proxy-encoder", actionId, generation, "encoder-capture-unavailable");
+  if (!valid) {
+    const projected = captures.find(capture => capture.provenance === "projected");
+    return { ...unknownCapture("proxy-encoder", actionId, generation,
+      projected?.unknownReason ?? "encoder-capture-unavailable"),
+    samples: captures, ...(projected ? { provenance: projected.provenance, projectionSource: projected.source } : {}) };
+  }
   return { owner: "proxy-encoder", clock: "performance", clockEpoch: epoch,
     startedAt: Math.min(...captures.map(capture => capture.startedAt)),
     completedAt: Math.max(...captures.map(capture => capture.completedAt)), actionId: actionId ?? null,
-    generation: Number.isSafeInteger(generation) ? generation : null,
+    generation: Number.isSafeInteger(generation) ? generation : null, provenance: "measured",
     revision: captures.at(-1).revision ?? null, samples: captures, validity: "valid", unknownReason: null };
 }
 
+export function trackRateReadings(readings, { predicted, projected }, now, playbackReadiness) {
+  const measured = (readings ?? []).filter(reading => reading.at <= now);
+  const summary = measured.length > 0 ? playbackReadiness.rateSummaryOf(measured) : null;
+  if (summary) return { summary, captures: measured.map(reading => ({ owner: reading.captureOwner,
+    clock: reading.captureClock, clockEpoch: reading.captureClockEpoch,
+    startedAt: reading.captureStartedAtMonotonic, completedAt: reading.captureCompletedAtMonotonic,
+    revision: reading.at,
+    validity: reading.captureOwner === "proxy-encoder" && reading.captureClock === "performance" &&
+      Number.isFinite(reading.captureClockEpoch) && Number.isFinite(reading.captureStartedAtMonotonic) &&
+      Number.isFinite(reading.captureCompletedAtMonotonic) && Number.isFinite(reading.at) &&
+      reading.captureCompletedAtMonotonic >= reading.captureStartedAtMonotonic
+      ? "valid" : "unknown",
+    unknownReason: reading.captureOwner === "proxy-encoder" && reading.captureClock === "performance" &&
+      Number.isFinite(reading.captureClockEpoch) && Number.isFinite(reading.captureStartedAtMonotonic) &&
+      Number.isFinite(reading.captureCompletedAtMonotonic) && Number.isFinite(reading.at) &&
+      reading.captureCompletedAtMonotonic >= reading.captureStartedAtMonotonic
+      ? null : "encoder-sample-capture-unavailable" })) };
+  const rate = Number(predicted ?? projected);
+  if (Number.isFinite(rate) && rate > 0) {
+    const seed = new playbackReadiness.RateTrend();
+    seed.add(now, rate);
+    const source = predicted === null || predicted === undefined
+      ? "current-cost-projection" : "stored-encode-prediction";
+    return { summary: seed.snapshot(), captures: [{ owner: "proxy-encoder", clock: "performance",
+      clockEpoch: null, startedAt: null, completedAt: null, revision: null, provenance: "projected", source,
+      validity: "unknown", unknownReason: "projected-encoder-speed-has-no-capture" }] };
+  }
+  return null;
+}
+
 function observeForecastInput(observeWait, sourceKey, state, event) {
   if (!state) return;
   observeWait?.(sourceKey, "process", {
@@ -956,6 +993,8 @@ export class ViewerRequests {
       const liveRuns = this.#host.encodeRuns.liveRunsOf?.(output) ?? [];
       const encoderCapture = encoderCaptureOf(trackRate?.captures, liveRuns, actionId, generation);
       const encoderCaptureValid = encoderCapture.validity === "valid";
+      const projectedRateCanSeedForecast = trackRate?.captures?.length > 0 &&
+        trackRate.captures.every(capture => capture.provenance === "projected");
       const processingStarted = liveRuns.some(({ progress }) => progress.processedSeconds > progress.startPositionSeconds);
       const startedAt = liveRuns.find(({ startedAt }) => startedAt > 0)?.startedAt ?? now;
       tracks.push({
@@ -995,7 +1034,10 @@ export class ViewerRequests {
           this.#host.initialOutputBitsPerMediaSecondOf?.(output) ?? 0,
         durationSeconds: output.timeline?.publishedStartOf(output.timeline.segmentCount) ?? session.file.durationSeconds,
         segmentCount: output.timeline?.segmentCount ?? segments.length,
-        readings: encoderCaptureValid ? trackRates : [],
+        // A projection is explicitly not a measured capture, but remains the
+        // numeric seed it was before capture provenance was carried here.
+        // Other invalid measured captures stay out of the forecast.
+        readings: encoderCaptureValid || projectedRateCanSeedForecast ? trackRates : [],
         capture: encoderCapture,
         segments,
         tailSegments: forecastGeometry?.tailSegments ?? [],
@@ -1247,39 +1289,16 @@ export class ViewerRequests {
    * would drop the later-told, earlier-taken one (torrent-tv/meta#178).
    */
   #trackRateReadings(output, now) {
-    const readings = (this.#host.encodeSpeedReadingsOf?.(output) ?? []).filter(reading => reading.at <= now);
-    const summary = readings.length > 0 ? this.#host.playbackReadiness.rateSummaryOf(readings) : null;
-    if (summary) return { summary, captures: readings.map(reading => ({ owner: reading.captureOwner,
-      clock: reading.captureClock, clockEpoch: reading.captureClockEpoch,
-      startedAt: reading.captureStartedAtMonotonic, completedAt: reading.captureCompletedAtMonotonic,
-      revision: reading.at,
-      validity: reading.captureOwner === "proxy-encoder" && reading.captureClock === "performance" &&
-        Number.isFinite(reading.captureClockEpoch) && Number.isFinite(reading.captureStartedAtMonotonic) &&
-        Number.isFinite(reading.captureCompletedAtMonotonic) && Number.isFinite(reading.at) &&
-        reading.captureCompletedAtMonotonic >= reading.captureStartedAtMonotonic
-        ? "valid" : "unknown",
-      unknownReason: reading.captureOwner === "proxy-encoder" && reading.captureClock === "performance" &&
-        Number.isFinite(reading.captureClockEpoch) && Number.isFinite(reading.captureStartedAtMonotonic) &&
-        Number.isFinite(reading.captureCompletedAtMonotonic) && Number.isFinite(reading.at) &&
-        reading.captureCompletedAtMonotonic >= reading.captureStartedAtMonotonic
-        ? null : "encoder-sample-capture-unavailable" })) };
+    const readings = this.#host.encodeSpeedReadingsOf?.(output) ?? [];
     // ONLY UNTIL A PIECE IS MEASURED does the prediction stand for the
     // encoder, and it is not kept among the readings. Added on every poll
     // between runs, it put the machine's share of that moment — 1 % at a
     // cold start — on the whole film, and the forecast read 0.03x
     // (torrent-tv/meta#178).
-    const projected = Number(this.#host.predictedEncodeSpeedOf?.(output) ?? this.#host.projectedEncodeSpeedOf?.(output));
-    if (Number.isFinite(projected) && projected > 0) {
-      const seed = new this.#host.playbackReadiness.RateTrend();
-      seed.add(now, projected);
-      return { summary: seed.snapshot(), captures: [{ owner: "proxy-encoder", clock: "performance",
-        clockEpoch: performance.timeOrigin, startedAt: now, completedAt: now, revision: now,
-        validity: "valid", unknownReason: null }] };
-    }
-    // Progress over wall time includes source waits, which the forecast prices
-    // separately. Keep the rate unknown until a measured or calibrated
-    // processing rate exists; single-piece runs now publish their own rate.
-    return null;
+    return trackRateReadings(readings, {
+      predicted: this.#host.predictedEncodeSpeedOf?.(output),
+      projected: this.#host.projectedEncodeSpeedOf?.(output)
+    }, now, this.#host.playbackReadiness);
   }
 
 }

package/services/server/forwarded-response-log.js

@@ -0,0 +1,55 @@
+/**
+ * @file The log of a forwarded transcode-session response (the registry's
+ * request, followed from its arrival to its last byte).
+ *
+ * Moved out of `server.js` verbatim (torrent-tv/meta#280). It imports nothing:
+ * the logger and the clock are passed in.
+ */
+
+/**
+ * Registers, on `app`, the hooks that write the `[forecast-http]` and
+ * `[http-response]` lines of a `POST /api/transcode-sessions` carrying
+ * `x-ttv-forwarded-request-id`. Any other request logs nothing.
+ *
+ * @param {import("fastify").FastifyInstance} app
+ * @param {{ log: (line: string) => void, warn: (line: string) => void, now?: () => number }} ports
+ */
+export function installForwardedResponseLog(app, { log, warn, now = () => performance.now() }) {
+  const forwardedSessionResponseStarts = new WeakMap();
+  const logStage = (stage, req) => {
+    const startedAt = forwardedSessionResponseStarts.get(req);
+    const requestId = req.headers["x-ttv-forwarded-request-id"];
+    if (startedAt === undefined || typeof requestId !== "string") return;
+    const at = now();
+    log(`[forecast-http] stage=${stage} requestId=${requestId} atMs=${at.toFixed(3)} ` +
+      `elapsedMs=${(at - startedAt).toFixed(3)}`);
+  };
+  app.addHook("onRequest", async (req, reply) => {
+    const requestId = req.headers["x-ttv-forwarded-request-id"];
+    if (typeof requestId !== "string" || req.method !== "POST" || req.url !== "/api/transcode-sessions") return;
+    const startedAt = now();
+    forwardedSessionResponseStarts.set(req, startedAt);
+    logStage("onRequest", req);
+    reply.raw.once("finish", () => {
+      logStage("finish", req);
+      log(`[http-response] requestId=${requestId} method=${req.method} url=${req.url} ` +
+        `responseMs=${(now() - startedAt).toFixed(1)} status=${reply.statusCode} ` +
+        `contentLength=${reply.raw.getHeader("content-length") ?? "unknown"}`);
+    });
+    reply.raw.once("close", () => {
+      if (!reply.raw.writableFinished) {
+        logStage("close", req);
+        warn(`[http-response] requestId=${requestId} method=${req.method} url=${req.url} ` +
+          `closedMs=${(now() - startedAt).toFixed(1)} status=${reply.statusCode}`);
+      }
+    });
+  });
+  app.addHook("preSerialization", async (req, _reply, payload) => {
+    logStage("preSerialization", req);
+    return payload;
+  });
+  app.addHook("onSend", async (req, _reply, payload) => {
+    logStage("onSend", req);
+    return payload;
+  });
+}

package/services/server/start-playback.js

@@ -0,0 +1,34 @@
+/**
+ * @file Where playback starts: viewer changes reach the source preparation and
+ * the download maps, and what an earlier process left behind is adopted.
+ *
+ * The subscription is made before the adoption, so whatever the adoption or
+ * anything after it changes about viewers reaches the maps. This is the seam
+ * the start order is tested through, since `server.js` cannot run in a test.
+ */
+
+/**
+ * @param {object} graph
+ * @param {{ viewerChanges: import("node:events").EventEmitter,
+ *           lifecycle: { adoptSegmentsLeftBehind(): object } }} graph.outputParts
+ * @param {{ viewersChanged(): Promise<unknown> }} graph.downloadMaps
+ * @param {() => { refresh(): unknown }} graph.preparation   - read when a change comes, never at the call
+ * @param {() => void} graph.onStateChanged
+ * @param {(line: string) => void} graph.warn
+ * @returns {object} what `adoptSegmentsLeftBehind` returned
+ */
+export function startPlayback({ outputParts, downloadMaps, preparation, onStateChanged, warn }) {
+  outputParts.viewerChanges.on("change", () => {
+    void preparation().refresh();
+    void downloadMaps.viewersChanged().catch(error => warn(`download maps after a viewer change: ${error.message}`));
+    onStateChanged();
+  });
+  // What the last life of this process left on the disk. The kernel kills this
+  // one often enough for that to be an ordinary state rather than an odd one —
+  // twice in a single viewing on 2026-09-02 — and when it does, no exit handler
+  // runs and nothing is cleared up. So this is both the cleanup and the only
+  // record that those encoders ended at all: it says what it found before it
+  // decides anything, keeps the segments whose closure is proven, and removes
+  // the one piece per output that was being written when the process died.
+  return outputParts.lifecycle.adoptSegmentsLeftBehind();
+}

package/services/server/torrent-pool-ports.js

@@ -0,0 +1,105 @@
+/**
+ * @file The torrent-pool adapters of the output graph: what the encoders and
+ * the machine budget ask of the torrent thread, as plain functions.
+ *
+ * Moved out of the `wireOutputs` call in `server.js` verbatim
+ * (torrent-tv/meta#280). It imports nothing: the pool and the registry are
+ * passed in.
+ */
+
+/**
+ * @param {object} ports
+ * @param {object} ports.torrentPool
+ * @param {{ get: (sourceKey: string) => { sourceType: string, source: unknown } | undefined }} ports.sourceRegistry
+ * @param {string} ports.wholeFilesRoot - Where whole files are kept (`completedFilesRoot()`).
+ */
+export function torrentPoolPorts({ torrentPool, sourceRegistry, wholeFilesRoot }) {
+  return {
+    readEncodeRanges: async (source, ranges, maxBytes) => {
+      const torrent = torrentPool.knownTorrent(source.sourceKey);
+      return torrent ? torrentPool.readHeldRangesOf(torrent, source.fileIndex, ranges, maxBytes) : null;
+    },
+    openEncodeWholeFile: source => torrentPool.acquireWholeFile(source),
+    // Which bytes of a file are downloaded whole now — what an original
+    // input's stretch may extend over. A snapshot: the copy that follows
+    // holds the pieces it reads, and refuses where one has gone since.
+    readEncodeHeldRanges: async (source) => {
+      const torrent = torrentPool.knownTorrent(source.sourceKey);
+      return torrent ? torrentPool.heldRangesOf(torrent, source.fileIndex) : [];
+    },
+    // What the spilled pieces weigh on the torrent thread, and how to tell them
+    // their share of the disk. The owner of the disk is on this side, where the
+    // segments are; the pieces are on the other.
+    spillDisk: typeof torrentPool.allowSpillBytes === "function"
+      ? {
+          held: () => torrentPool.spilledBytes ?? 0,
+          allow: (bytes) => torrentPool.allowSpillBytes(bytes)
+        }
+      : null,
+    // Files downloaded whole, kept as files. They live on the torrent thread
+    // too, and until 2026-09-14 they had no bound of any kind — a 2.8 GB film
+    // on a host whose disk is often a 32 GB card.
+    wholeFiles: typeof torrentPool.allowWholeFileBytes === "function"
+      ? {
+          held: () => torrentPool.wholeFileBytes ?? 0,
+          required: () => torrentPool.wholeFileRequiredBytes ?? 0,
+          allow: (bytes) => torrentPool.allowWholeFileBytes(bytes),
+          root: wholeFilesRoot
+        }
+      : null,
+    // The pieces held IN memory, on the torrent thread. Told their share by the
+    // same owner that divides the disk: what does not fit here is spilled
+    // there, so the two cannot be divided apart.
+    memoryClaimant: typeof torrentPool.allowMemoryBytes === "function"
+      ? {
+          held: () => torrentPool.memoryClaim?.held ?? 0,
+          wanted: () => torrentPool.memoryClaim?.wanted ?? 0,
+          allow: (bytes) => torrentPool.allowMemoryBytes(bytes)
+        }
+      : null,
+    getTorrentTotals: async () => {
+      if (typeof torrentPool.getTorrentTotals !== "function") {
+        return null;
+      }
+      return torrentPool.getTorrentTotals();
+    },
+    setDownloadRate: (bytesPerSecond, because) => torrentPool.setDownloadRate?.(bytesPerSecond, because),
+    setSpeculativeHold: (held, because) => torrentPool.setSpeculativeHold?.(held, because),
+    getSourceStats: async (sourceKey, fileIndex, options) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return null;
+      }
+      try {
+        const torrent = torrentPool.knownTorrent(sourceKey);
+        if (!torrent) return null;
+        // Awaited for the same reason as the stats route: this now crosses a
+        // thread boundary and returns a promise.
+        return await torrentPool.getFileStats(torrent, Number.isInteger(fileIndex) ? fileIndex : null, options);
+      } catch {
+        return null;
+      }
+    },
+    // Pull one whole file onto the disk. Used for a soundtrack that ships beside
+    // the picture, once the encoder is as far ahead of the viewer as it is
+    // allowed to get — the one moment the swarm's capacity is demonstrably
+    // spare. A bounded read of the file's whole length, NOT `file.select()`:
+    // selecting a file alongside the readers' own windows is what made a seek
+    // wait 93 s while the swarm fetched 2.47 GB in file order (see
+    // `#syncSelections` in `torrent/torrent-pool.js`).
+    fetchWholeFile: async ({ sourceKey, fileIndex }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return;
+      }
+      const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+      // The same background fill the warm-up starts when a file is chosen, not a
+      // second way of doing it. It is guarded against running twice on one file,
+      // so the two triggers converge instead of putting two readers on the same
+      // soundtrack — and only one of them would have stood aside for the
+      // picture. This trigger remains for the session that never had a warm-up
+      // before it.
+      await torrentPool.fillFileInBackground?.(torrent, fileIndex);
+    }
+  };
+}