@torrent-tv/proxy 2.107.53 → 2.107.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.107.53",
+  "version": "2.107.54",
   "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,24 @@ 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 sourceIndexes = [...output.spec.sourceFileIndexes];
       if (sourceIndexes.length === 0) {
         sourceIndexes.push(output.file.fileIndex);
@@ -814,36 +886,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 +950,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,7 +994,8 @@ 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,
         readySegmentIndices: [...inventory.keys()],
@@ -902,10 +1003,10 @@ export class ViewerRequests {
       });
     }
 
-    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 +1033,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 +1041,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 +1061,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 +1089,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 +1247,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 +1270,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

package/services/torrent/worker/worker.js

@@ -42,6 +42,9 @@ import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../../storage/memory
 import { profileThisThread } from "../../storage/cpu-profile.js";
 import { forwardLogsTo, logger } from "../../../utils/logger.js";
 
+const WORKER_CLOCK_EPOCH = performance.timeOrigin;
+let sourceSnapshotRevision = 0;
+
 /**
  * Everything this thread logs goes to the main thread, which owns the file.
  *
@@ -492,6 +495,8 @@ async function runCommand(command, params, id) {
 
     case Command.FILE_STATS: {
       const statsStartedAt = performance.now();
+      const sourceCaptureStartedAt = statsStartedAt;
+      const sourceRevision = ++sourceSnapshotRevision;
       emitWaitTrace(params.sourceKey, "W10", "begin", { startedAt: statsStartedAt,
         fileIndex: params.fileIndex, forecast: params.forecast === true });
       const finishStatsTrace = (outcome, fields = {}) => {
@@ -504,7 +509,14 @@ async function runCommand(command, params, id) {
         if (!torrent) {
           const whole = wholeSources.fileOf(params.sourceKey, params.fileIndex);
           finishStatsTrace(whole ? "whole-file" : "pending");
-          return whole ? wholeFileStats(whole.length) : { pending: true };
+          return {
+            ...(whole ? wholeFileStats(whole.length) : { pending: true }),
+            sourceCapture: {
+              owner: "torrent-worker", clock: "performance", clockEpoch: WORKER_CLOCK_EPOCH,
+              startedAt: sourceCaptureStartedAt, completedAt: performance.now(), revision: sourceRevision,
+              validity: whole ? "valid" : "unknown", unknownReason: whole ? null : "source-not-ready"
+            }
+          };
         }
         // What this file's own interruptions demand, measured by the reader in
         // this thread. It travels with the stats because the caller asking for
@@ -515,7 +527,8 @@ async function runCommand(command, params, id) {
         const file = Array.isArray(torrent?.files) ? torrent.files[params.fileIndex] : null;
         const forecastAt = performance.now();
         const forecast = file && params.forecast === true ? downloadForecastOf(torrent) : null;
-        const forecastMs = params.forecast === true ? performance.now() - forecastAt : 0;
+        const forecastCompletedAt = performance.now();
+        const forecastMs = params.forecast === true ? forecastCompletedAt - forecastAt : 0;
         const stats = pool.getFileStats(torrent, params.fileIndex);
         const ranges = [];
         if (forecast) for (const [piece, availableAt] of forecast.arrivals) {
@@ -526,8 +539,19 @@ async function runCommand(command, params, id) {
         finishStatsTrace("ok", { forecast: params.forecast === true });
         return {
           ...stats,
+          sourceCapture: {
+            owner: "torrent-worker", clock: "performance", clockEpoch: WORKER_CLOCK_EPOCH,
+            startedAt: sourceCaptureStartedAt, completedAt: performance.now(), revision: sourceRevision,
+            validity: stats ? "valid" : "unknown", unknownReason: stats ? null : "source-stats-unavailable"
+          },
           ...(params.forecast === true ? { downloadForecast: {
-            measuredAt: forecast?.measuredAt ?? Date.now(), global: true, ranges
+            measuredAt: forecast?.measuredAt ?? Date.now(), global: true, ranges,
+            capture: {
+              owner: "torrent-worker", clock: "performance", clockEpoch: WORKER_CLOCK_EPOCH,
+              startedAt: forecastAt, completedAt: forecastCompletedAt, revision: sourceRevision,
+              validity: forecast ? "valid" : "unknown",
+              unknownReason: forecast ? null : "source-arrival-forecast-unavailable"
+            }
           } } : {}),
           supply: supplyFiguresFor(torrent?.infoHash, file?.name, params.segmentSeconds ?? 4),
           // How long this answer waited for the arrival forecast, which the

package/services/viewer/Viewer.js

@@ -53,6 +53,34 @@ function fragmentEventAges(value) {
     Number.isFinite(value?.[name]) && value[name] >= 0 ? value[name] : null]));
 }
 
+function browserCaptureOf(report, sessionId) {
+  const clockEpoch = report.captureClockEpoch;
+  const startedAt = report.captureStartedAtBrowser;
+  const completedAt = report.captureCompletedAtBrowser;
+  const valid = typeof report.captureEpoch === "string" && report.captureEpoch.length > 0 &&
+    Number.isFinite(report.captureEpochStartedAtBrowser) && Number.isFinite(report.captureRevision) &&
+    Number.isSafeInteger(report.captureRevision) && report.captureRevision > 0 &&
+    Number.isFinite(clockEpoch) && Number.isFinite(startedAt) && Number.isFinite(completedAt) &&
+    report.captureEpochStartedAtBrowser >= clockEpoch && startedAt >= report.captureEpochStartedAtBrowser &&
+    completedAt >= startedAt &&
+    Number.isSafeInteger(report.generation) && report.generation >= 0;
+  return {
+    owner: "browser",
+    clock: "performance",
+    clockEpoch: Number.isFinite(clockEpoch) ? clockEpoch : null,
+    startedAt: Number.isFinite(startedAt) ? startedAt : null,
+    completedAt: Number.isFinite(completedAt) ? completedAt : null,
+    actionId: typeof sessionId === "string" && sessionId.length > 0 ? sessionId : null,
+    generation: Number.isSafeInteger(report.generation) ? report.generation : null,
+    revision: Number.isSafeInteger(report.captureRevision) ? report.captureRevision : null,
+    epoch: typeof report.captureEpoch === "string" ? report.captureEpoch : null,
+    epochStartedAt: Number.isFinite(report.captureEpochStartedAtBrowser)
+      ? report.captureEpochStartedAtBrowser : null,
+    validity: valid ? "valid" : "unknown",
+    unknownReason: valid ? null : "missing-or-invalid-browser-capture"
+  };
+}
+
 function appendServiceSnapshot(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const snapshot = {};
@@ -522,6 +550,18 @@ export class Viewer {
       appendEpoch = null,
       appendEpochStartedAt = null,
       appendSnapshotAt = null,
+      captureClockEpoch = null,
+      captureEpoch = null,
+      captureEpochStartedAtBrowser = null,
+      captureRevision = null,
+      captureStartedAtBrowser = null,
+      captureCompletedAtBrowser = null,
+      linkSampleStartedAtBrowser = null,
+      linkSampleCompletedAtBrowser = null,
+      linkSampleActionId = null,
+      linkSampleGeneration = null,
+      linkSampleClockEpoch = null,
+      linkSampleRevision = null,
       appendService: appendServiceReading = null,
       fragmentService: fragmentServiceReading = null,
       bufferedAheadSec,
@@ -564,6 +604,18 @@ export class Viewer {
     const sampleMbps = Number(linkSampleMbps);
     const sampleAt = Number(linkSampleAt);
     const previous = this.netReport;
+    const browserCapture = browserCaptureOf({ captureClockEpoch, captureEpoch, captureEpochStartedAtBrowser,
+      captureRevision, captureStartedAtBrowser, captureCompletedAtBrowser, generation }, appendSessionId);
+    const previousCapture = previous?.bufferCapture ?? null;
+    const captureOrderKnown = browserCapture.clockEpoch !== null && browserCapture.epoch !== null &&
+      browserCapture.epochStartedAt !== null && browserCapture.revision !== null && browserCapture.revision > 0;
+    const sameCaptureClock = captureOrderKnown && browserCapture.clockEpoch === previousCapture?.clockEpoch;
+    const sameCaptureEpoch = sameCaptureClock && browserCapture.epoch === previousCapture?.epoch;
+    const newerCapture = captureOrderKnown && (!previousCapture || !previousCapture.clockEpoch ||
+      !sameCaptureClock && browserCapture.epochStartedAt > (previousCapture.epochStartedAt ?? 0) ||
+      sameCaptureClock && (sameCaptureEpoch && browserCapture.revision > previousCapture.revision ||
+        !sameCaptureEpoch && browserCapture.epochStartedAt > (previousCapture.epochStartedAt ?? 0)));
+    const staleCapture = captureOrderKnown && previousCapture && !newerCapture;
     const incomingAppendService = typeof appendEpoch === "string" && appendEpoch.length > 0
       ? appendServiceSnapshot(appendServiceReading) : null;
     const incomingFragmentService = typeof appendEpoch === "string" && appendEpoch.length > 0
@@ -578,37 +630,85 @@ export class Viewer {
           (!previous?.appendService || appendServiceIsMonotonic(incomingAppendService, previous.appendService)) &&
           (!previous?.fragmentService || fragmentServiceIsMonotonic(incomingFragmentService, previous.fragmentService))
         : appendEpochStartedAt > (previous?.appendEpochStartedAt ?? 0));
+    const preserveBrowserService = sameAppendEpoch && incomingAppendService && incomingFragmentService;
     const hasPlaybackSample = Number.isFinite(sampleMbps) && sampleMbps > 0 &&
-      Number.isFinite(sampleAt) && sampleAt > 0;
-    const newerPlaybackSample = hasPlaybackSample && sampleAt > (this.netReport?.linkSampleAt ?? 0);
+      Number.isFinite(sampleAt) && sampleAt > 0 && Number.isFinite(captureClockEpoch) &&
+      Number.isFinite(linkSampleClockEpoch) && linkSampleClockEpoch === captureClockEpoch &&
+      Number.isSafeInteger(linkSampleRevision) && linkSampleRevision > 0 &&
+      Number.isFinite(linkSampleStartedAtBrowser) && Number.isFinite(linkSampleCompletedAtBrowser) &&
+      linkSampleStartedAtBrowser >= captureClockEpoch && linkSampleCompletedAtBrowser === sampleAt &&
+      linkSampleStartedAtBrowser <= linkSampleCompletedAtBrowser &&
+      Number.isFinite(captureCompletedAtBrowser) && sampleAt <= captureCompletedAtBrowser &&
+      Number.isFinite(linkSampleAgeMs) && linkSampleAgeMs >= 0;
+    const oldLinkEpoch = this.netReport?.linkCapture?.epoch !== String(linkSampleClockEpoch) &&
+      Number.isFinite(this.netReport?.linkCapture?.epochStartedAt) &&
+      Number.isFinite(linkSampleClockEpoch) &&
+      linkSampleClockEpoch <= this.netReport.linkCapture.epochStartedAt;
+    const newerPlaybackSample = hasPlaybackSample && !oldLinkEpoch &&
+      (linkSampleClockEpoch !== this.netReport?.linkCapture?.clockEpoch ||
+        linkSampleRevision > (this.netReport?.linkCapture?.revision ?? 0));
+    const linkClockEpochChanged = Number.isFinite(captureClockEpoch) &&
+      Number.isFinite(this.netReport?.linkCapture?.clockEpoch) &&
+      captureClockEpoch !== this.netReport.linkCapture.clockEpoch;
+    const newerInvalidPlaybackSample = !stale && newerCapture && !hasPlaybackSample &&
+      (Number.isSafeInteger(linkSampleRevision) || linkSampleAt !== null && linkSampleAt !== undefined ||
+        linkClockEpochChanged);
+    const preserveCapture = stale || staleCapture;
+    const linkCapture = newerPlaybackSample ? {
+      owner: "browser", clock: "performance", clockEpoch: linkSampleClockEpoch,
+      startedAt: linkSampleStartedAtBrowser, completedAt: linkSampleCompletedAtBrowser,
+      actionId: typeof linkSampleActionId === "string" ? linkSampleActionId : null,
+      generation: Number.isSafeInteger(linkSampleGeneration) ? linkSampleGeneration : null,
+      epoch: String(linkSampleClockEpoch), epochStartedAt: linkSampleClockEpoch,
+      revision: linkSampleRevision, validity: "valid", unknownReason: null
+    } : newerInvalidPlaybackSample ? {
+      owner: "browser", clock: "performance", clockEpoch: Number.isFinite(captureClockEpoch) ? captureClockEpoch : null,
+      startedAt: null, completedAt: null, actionId: appendSessionId,
+      generation: Number.isSafeInteger(generation) ? generation : null,
+      epoch: Number.isFinite(captureClockEpoch) ? String(captureClockEpoch) : null,
+      epochStartedAt: captureClockEpoch,
+      revision: linkSampleRevision, validity: "invalid", unknownReason: "invalid-link-sample-capture"
+    } : this.netReport?.linkCapture ?? {
+      owner: "browser", clock: "performance", clockEpoch: null, startedAt: null, completedAt: null,
+      actionId: appendSessionId, generation: Number.isSafeInteger(generation) ? generation : null,
+      epoch: null, epochStartedAt: null, revision: null, validity: "unknown",
+      unknownReason: "missing-link-sample-capture"
+    };
+    const useCapture = !stale && !staleCapture && newerCapture && browserCapture.validity === "valid";
     this.netReport = {
       linkMbps: lastLinkMbps,
       linkMeasuredAt,
-      linkSampleAt: newerPlaybackSample ? sampleAt : this.netReport?.linkSampleAt ?? null,
-      linkSampleMbps: newerPlaybackSample ? sampleMbps : this.netReport?.linkSampleMbps ?? null,
-      linkSampleMeasuredAt: newerPlaybackSample
-        ? Number.isFinite(linkSampleAgeMs) && linkSampleAgeMs >= 0
-          ? now - linkSampleAgeMs
-          : now
-        : this.netReport?.linkSampleMeasuredAt ?? null,
+      linkSampleAt: newerPlaybackSample ? sampleAt : newerInvalidPlaybackSample ? null : this.netReport?.linkSampleAt ?? null,
+      linkSampleMbps: newerPlaybackSample ? sampleMbps : newerInvalidPlaybackSample ? null : this.netReport?.linkSampleMbps ?? null,
+      linkSampleMeasuredAt: newerPlaybackSample ? now : newerInvalidPlaybackSample ? null : this.netReport?.linkSampleMeasuredAt ?? null,
+      linkCapture,
+      bufferCapture: preserveCapture ? previousCapture ?? browserCapture : useCapture ? browserCapture : {
+        ...browserCapture,
+        validity: "unknown",
+        unknownReason: browserCapture.unknownReason ?? "missing-or-invalid-browser-capture"
+      },
       appendSessionId: useBrowserService ? appendSessionId : previous?.appendSessionId ?? null,
-      appendEpoch: useBrowserService ? appendEpoch : previous?.appendEpoch ?? null,
+      appendEpoch: useBrowserService ? appendEpoch : preserveBrowserService ? previous?.appendEpoch ?? null
+        : useCapture ? null : previous?.appendEpoch ?? null,
       appendEpochStartedAt: useBrowserService ? appendEpochStartedAt : previous?.appendEpochStartedAt ?? null,
       appendSnapshotAt: useBrowserService ? appendSnapshotAt : previous?.appendSnapshotAt ?? null,
-      appendService: useBrowserService ? incomingAppendService : previous?.appendService ?? null,
-      fragmentService: useBrowserService ? incomingFragmentService : previous?.fragmentService ?? null,
-      appendServiceReceivedAt: useBrowserService ? now : previous?.appendServiceReceivedAt ?? null,
-      bufferedAheadSec: held,
+      appendService: useBrowserService ? incomingAppendService : preserveBrowserService ? previous?.appendService ?? null
+        : useCapture ? null : previous?.appendService ?? null,
+      fragmentService: useBrowserService ? incomingFragmentService : preserveBrowserService ? previous?.fragmentService ?? null
+        : useCapture ? null : previous?.fragmentService ?? null,
+      appendServiceReceivedAt: useBrowserService ? now : preserveBrowserService ? previous?.appendServiceReceivedAt ?? null
+        : useCapture ? null : previous?.appendServiceReceivedAt ?? null,
+      bufferedAheadSec: preserveCapture ? previous?.bufferedAheadSec ?? 0 : useCapture ? held : 0,
       timestampOffsets: Object.fromEntries(["video", "audio"].filter((key) =>
         Number.isFinite(timestampOffsets?.[key])).map((key) => [key, timestampOffsets[key]])),
-      bufferedRanges: bufferedRanges && typeof bufferedRanges === "object" ?
+      bufferedRanges: preserveCapture ? previous?.bufferedRanges ?? null : useCapture && bufferedRanges && typeof bufferedRanges === "object" ?
         Object.fromEntries(["video", "audio", "media"].filter((key) => Array.isArray(bufferedRanges[key]))
           .map((key) => [key, bufferedRanges[key].slice(0, 256).filter((range) =>
             Number.isFinite(range?.start) && Number.isFinite(range?.end) && range.start >= 0 && range.end > range.start)
             .map(({ start, end }) => ({ start, end }))])) : null,
-      bufferLimitSeconds: Number.isFinite(bufferLimitSeconds) && bufferLimitSeconds > 0
+      bufferLimitSeconds: preserveCapture ? previous?.bufferLimitSeconds ?? null : useCapture && Number.isFinite(bufferLimitSeconds) && bufferLimitSeconds > 0
         ? bufferLimitSeconds
-        : this.netReport?.bufferLimitSeconds ?? null,
+        : useCapture ? null : this.netReport?.bufferLimitSeconds ?? null,
       positionSeconds:
         Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : null,
       at: now

package/services/viewer/ViewerPlaybackState.js

@@ -46,11 +46,15 @@ export class ViewerPlaybackState {
     return removed;
   }
 
-  addLinkReading(state, at, mbps) {
-    state.link.add(at, mbps * 1_000_000);
+  addLinkReading(state, at, mbps, capture = null) {
+    state.link.add(at, mbps * 1_000_000, capture);
   }
 
-  sourceRateReadings(state, id, stats, now, playbackReadiness, lookaheadSeconds) {
+  forgetLinkReadings(state, playbackReadiness, lookaheadSeconds) {
+    if (state) state.link = new playbackReadiness.RateTrend(lookaheadSeconds);
+  }
+
+  sourceRateReadings(state, id, stats, now, playbackReadiness, lookaheadSeconds, capture = null) {
     let source = state.sources.get(id);
     if (!source) {
       const { RateTrend, SessionRate } = playbackReadiness;
@@ -58,15 +62,16 @@ export class ViewerPlaybackState {
         deliveredAll: new SessionRate(), freeAll: new SessionRate(), limit: null };
       state.sources.set(id, source);
     }
+    const readingCapture = capture ?? stats?.sourceCapture ?? null;
     if (Number.isFinite(stats?.downloadSpeed) && stats.downloadSpeed >= 0) {
-      source.delivered.add(now, stats.downloadSpeed);
-      source.deliveredAll.add(now, stats.downloadSpeed);
+      source.delivered.add(now, stats.downloadSpeed, readingCapture);
+      source.deliveredAll.add(now, stats.downloadSpeed, readingCapture);
     }
     const limit = stats?.selectionLimit;
     if (limit && source.limit && limit.freeMs > source.limit.freeMs) {
       const free = Math.max(0, limit.freeBytes - source.limit.freeBytes) * 1000 / (limit.freeMs - source.limit.freeMs);
-      source.free.add(now, free);
-      source.freeAll.add(now, free);
+      source.free.add(now, free, readingCapture);
+      source.freeAll.add(now, free, readingCapture);
     }
     if (limit) source.limit = limit;
     return sourceService(source.free.snapshot(), source.delivered.snapshot(),
@@ -85,6 +90,19 @@ export class ViewerPlaybackState {
     return source ? { free: source.free.snapshot(), delivered: source.delivered.snapshot() } : null;
   }
 
+  sourceCaptureSnapshot(state, id) {
+    const source = state.sources.get(id);
+    if (!source) return null;
+    return {
+      recent: { delivered: source.delivered.captureSnapshot(), free: source.free.captureSnapshot() },
+      tail: { delivered: source.deliveredAll.captureSnapshot(), free: source.freeAll.captureSnapshot() }
+    };
+  }
+
+  forgetSourceReadings(state, id) {
+    state?.sources.delete(id);
+  }
+
   getWait(viewer, waitId) {
     return this.#stateFor(viewer)?.waits.get(waitId) ?? null;
   }

package/services/viewer/playback-readiness.js

@@ -149,14 +149,16 @@ export class SessionRate {
   #inverseSum = 0;
   #zero = false;
   #weighted = 0;
+  #capture = null;
 
-  add(at, value) {
+  add(at, value, capture = null) {
     if (!Number.isFinite(at) || !Number.isFinite(value) || value < 0 || at <= (this.#last?.at ?? Number.NEGATIVE_INFINITY)) {
       return false;
     }
     if (this.#last) this.#weighted += this.#last.value * (at - this.#last.at);
     this.#first ??= { at, value };
     this.#last = { at, value };
+    this.#capture = mergeCaptureSummary(this.#capture, capture);
     this.#count += 1;
     this.#sum += value;
     if (value > 0) this.#inverseSum += 1 / value;
@@ -177,6 +179,10 @@ export class SessionRate {
       spanSeconds: spanMs / 1000
     };
   }
+
+  captureSnapshot() {
+    return this.#capture ? { ...this.#capture } : null;
+  }
 }
 
 /**
@@ -192,12 +198,12 @@ export class RateTrend {
     this.#horizonMs = Math.max(0, horizonSeconds) * 1000;
   }
 
-  add(at, value) {
+  add(at, value, capture = null) {
     if (!Number.isFinite(at) || !Number.isFinite(value) || value < 0 ||
       at <= (this.#readings.at(-1)?.at ?? Number.NEGATIVE_INFINITY)) {
       return false;
     }
-    this.#readings.push({ at, value });
+    this.#readings.push({ at, value, capture: capture ? { ...capture } : null });
     const cutoff = at - this.#horizonMs;
     while (this.#readings.length > 1 && this.#readings[1].at <= cutoff) {
       this.#readings.shift();
@@ -211,6 +217,22 @@ export class RateTrend {
     }
     return summarizeRate(this.#readings);
   }
+
+  captureSnapshot() {
+    return this.#readings.map(reading => reading.capture ? { ...reading.capture } : null);
+  }
+}
+
+function mergeCaptureSummary(previous, capture) {
+  if (!capture || capture.validity !== "valid" || !Number.isFinite(capture.clockEpoch) ||
+      !Number.isFinite(capture.startedAt) || !Number.isFinite(capture.completedAt) ||
+      capture.completedAt < capture.startedAt) return { validity: "unknown", unknownReason: "missing-rate-capture" };
+  if (!previous) return { ...capture };
+  if (previous.validity !== "valid" || previous.clockEpoch !== capture.clockEpoch) {
+    return { validity: "invalid", unknownReason: "rate-capture-epoch-mismatch" };
+  }
+  return { ...previous, startedAt: Math.min(previous.startedAt, capture.startedAt),
+    completedAt: Math.max(previous.completedAt, capture.completedAt), revision: capture.revision };
 }
 
 /**