@torrent-tv/proxy 2.107.53 → 2.107.55

package/package.json

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

package/routes/api/sources/stats/get.js

@@ -70,12 +70,10 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
   // local lookup. Without the await the reply was the pending promise itself,
   // which serialises to `{}` — the empty stats seen in the field 2026-08-02.
   const statsStartedAt = performance.now();
-  let statsCompletedAt;
   let stats;
   try {
     stats = await torrentPool.getFileStats(torrent, fileIndex);
   } finally {
-    statsCompletedAt = performance.now();
     logger.info(`[stats] ${sourceKey.slice(0, 8)} getFileStatsMs=${(performance.now() - statsStartedAt).toFixed(1)}`);
   }
   if (stats?.pending || !stats) {
@@ -161,9 +159,11 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
   }
   const responsePreparedAtProxyMs = performance.now();
   return reply.send({ ...stats, sourceSnapshotTransport: {
+    clockEpoch: performance.timeOrigin,
+    snapshotClockEpoch: stats.sourceCapture?.clockEpoch ?? null,
     requestReceivedAtProxyMs,
-    snapshotStartedAtProxyMs: statsStartedAt,
-    snapshotCompletedAtProxyMs: statsCompletedAt,
+    snapshotStartedAtProxyMs: stats.sourceCapture?.validity === "valid" ? stats.sourceCapture.startedAt : null,
+    snapshotCompletedAtProxyMs: stats.sourceCapture?.validity === "valid" ? stats.sourceCapture.completedAt : null,
     responsePreparedAtProxyMs
   } });
 }

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

@@ -117,12 +117,30 @@ export async function handleApiTranscodeSessionNetReportPost(req, reply,
       linkMbps: Number.isFinite(linkMbps) && linkMbps > 0 ? linkMbps : undefined,
       linkSampleMbps: Number.isFinite(linkSampleMbps) && linkSampleMbps > 0 ? linkSampleMbps : undefined,
       linkSampleAt: Number.isFinite(linkSampleAt) && linkSampleAt > 0 ? linkSampleAt : undefined,
+      linkSampleAgeMs: Number.isFinite(body.linkSampleAgeMs) && body.linkSampleAgeMs >= 0
+        ? body.linkSampleAgeMs : undefined,
       appendSessionId: sessionId,
       appendEpoch: typeof body.appendEpoch === "string" ? body.appendEpoch : undefined,
       appendEpochStartedAt: Number.isFinite(body.appendEpochStartedAt) && body.appendEpochStartedAt > 0
         ? body.appendEpochStartedAt : undefined,
       appendSnapshotAt: Number.isFinite(body.appendSnapshotAt) && body.appendSnapshotAt > 0
         ? body.appendSnapshotAt : undefined,
+      captureClockEpoch: Number.isFinite(body.captureClockEpoch) ? body.captureClockEpoch : undefined,
+      captureEpoch: typeof body.captureEpoch === "string" ? body.captureEpoch : undefined,
+      captureEpochStartedAtBrowser: Number.isFinite(body.captureEpochStartedAtBrowser)
+        ? body.captureEpochStartedAtBrowser : undefined,
+      captureRevision: Number.isSafeInteger(body.captureRevision) ? body.captureRevision : undefined,
+      captureStartedAtBrowser: Number.isFinite(body.captureStartedAtBrowser) ? body.captureStartedAtBrowser : undefined,
+      captureCompletedAtBrowser: Number.isFinite(body.captureCompletedAtBrowser)
+        ? body.captureCompletedAtBrowser : undefined,
+      linkSampleStartedAtBrowser: Number.isFinite(body.linkSampleStartedAtBrowser)
+        ? body.linkSampleStartedAtBrowser : undefined,
+      linkSampleCompletedAtBrowser: Number.isFinite(body.linkSampleCompletedAtBrowser)
+        ? body.linkSampleCompletedAtBrowser : undefined,
+      linkSampleActionId: typeof body.linkSampleActionId === "string" ? body.linkSampleActionId : undefined,
+      linkSampleGeneration: Number.isSafeInteger(body.linkSampleGeneration) ? body.linkSampleGeneration : undefined,
+      linkSampleClockEpoch: Number.isFinite(body.linkSampleClockEpoch) ? body.linkSampleClockEpoch : undefined,
+      linkSampleRevision: Number.isSafeInteger(body.linkSampleRevision) ? body.linkSampleRevision : undefined,
       appendService: body.appendService && typeof body.appendService === "object" ? body.appendService : undefined,
       fragmentService: body.fragmentService && typeof body.fragmentService === "object" ? body.fragmentService : undefined,
       bufferedAheadSec,

package/routes/api/transcode-sessions/progress/get.js

@@ -19,13 +19,21 @@ export async function handleApiTranscodeSessionsProgressGet(req, reply, { viewer
   // quality change the stream on screen is another session — a different one
   // for each viewer who changed.
   const consumerId = typeof req.query?.consumer === "string" ? req.query.consumer : "";
-  const progress = await viewerRequests.getSessionProgress(sessionId, consumerId);
+  const stated = Number(req.query?.generation);
+  const generation = Number.isSafeInteger(stated) && stated >= 0 ? stated : Number.NaN;
+  const progress = await viewerRequests.getSessionProgress(sessionId, consumerId, generation);
+  if (progress?.superseded === true) {
+    return reply.code(409).send({ error: "Viewer action was superseded." });
+  }
   if (!progress) {
     return reply.code(404).send({ error: "Transcode session was not found." });
   }
 
   const responsePreparedAtProxyMs = performance.now();
   progress.snapshotTransport = {
+    clockEpoch: performance.timeOrigin,
+    snapshotClockEpoch: progress.playbackReadiness?.snapshotClockEpoch ?? null,
+    generation: Number.isSafeInteger(generation) ? generation : null,
     requestReceivedAtProxyMs,
     snapshotAtProxyMs: progress.playbackReadiness?.snapshotAtProxyMs ?? null,
     responsePreparedAtProxyMs

package/services/encode/EncodeRun.js

@@ -37,6 +37,8 @@
  * owns the output. This carries a decision out and reports what happened.
  */
 
+import { performance } from "node:perf_hooks";
+
 import { ENCODE_RUN_EVENT, ENCODE_RUN_STATE, INITIAL_RUN_STATE, nextState } from "./encode-run-state.js";
 import { classifyEncodeExit, ENCODE_EXIT } from "./encode-exit.js";
 import { workDeltaBetween } from "./encoder-readings.js";
@@ -228,6 +230,7 @@ export class EncodeRun {
    * @param {(args: string[]) => import("node:child_process").ChildProcess} params.spawn
    * @param {{ info: (line: string) => void, warn: (line: string) => void, error?: (line: string) => void }} params.logger
    * @param {() => number} [params.now]
+   * @param {() => number} [params.monotonicNow]
    * @param {(ended: RunEnded) => void} [params.onEnded]
    * @param {(reading: { speed: number, at: number, workSeconds: number, workingSeconds: number }) => void} [params.onSpeedMeasured] -
    *   Told each time this run has measured its processing speed, once per
@@ -291,6 +294,7 @@ export class EncodeRun {
     indexOfName,
     startSeconds = 0,
     totalSeconds = null,
+    monotonicNow,
     because = "no reason was given"
   }) {
     this.address = address;
@@ -302,10 +306,11 @@ export class EncodeRun {
     this.spawnProcess = spawn;
     this.logger = logger;
     this.now = typeof now === "function" ? now : Date.now;
-    this.progress = new RunProgress({ startSeconds, totalSeconds, now: this.now });
+    this.monotonicNow = typeof monotonicNow === "function" ? monotonicNow : () => performance.now();
+    this.progress = new RunProgress({ startSeconds, totalSeconds, now: this.now, monotonicNow: this.monotonicNow });
     /** Where this run's time went: its own work, or waiting, or stopped. */
     this.clock = new RunClock({ now: this.now });
-    this.#pieceSample = { at: this.now(), producedSeconds: 0, workingMs: 0 };
+    this.#pieceSample = { at: this.now(), monotonicAt: this.monotonicNow(), producedSeconds: 0, workingMs: 0 };
     this.onEnded = typeof onEnded === "function" ? onEnded : () => {};
     this.onProgress = typeof onProgress === "function" ? onProgress : () => {};
     this.onProduced = typeof onProduced === "function" ? onProduced : () => {};
@@ -463,6 +468,7 @@ export class EncodeRun {
       this.#pieceSample = {
         ...this.#workSample,
         at: this.now(),
+        monotonicAt: this.monotonicNow(),
         workingMs: this.clock.workingMs()
       };
     }
@@ -600,6 +606,7 @@ export class EncodeRun {
       const at = this.now();
       this.#workSample = {
         at,
+        monotonicAt: this.progress.updatedAtMonotonic,
         producedSeconds: Math.max(0, this.progress.processedSeconds - this.progress.startPositionSeconds),
         workingMs: this.clock.workingMs(at)
       };
@@ -766,7 +773,10 @@ export class EncodeRun {
     }
     const work = workDeltaBetween(this.#pieceSample, sample);
     if (work !== null) {
-      this.#speedReading = { speed: work.workSeconds / work.workingSeconds, at: sample.at, ...work };
+      this.#speedReading = { speed: work.workSeconds / work.workingSeconds, at: sample.at, ...work,
+        captureOwner: "proxy-encoder", captureClock: "performance", captureClockEpoch: performance.timeOrigin,
+        captureStartedAtMonotonic: this.#pieceSample.monotonicAt,
+        captureCompletedAtMonotonic: sample.monotonicAt };
       this.#pieceSample = sample;
       this.#speedMeasurementPending = false;
       this.onSpeedMeasured(this.speedReading);

package/services/encode/RunProgress.js

@@ -1,3 +1,5 @@
+import { performance } from "node:perf_hooks";
+
 /**
  * @file Progress reported by one encoder run, placed on the source timeline.
  *
@@ -22,15 +24,18 @@ function parseTimestamp(value) {
 }
 
 export class RunProgress {
-  constructor({ startSeconds = 0, totalSeconds = null, now = Date.now } = {}) {
+  constructor({ startSeconds = 0, totalSeconds = null, now = Date.now, monotonicNow = () => performance.now() } = {}) {
     this.startPositionSeconds = Number.isFinite(startSeconds) ? Math.max(0, startSeconds) : 0;
     this.processedSeconds = this.startPositionSeconds;
     this.totalSeconds = Number.isFinite(totalSeconds) && totalSeconds > 0 ? totalSeconds : null;
     this.percent = null;
     this.remainingSeconds = this.totalSeconds;
     this.updatedAt = now();
+    this.updatedAtMonotonic = monotonicNow();
+    this.clockEpoch = performance.timeOrigin;
     this.lastLoggedAt = 0;
     this.now = now;
+    this.monotonicNow = monotonicNow;
     this.#derive();
   }
 
@@ -42,6 +47,7 @@ export class RunProgress {
       this.processedSeconds = this.startPositionSeconds + Math.max(0, relative);
     }
     this.updatedAt = this.now();
+    this.updatedAtMonotonic = this.monotonicNow();
     this.#derive();
     return this.snapshot();
   }
@@ -61,7 +67,9 @@ export class RunProgress {
       totalSeconds: this.totalSeconds,
       percent: this.percent,
       remainingSeconds: this.remainingSeconds,
-      updatedAt: this.updatedAt
+      updatedAt: this.updatedAt,
+      updatedAtMonotonic: this.updatedAtMonotonic,
+      clockEpoch: this.clockEpoch
     };
   }
 
@@ -77,3 +85,4 @@ export class RunProgress {
     this.remainingSeconds = Math.max(0, this.totalSeconds - this.processedSeconds);
   }
 }
+

package/services/encode/SpeedReadings.js

@@ -14,7 +14,9 @@
  */
 
 export class SpeedReadings {
-  /** @type {WeakMap<object, Array<{ speed: number, at: number, workSeconds?: number, workingSeconds?: number }>>} */
+  /** @type {WeakMap<object, Array<{ speed: number, at: number, workSeconds?: number, workingSeconds?: number,
+   * captureOwner?: string, captureClock?: string, captureClockEpoch?: number,
+   * captureStartedAtMonotonic?: number, captureCompletedAtMonotonic?: number }>>} */
   #byOutput = new WeakMap();
   #keepMs;
 
@@ -25,7 +27,9 @@ export class SpeedReadings {
 
   /**
    * @param {object} output
-   * @param {{ speed: number, at: number, workSeconds?: number, workingSeconds?: number } | null} reading
+   * @param {{ speed: number, at: number, workSeconds?: number, workingSeconds?: number,
+   * captureOwner?: string, captureClock?: string, captureClockEpoch?: number,
+   * captureStartedAtMonotonic?: number, captureCompletedAtMonotonic?: number } | null} reading
    */
   note(output, reading) {
     if (!output || !(reading?.speed > 0) || !Number.isFinite(reading.at)) return;
@@ -34,6 +38,10 @@ export class SpeedReadings {
     let place = readings.length;
     while (place > 0 && readings[place - 1].at > reading.at) place -= 1;
     const sample = { speed: reading.speed, at: reading.at };
+    for (const key of ["captureOwner", "captureClock", "captureClockEpoch", "captureStartedAtMonotonic",
+      "captureCompletedAtMonotonic"]) {
+      if (reading[key] !== undefined) sample[key] = reading[key];
+    }
     if (Number.isFinite(reading.workSeconds) && reading.workSeconds > 0 &&
         Number.isFinite(reading.workingSeconds) && reading.workingSeconds > 0) {
       Object.assign(sample, { workSeconds: reading.workSeconds, workingSeconds: reading.workingSeconds });

package/services/server/ViewerRequests.js

@@ -87,6 +87,49 @@ function forecastInputIdentity(state) {
   return state && JSON.stringify([state.sourceId, state.trackId, state.segmentIndex, state.phase]);
 }
 
+function unknownCapture(owner, actionId, generation, reason) {
+  return { owner, clock: "performance", clockEpoch: null, startedAt: null, completedAt: null,
+    actionId: actionId ?? null, generation: Number.isSafeInteger(generation) ? generation : null,
+    revision: null, validity: "unknown", unknownReason: reason };
+}
+
+function sourceCaptureOf(stats, actionId, generation) {
+  const source = stats?.sourceCapture;
+  if (!source || source.owner !== "torrent-worker" || source.clock !== "performance" ||
+      source.validity !== "valid" || !Number.isFinite(source.clockEpoch) ||
+      source.clockEpoch !== performance.timeOrigin ||
+      !Number.isFinite(source.startedAt) || !Number.isFinite(source.completedAt) ||
+      source.completedAt < source.startedAt || !Number.isSafeInteger(source.revision)) {
+    return { ...unknownCapture("torrent-worker", actionId, generation,
+      source?.unknownReason ?? "source-capture-unavailable"),
+      ...(Number.isFinite(source?.clockEpoch) ? { clockEpoch: source.clockEpoch } : {}),
+      ...(Number.isSafeInteger(source?.revision) ? { revision: source.revision } : {}) };
+  }
+  return { ...source, actionId: actionId ?? null, generation: Number.isSafeInteger(generation) ? generation : null };
+}
+
+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,
+    validity: Number.isFinite(run.progress?.clockEpoch) && Number.isFinite(run.progress?.updatedAtMonotonic)
+      ? "valid" : "unknown", unknownReason: Number.isFinite(run.progress?.clockEpoch) &&
+        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" &&
+    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");
+  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,
+    revision: captures.at(-1).revision ?? null, samples: captures, validity: "valid", unknownReason: null };
+}
+
 function observeForecastInput(observeWait, sourceKey, state, event) {
   if (!state) return;
   observeWait?.(sourceKey, "process", {
@@ -612,7 +655,7 @@ export class ViewerRequests {
     return this.#host.viewerSecondsOn(session, consumerId);
   }
 
-  async getSessionProgress(sessionId, consumerId = "") {
+  async getSessionProgress(sessionId, consumerId = "", statedGeneration = Number.NaN) {
     if (!isOutputName(sessionId)) {
       return null;
     }
@@ -628,6 +671,12 @@ export class ViewerRequests {
     const session = this.#host.activeOutputFor({ base: named, consumerId, outputs: this.#host.outputs });
     this.#host.outputs.touch(session);
     const viewer = consumerId ? this.#host.viewers.get(consumerId) : null;
+    const requestGeneration = consumerId && viewer?.assignments
+      ? this.#host.generationOfRequest(consumerId) : null;
+    const requestGenerationIsStated = Number.isSafeInteger(statedGeneration);
+    if (requestGenerationIsStated && requestGeneration !== statedGeneration) return { superseded: true };
+    const requestGenerationIsCurrent = () => !Number.isSafeInteger(requestGeneration) ||
+      this.#host.generationOfRequest(consumerId) === requestGeneration;
     const stillOwnsProgress = () => this.#stillOwnsProgress(named, session, consumerId, viewer);
     const audio = this.#host.renditions.servesAudioSeparately(session)
       ? this.#host.renditions.playbackAudioOutputFor(session, consumerId) : null;
@@ -648,10 +697,12 @@ export class ViewerRequests {
     // Observed output bitrate (Mbit/s) from recently completed segments. The
     // proxy uses it for the viewer-link budget and the readiness forecast.
     const outputMbps = await this.#host.quality.observedStreamMbps(session);
+    if (!requestGenerationIsCurrent()) return requestGenerationIsStated ? { superseded: true } : null;
     if (!stillOwnsProgress()) return null;
     const progress = this.#host.encodeRuns.progressOf(session);
     const playbackReadiness = await this.#playbackReadinessFor(session, consumerId, progress, outputMbps,
       viewer, stillOwnsProgress);
+    if (!requestGenerationIsCurrent()) return requestGenerationIsStated ? { superseded: true } : null;
     if (!stillOwnsProgress()) return null;
     return {
       // The id the caller asked about, not the variant it was answered from —
@@ -758,13 +809,31 @@ export class ViewerRequests {
     // the answer crossed the connection in 21 ms (r50, torrent-tv/meta#178).
     const parts = { enteredAt: performance.now(), statsMs: 0, workerForecastMs: 0, qualityMs: 0 };
     const viewerReading = viewer?.linkReading() ?? null;
+    const generation = consumerId && viewer?.assignments
+      ? this.#host.generationOfRequest(consumerId) : null;
+    const actionIsCurrent = () => !Number.isSafeInteger(generation) ||
+      this.#host.generationOfRequest(consumerId) === generation;
+    const actionId = Number.isSafeInteger(generation)
+      ? `${session.file.sourceKey}:${session.file.fileIndex}:${generation}` : null;
     const measurement = viewer
       ? this.#host.viewerPlaybackState.rateState(viewer, session, this.#host.playbackReadiness, this.#host.lookaheadSeconds)
       : { link: new this.#host.playbackReadiness.RateTrend(this.#host.lookaheadSeconds), sources: new Map() };
+    const existingLinkCaptures = measurement.link.captureSnapshot();
+    if (viewer && (viewerReading?.linkCapture?.validity !== "valid" || existingLinkCaptures.some(capture =>
+      !capture || capture.clockEpoch !== viewerReading.linkCapture.clockEpoch))) {
+      this.#host.viewerPlaybackState.forgetLinkReadings(measurement, this.#host.playbackReadiness,
+        this.#host.lookaheadSeconds);
+    }
     const linkAt = Number(viewerReading?.linkSampleMeasuredAt);
-    if (Number.isFinite(viewerReading?.linkSampleMbps) && viewerReading.linkSampleMbps > 0 && Number.isFinite(linkAt)) {
-      this.#host.viewerPlaybackState.addLinkReading(measurement, linkAt, viewerReading.linkSampleMbps);
+    if (viewerReading?.linkCapture?.validity === "valid" && Number.isFinite(viewerReading?.linkSampleMbps) &&
+        viewerReading.linkSampleMbps > 0 && Number.isFinite(linkAt)) {
+      this.#host.viewerPlaybackState.addLinkReading(measurement, linkAt, viewerReading.linkSampleMbps,
+        viewerReading.linkCapture);
     }
+    const rawBufferCapture = viewerReading?.bufferCapture ?? unknownCapture("browser", actionId, generation,
+      "browser-buffer-capture-unavailable");
+    const bufferCaptureValid = rawBufferCapture.validity === "valid" && rawBufferCapture.actionId === session.id &&
+      rawBufferCapture.generation === generation;
 
     const outputs = [session];
     const requiresSeparateAudio = this.#host.renditions.servesAudioSeparately(session);
@@ -780,21 +849,25 @@ export class ViewerRequests {
     let primarySourceStats = null;
     const tracks = [];
     for (const output of outputs) {
-      if (!stillOwnsProgress() || this.#host.outputs.get(output.id) !== output) return null;
+      if (!stillOwnsProgress() || !actionIsCurrent() || this.#host.outputs.get(output.id) !== output) return null;
       const trackProgress = output === session ? progress : this.#host.encodeRuns.progressOf(output);
-      const trackRates = this.#trackRateReadings(output, now);
+      const trackRate = this.#trackRateReadings(output, now);
+      const trackRates = trackRate?.summary ?? null;
       const trackName = output === session ? "video" : "audio";
       // The page states the offset its player applied to this track, and the
       // init it applied it to is the session's. Until both are known, the
       // pieces stay on their own presentation timeline: there is nothing yet
       // to place them by.
-      const playerOffset = viewerReading?.timestampOffsets?.[trackName];
+      const playerOffset = bufferCaptureValid ? viewerReading?.timestampOffsets?.[trackName] : null;
+      const reportedPosition = bufferCaptureValid && Number.isFinite(viewerReading?.positionSeconds)
+        ? viewerReading.positionSeconds : null;
       const servedInit = Number.isFinite(playerOffset) ? this.#host.segmentStore.initOf(output.outputKey) : null;
       const placedByPlayer = Boolean(servedInit?.length);
       const sessionInit = placedByPlayer ? servedInit : null;
       const inventory = this.#host.segmentStore.sizesOf(output.outputKey);
-      const segments = this.#host.outputForecastGeometry.segmentsOf(output, sessionInit, inventory, Number.isFinite(viewerReading?.positionSeconds)
-        ? viewerReading.positionSeconds : this.#host.viewerSecondsOn(session, consumerId, now));
+      const segments = this.#host.outputForecastGeometry.segmentsOf(output, sessionInit, inventory,
+        Number.isFinite(reportedPosition) ? reportedPosition : this.#host.viewerSecondsOn(session, consumerId, now));
+      const forecastGeometry = this.#host.outputForecastGeometry.get(output);
       const sourceIndexes = [...output.spec.sourceFileIndexes];
       if (sourceIndexes.length === 0) {
         sourceIndexes.push(output.file.fileIndex);
@@ -814,36 +887,62 @@ export class ViewerRequests {
         } catch {
           stats = null;
         }
-        if (!stillOwnsProgress() || this.#host.outputs.get(output.id) !== output) return null;
+        if (!stillOwnsProgress() || !actionIsCurrent() || this.#host.outputs.get(output.id) !== output) return null;
         if (output === session && fileIndex === session.file.fileIndex) primarySourceStats = stats;
         parts.statsMs += performance.now() - statsAt;
         parts.workerForecastMs += Number(stats?.forecastMs) || 0;
+        const sourceCapture = sourceCaptureOf(stats, actionId, generation);
         if (!sourceForecasts.has(output.file.sourceKey)) sourceForecasts.set(output.file.sourceKey, stats?.downloadForecast ?? { ranges: [] });
         const sharedForecast = sourceForecasts.get(output.file.sourceKey);
-        const downloadForecast = sharedForecast.global ? { measuredAt: sharedForecast.measuredAt,
+        const capturedForecast = sourceCaptureOf({ sourceCapture: sharedForecast?.capture }, actionId, generation);
+        const forecastCapture = sharedForecast?.global === true && !Array.isArray(sharedForecast.ranges)
+          ? { ...capturedForecast, validity: "unknown", unknownReason: "source-arrival-ranges-unavailable" }
+          : capturedForecast;
+        const downloadForecast = sourceCapture.validity !== "valid" || forecastCapture.validity !== "valid"
+          ? { ranges: [] } : sharedForecast.global ? { measuredAt: sharedForecast.measuredAt,
           ranges: !stats ? [] : sharedForecast.ranges.map(range => ({ ...range,
             start: Math.max(0, range.start - stats.fileOffset),
             end: Math.min(stats.fileLength, range.end - stats.fileOffset)
           })).filter(range => range.end > range.start) } : sharedForecast;
+        const sourceFactsValid = sourceCapture.validity === "valid";
+        const ownsSourceState = viewer && this.#host.viewerPlaybackState.owns(viewer, session, measurement);
+        const sourceReadingsValid = sourceFactsValid && Number.isFinite(stats?.downloadSpeed) && stats.downloadSpeed >= 0;
+        const existingSourceCaptures = ownsSourceState
+          ? this.#host.viewerPlaybackState.sourceCaptureSnapshot(measurement, output.file.sourceKey) : null;
+        const sourceEpochChanged = sourceReadingsValid && existingSourceCaptures &&
+          [existingSourceCaptures.recent?.delivered, existingSourceCaptures.recent?.free,
+            existingSourceCaptures.tail?.delivered, existingSourceCaptures.tail?.free].some(capture =>
+            capture?.validity === "valid" && capture.clockEpoch !== sourceCapture.clockEpoch);
+        if (ownsSourceState && (!sourceReadingsValid || sourceEpochChanged)) {
+          this.#host.viewerPlaybackState.forgetSourceReadings(measurement, output.file.sourceKey);
+        }
+        const downloadRateReadings = ownsSourceState && sourceReadingsValid
+          ? this.#host.viewerPlaybackState.sourceRateReadings(measurement, output.file.sourceKey, stats, now,
+            this.#host.playbackReadiness, this.#host.lookaheadSeconds, sourceCapture) : null;
+        const tailRateReadings = ownsSourceState && sourceReadingsValid
+          ? this.#host.viewerPlaybackState.sourceTailRateReadings(measurement, output.file.sourceKey, now,
+            this.#host.playbackReadiness) : null;
+        const downloadRateSummaries = ownsSourceState && sourceReadingsValid
+          ? this.#host.viewerPlaybackState.sourceRateSummaries(measurement, output.file.sourceKey) : null;
+        const rateCapture = ownsSourceState && sourceReadingsValid
+          ? this.#host.viewerPlaybackState.sourceCaptureSnapshot(measurement, output.file.sourceKey) : null;
         sourceMeasurements.set(sourceId, {
           id: sourceId,
           serviceKey: output.file.sourceKey,
-          complete: stats?.fileAvailable === true,
-          residence: stats?.residence,
-          fileOffset: stats?.fileOffset,
-          fileLength: stats?.fileLength,
-          bytesPerMediaSecond: Number.isFinite(stats?.fileLength) && stats.fileLength > 0 &&
+          complete: sourceFactsValid ? stats?.fileAvailable === true : null,
+          residence: sourceFactsValid ? stats?.residence : null,
+          fileOffset: sourceFactsValid ? stats?.fileOffset : null,
+          fileLength: sourceFactsValid ? stats?.fileLength : null,
+          bytesPerMediaSecond: sourceFactsValid && Number.isFinite(stats?.fileLength) && stats.fileLength > 0 &&
             Number.isFinite(session.file.durationSeconds) && session.file.durationSeconds > 0
             ? stats.fileLength / session.file.durationSeconds : null,
-          pieceLength: stats?.pieceLength,
-          downloadRateReadings: viewer && this.#host.viewerPlaybackState.owns(viewer, session, measurement)
-            ? this.#host.viewerPlaybackState.sourceRateReadings(measurement, output.file.sourceKey, stats, now,
-              this.#host.playbackReadiness, this.#host.lookaheadSeconds) : null,
-          tailRateReadings: viewer && this.#host.viewerPlaybackState.owns(viewer, session, measurement)
-            ? this.#host.viewerPlaybackState.sourceTailRateReadings(measurement, output.file.sourceKey, now,
-              this.#host.playbackReadiness) : null,
-          downloadRateSummaries: viewer && this.#host.viewerPlaybackState.owns(viewer, session, measurement)
-            ? this.#host.viewerPlaybackState.sourceRateSummaries(measurement, output.file.sourceKey) : null,
+          pieceLength: sourceFactsValid ? stats?.pieceLength : null,
+          downloadRateReadings,
+          tailRateReadings,
+          downloadRateSummaries,
+          capture: { ...sourceCapture, rateReadings: rateCapture ?? {
+            validity: "unknown", unknownReason: "source-rate-capture-unavailable" },
+          downloadForecast: forecastCapture },
           downloadForecast,
         });
       }
@@ -852,36 +951,38 @@ export class ViewerRequests {
       const observedMbps = output === session
         ? outputMbps
         : await this.#host.quality.observedStreamMbps(output);
-      if (!stillOwnsProgress() || this.#host.outputs.get(output.id) !== output) return null;
+      if (!stillOwnsProgress() || !actionIsCurrent() || this.#host.outputs.get(output.id) !== output) return null;
       parts.qualityMs += performance.now() - qualityAt;
       const liveRuns = this.#host.encodeRuns.liveRunsOf?.(output) ?? [];
+      const encoderCapture = encoderCaptureOf(trackRate?.captures, liveRuns, actionId, generation);
+      const encoderCaptureValid = encoderCapture.validity === "valid";
       const processingStarted = liveRuns.some(({ progress }) => progress.processedSeconds > progress.startPositionSeconds);
       const startedAt = liveRuns.find(({ startedAt }) => startedAt > 0)?.startedAt ?? now;
       tracks.push({
         id: output.outputKey,
         clockOffsetSeconds: placedByPlayer ? playerOffset : 0,
-        clientRanges: viewerReading?.bufferedRanges?.[output === session ? "video" : "audio"] ??
-          viewerReading?.bufferedRanges?.media,
+        clientRanges: bufferCaptureValid ? viewerReading?.bufferedRanges?.[output === session ? "video" : "audio"] ??
+          viewerReading?.bufferedRanges?.media : null,
         // Browser-observed append and fragment-parse samples are retained for
         // the full model's service schedule; they are not yet used as numeric
         // predecessors in the partial continuity calculation.
-        appendService: viewerReading?.appendSessionId === session.id && viewerReading?.appendService?.[trackName]
+        appendService: bufferCaptureValid && viewerReading?.appendSessionId === session.id && viewerReading?.appendService?.[trackName]
           ? { ...viewerReading.appendService[trackName], epoch: viewerReading.appendEpoch,
             epochStartedAt: viewerReading.appendEpochStartedAt, snapshotAt: viewerReading.appendSnapshotAt,
             receivedAt: viewerReading.appendServiceReceivedAt }
           : null,
-        fragmentService: viewerReading?.appendSessionId === session.id && viewerReading?.fragmentService?.[trackName]
+        fragmentService: bufferCaptureValid && viewerReading?.appendSessionId === session.id && viewerReading?.fragmentService?.[trackName]
           ? { ...viewerReading.fragmentService[trackName], epoch: viewerReading.appendEpoch,
             epochStartedAt: viewerReading.appendEpochStartedAt, snapshotAt: viewerReading.appendSnapshotAt,
             receivedAt: viewerReading.appendServiceReceivedAt }
           : null,
         sourceIds,
-        processedSeconds: trackProgress?.processedSeconds,
-        startupRemainingSeconds: processingStarted ? 0 : Math.max(0,
+        processedSeconds: encoderCaptureValid ? trackProgress?.processedSeconds : null,
+        startupRemainingSeconds: !encoderCaptureValid ? null : processingStarted ? 0 : Math.max(0,
           (this.#host.processingStartupSecondsOf?.(output) ?? 0) - Math.max(0, (now - startedAt) / 1000)),
-        processingRanges: liveRuns.map(({ progress }) => ({
+        processingRanges: encoderCaptureValid ? liveRuns.map(({ progress }) => ({
           start: progress.startPositionSeconds, end: progress.processedSeconds
-        })),
+        })) : [],
         // What a run's start costs this output, and the stretches its live
         // runs were given: the forecast starts a run wherever production meets
         // bytes that were not held when the run before was admitted.
@@ -894,18 +995,20 @@ 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: trackRates,
+        readings: encoderCaptureValid ? trackRates : [],
+        capture: encoderCapture,
         segments,
-        geometry: this.#host.outputForecastGeometry.get(output)?.geometry,
+        tailSegments: forecastGeometry?.tailSegments ?? [],
+        geometry: forecastGeometry?.geometry,
         readySegmentIndices: [...inventory.keys()],
         segmentSizesBytes: inventory
       });
     }
 
-    if (!stillOwnsProgress()) return null;
+    if (!stillOwnsProgress() || !actionIsCurrent()) return null;
 
-    const bufferedAheadSeconds = Number(viewerReading?.bufferedAheadSec);
-    const positionSeconds = Number.isFinite(viewerReading?.positionSeconds)
+    const bufferedAheadSeconds = bufferCaptureValid ? Number(viewerReading?.bufferedAheadSec) : null;
+    const positionSeconds = bufferCaptureValid && Number.isFinite(viewerReading?.positionSeconds)
       ? viewerReading.positionSeconds
       : this.#host.viewerSecondsOn(session, consumerId, now);
     // Both separately delivered tracks can run short independently. Use the
@@ -932,7 +1035,7 @@ export class ViewerRequests {
       positionSeconds,
       durationSeconds: session.file.durationSeconds,
       bufferedAheadSeconds,
-      bufferLimitSeconds: viewerReading?.bufferLimitSeconds,
+      bufferLimitSeconds: bufferCaptureValid ? viewerReading?.bufferLimitSeconds : null,
       reserveSeconds,
       lookaheadSeconds: this.#host.lookaheadSeconds,
       // Disk room remaining after stock reserved for other active outputs.
@@ -940,7 +1043,7 @@ export class ViewerRequests {
       requiredAudio: requiresSeparateAudio,
       sources: [...sourceMeasurements.values()],
       tracks,
-      linkReadings: measurement.link.snapshot()
+      linkReadings: viewerReading?.linkCapture?.validity === "valid" ? measurement.link.snapshot() : null
     };
     // A subtitle track chosen inside THIS file is the last input the forecast
     // waits for. A subtitle FILE beside it is named by its own index and is
@@ -960,6 +1063,18 @@ export class ViewerRequests {
     const forecast = withSubtitleReadiness(predicted, subtitle,
       subtitle ? this.#host.subtitleReadyFor?.(viewer) !== false : true);
     forecast.snapshotAtProxyMs = startedAt;
+    forecast.snapshotClockEpoch = performance.timeOrigin;
+    forecast.inputCaptures = {
+      source: [...sourceMeasurements].map(([id, source]) => ({ id, capture: source.capture })),
+      link: { ...(viewerReading?.linkCapture ?? unknownCapture("browser", actionId, generation,
+        "link-capture-unavailable")), rateReadings: measurement.link.captureSnapshot() },
+      encoder: tracks.map(track => ({ id: track.id, capture: track.capture })),
+      buffer: bufferCaptureValid || rawBufferCapture.validity === "unknown" ? rawBufferCapture : {
+        ...rawBufferCapture, validity: "invalid",
+        unknownReason: rawBufferCapture.generation !== generation ? "seek-generation-replaced" :
+          rawBufferCapture.actionId !== session.id ? "viewer-session-replaced" : "viewer-output-cancelled"
+      }
+    };
     forecast.operations = outputs.flatMap((output, index) => {
       const common = { speed: this.#host.playbackReadiness.forecastRate(tracks[index].readings, now, 0, "piece"),
         processedSeconds: tracks[index].processedSeconds,
@@ -976,8 +1091,6 @@ export class ViewerRequests {
           outputCodec: output.spec.audio.transcode ? "aac" : null }] : [])
       ];
     });
-    const generation = consumerId && viewer?.assignments
-      ? this.#host.generationOfRequest(consumerId) : null;
     const earlyWaitId = Number.isSafeInteger(generation)
       ? `${session.file.sourceKey}:${session.file.fileIndex}:${generation}` : null;
     if (earlyWaitId && this.#host.viewerPlaybackState.hasWait(viewer, earlyWaitId) && primarySourceStats) {
@@ -1136,7 +1249,20 @@ export class ViewerRequests {
   #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;
+    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" })) };
     // 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
@@ -1146,7 +1272,9 @@ export class ViewerRequests {
     if (Number.isFinite(projected) && projected > 0) {
       const seed = new this.#host.playbackReadiness.RateTrend();
       seed.add(now, projected);
-      return seed.snapshot();
+      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