@torrent-tv/proxy 2.107.52 → 2.107.54

package/services/server/wire-outputs.js

@@ -107,6 +107,9 @@ import { describeProcessor, processorBetween, sampleProcessor } from "../storage
 import { ProcessorBudget } from "../encode/ProcessorBudget.js";
 import { ENCODE_RUN_STATE, processCanBeSignalled } from "../encode/encode-run-state.js";
 import { secondsUntilClosed } from "../encode/piece-close-time.js";
+import { ViewerPlaybackState } from "../viewer/ViewerPlaybackState.js";
+import { OutputForecastGeometry } from "../viewer/OutputForecastGeometry.js";
+import { ForecastDiagnostics } from "./ForecastDiagnostics.js";
 
 // Where a variant and an audio rendition live under a session — `v/<height>/…`
 // and `a/<track>/…` — is stated in `encode/output/playlists.js`, beside the lines that
@@ -249,6 +252,14 @@ export function wireOutputs({
   // output key owns its record, and the graph releases it at the last session.
   const waits = new WaitLedger();
   const parts = {};
+  parts.viewerPlaybackState = new ViewerPlaybackState();
+  parts.outputForecastGeometry = new OutputForecastGeometry({
+    lookaheadSeconds: LOOKAHEAD_PAUSE_SECONDS,
+    finishedMediaRangesOf: (output, index) => parts.encodeRuns.finishedMediaRangesOf(output, index),
+    sourceInputsFor: (output, index) => parts.sourceInputsFor?.(output, index),
+    endsWithinPlayerSeekTolerance
+  });
+  parts.forecastDiagnostics = new ForecastDiagnostics({ logger });
   const audioDescriptionOf = (output) => (getCachedAudioTracks?.({
     sourceKey: output.file.sourceKey, fileIndex: output.spec.grid?.fileIndex ?? output.file.fileIndex
   }) ?? []).find((track) => track.fileIndex === output.spec.audio?.fileIndex &&
@@ -573,6 +584,9 @@ export function wireOutputs({
     planEncodersSoon: () => parts.encodeRuns.planEncodersSoon(),
     invalidateWaits: (output) => parts.serving.invalidateWaits(output),
     clearWaits: () => waits.clear(),
+    forgetForecastOutput: (output) => parts.viewerRequests.outputDisposed(output),
+    viewerDeparted: (viewer) => parts.viewerRequests.viewerDeparted(viewer),
+    outputViewerDeparted: (viewer, output) => parts.viewerRequests.outputViewerDeparted(viewer, output),
     segmentFormatOfKey,
     // Where the viewers of one output stand, in its segments: what the store
     // the output retention policy reads to give disk back in the right order.
@@ -632,6 +646,9 @@ export function wireOutputs({
   // What a viewer asks for: an output of a file, a position, a report of progress.
   parts.viewerRequests = new ViewerRequests({
     observeWait,
+    viewerPlaybackState: parts.viewerPlaybackState,
+    outputForecastGeometry: parts.outputForecastGeometry,
+    noteForecast: (...args) => parts.forecastDiagnostics.note(...args),
     // Whether this machine has a place for one more viewer on this output —
     // asked in the same synchronous stretch as they are put on it.
     admitsWatching: (output) => parts.admission.admitsWatching(output?.outputKey ?? ""),

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/OutputForecastGeometry.js

@@ -0,0 +1,87 @@
+/**
+ * Cached piece geometry for playback forecasts. It is keyed by a live output
+ * object and explicitly forgotten when that output is disposed.
+ */
+export class OutputForecastGeometry {
+  #byOutput = new Map();
+  #host;
+
+  constructor(host) {
+    this.#host = host;
+  }
+
+  get(output) {
+    return this.#byOutput.get(output) ?? null;
+  }
+
+  forget(output) {
+    return this.#byOutput.delete(output);
+  }
+
+  size() {
+    return this.#byOutput.size;
+  }
+
+  segmentsOf(output, sessionInit, inventory, positionSeconds) {
+    const timeline = output.timeline;
+    const count = timeline?.segmentCount ?? 0;
+    let forecast = this.#byOutput.get(output);
+    if (!forecast) {
+      forecast = { pieces: [], geometry: {} };
+      this.#byOutput.set(output, forecast);
+    }
+    const kept = forecast.pieces;
+    const segments = [];
+    const lookahead = Number(this.#host.lookaheadSeconds);
+    const start = Number.isFinite(positionSeconds) ? Math.max(0, positionSeconds) : 0;
+    const end = Number.isFinite(lookahead) && lookahead > 0 ? start + lookahead : Number.POSITIVE_INFINITY;
+    let low = 0, high = count;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (timeline.publishedStartOf(middle + 1) <= start) low = middle + 1;
+      else high = middle;
+    }
+    const first = Math.max(0, low - 1);
+    low = first;
+    high = count;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (timeline.publishedStartOf(middle) < end) low = middle + 1;
+      else high = middle;
+    }
+    const last = low;
+    const indexes = new Set([0]);
+    for (let index = first; index < last; index++) indexes.add(index);
+    for (const index of indexes) {
+      const endSeconds = timeline.publishedStartOf(index + 1);
+      const ranges = inventory.has(index) ? this.#host.finishedMediaRangesOf(output, index) : undefined;
+      const mediaRanges = ranges && output.segmentFormat?.servedMediaRanges ?
+        output.segmentFormat.servedMediaRanges(ranges, { initBytes: sessionInit }) : undefined;
+      if (index !== 0 && mediaRanges === undefined && !inventory.has(index) &&
+        Number.isFinite(endSeconds) && Number.isFinite(positionSeconds) &&
+        !this.#host.endsWithinPlayerSeekTolerance(endSeconds, positionSeconds) &&
+        endSeconds < positionSeconds) {
+        continue;
+      }
+      const startSeconds = timeline.publishedStartOf(index);
+      const sourceInputs = this.#host.sourceInputsFor?.(output, index) ?? undefined;
+      const previous = kept[index];
+      if (previous && previous.startSeconds === startSeconds && previous.endSeconds === endSeconds &&
+        previous.mediaRanges === mediaRanges && sameInputs(previous.sourceInputs, sourceInputs)) {
+        segments.push(previous);
+        continue;
+      }
+      const segment = { index, startSeconds, endSeconds, sourceInputs, mediaRanges };
+      kept[index] = segment;
+      segments.push(segment);
+    }
+    if (kept.length > count) kept.length = count;
+    return segments;
+  }
+}
+
+function sameInputs(left, right) {
+  if (left === right) return true;
+  if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+  return left.every((input, index) => input.sourceId === right[index].sourceId && input.ranges === right[index].ranges);
+}

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

@@ -0,0 +1,233 @@
+/**
+ * Cross-request measurements owned by one live viewing. A viewer is the key,
+ * rather than its reusable wire id, so a later viewing with the same id starts
+ * with fresh measurements.
+ */
+export class ViewerPlaybackState {
+  #byViewer = new Map();
+  #waitOrder = new Map();
+
+  #stateFor(viewer, create = false) {
+    if (!viewer || typeof viewer !== "object") return null;
+    let state = this.#byViewer.get(viewer);
+    if (!state && create) {
+      state = { ratesByOutput: new Map(), waits: new Map() };
+      this.#byViewer.set(viewer, state);
+    }
+    return state ?? null;
+  }
+
+  rateState(viewer, output, playbackReadiness, lookaheadSeconds) {
+    const owner = this.#stateFor(viewer, true);
+    let state = owner.ratesByOutput.get(output);
+    if (!state) {
+      state = { link: new playbackReadiness.RateTrend(lookaheadSeconds), sources: new Map() };
+      owner.ratesByOutput.set(output, state);
+    }
+    return state;
+  }
+
+  owns(viewer, output, state) {
+    return this.#stateFor(viewer)?.ratesByOutput.get(output) === state;
+  }
+
+  forgetOutput(output) {
+    for (const [viewer, owner] of this.#byViewer) {
+      owner.ratesByOutput.delete(output);
+      this.#deleteIfEmpty(viewer, owner);
+    }
+  }
+
+  forgetViewerOutput(viewer, output) {
+    const owner = this.#stateFor(viewer);
+    if (!owner) return false;
+    const removed = owner.ratesByOutput.delete(output);
+    this.#deleteIfEmpty(viewer, owner);
+    return removed;
+  }
+
+  addLinkReading(state, at, mbps, capture = null) {
+    state.link.add(at, mbps * 1_000_000, capture);
+  }
+
+  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;
+      source = { delivered: new RateTrend(lookaheadSeconds), free: new RateTrend(lookaheadSeconds),
+        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, 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, readingCapture);
+      source.freeAll.add(now, free, readingCapture);
+    }
+    if (limit) source.limit = limit;
+    return sourceService(source.free.snapshot(), source.delivered.snapshot(),
+      summary => playbackReadiness.forecastRate(summary, now, 0, "time"));
+  }
+
+  sourceTailRateReadings(state, id, now, playbackReadiness) {
+    const source = state.sources.get(id);
+    if (!source) return null;
+    return sourceService(source.freeAll.snapshot(), source.deliveredAll.snapshot(),
+      summary => playbackReadiness.forecastRate(summary, now, 0, "time"));
+  }
+
+  sourceRateSummaries(state, id) {
+    const source = state.sources.get(id);
+    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;
+  }
+
+  hasWait(viewer, waitId) {
+    return this.#stateFor(viewer)?.waits.has(waitId) ?? false;
+  }
+
+  recordWaitSnapshot({ viewer, consumerId, generation, sourceKey, fileIndex, waitId, features }) {
+    const owner = this.#stateFor(viewer, true);
+    const current = owner.waits.get(waitId);
+    const context = current?.waitId === waitId ? current : {
+      consumerId, generation, sourceKey, fileIndex, waitId, snapshots: [], observedWaits: new Set()
+    };
+    const measuredAt = performance.now();
+    const ageElapsedMs = Number.isFinite(context.featuresMeasuredAt)
+      ? Math.max(0, measuredAt - context.featuresMeasuredAt) : 0;
+    const mergedFeatures = mergeWaitFeatures(context.features, features, ageElapsedMs);
+    Object.assign(context, { consumerId, generation, sourceKey, fileIndex, waitId, features: mergedFeatures,
+      featuresMeasuredAt: measuredAt, updatedAt: Date.now() });
+    const previous = context.snapshots.at(-1);
+    if (!previous || JSON.stringify(previous) !== JSON.stringify(mergedFeatures)) {
+      const snapshot = { ...mergedFeatures };
+      if (context.snapshots.length < 2) context.snapshots.push(snapshot);
+      else context.snapshots[1] = snapshot;
+    }
+    owner.waits.set(waitId, context);
+    if (!this.#waitOrder.has(context)) this.#waitOrder.set(context, { viewer, waitId });
+    return context;
+  }
+
+  noteFirstFrame({ viewer, generation, waitId, wait, elapsedMs, stages, record }) {
+    const observation = this.getWait(viewer, waitId);
+    if (!observation || observation.generation !== generation || !Number.isSafeInteger(wait) || wait < 0 ||
+        observation.observedWaits.has(wait) || !Number.isFinite(elapsedMs) || elapsedMs < 0) return false;
+    const initialFeatures = observation.snapshots[0];
+    if (initialFeatures) record({ seconds: elapsedMs / 1000, features: initialFeatures,
+      featureSnapshots: observation.snapshots.slice(1), stages });
+    observation.observedWaits.add(wait);
+    observation.updatedAt = Date.now();
+    return true;
+  }
+
+  deleteWait(viewer, waitId) {
+    const owner = this.#stateFor(viewer);
+    if (!owner) return false;
+    const context = owner.waits.get(waitId);
+    const removed = owner.waits.delete(waitId);
+    if (context) this.#waitOrder.delete(context);
+    this.#deleteIfEmpty(viewer, owner);
+    return removed;
+  }
+
+  pruneWaits(now = Date.now(), maxObservations = 1000) {
+    const cutoff = now - 30 * 60_000;
+    for (const [viewer, owner] of this.#byViewer) {
+      for (const [waitId, value] of owner.waits) {
+        if (value.updatedAt < cutoff) {
+          owner.waits.delete(waitId);
+          this.#waitOrder.delete(value);
+        }
+      }
+      if (owner) this.#deleteIfEmpty(viewer, owner);
+    }
+    while (this.#waitOrder.size > maxObservations) {
+      const [context, { viewer, waitId }] = this.#waitOrder.entries().next().value;
+      const owner = this.#stateFor(viewer);
+      owner?.waits.delete(waitId);
+      this.#waitOrder.delete(context);
+      if (owner) this.#deleteIfEmpty(viewer, owner);
+    }
+  }
+
+  forgetViewer(viewer) {
+    const owner = this.#stateFor(viewer);
+    if (!owner) return false;
+    for (const context of owner.waits.values()) this.#waitOrder.delete(context);
+    return this.#byViewer.delete(viewer);
+  }
+
+  viewerCount() {
+    return this.#byViewer.size;
+  }
+
+  waitCount(viewer) {
+    return this.#stateFor(viewer)?.waits.size ?? 0;
+  }
+
+  #deleteIfEmpty(viewer, owner) {
+    if (owner.ratesByOutput.size === 0 && owner.waits.size === 0) this.#byViewer.delete(viewer);
+  }
+}
+
+export function sourceService(free, delivered, rateOf) {
+  if (!free) return delivered;
+  if (!delivered) return free;
+  return (rateOf(delivered) ?? 0) > (rateOf(free) ?? 0) ? delivered : free;
+}
+
+function mergeWaitFeatures(previous, incoming, ageElapsedMs) {
+  const merged = { ...(previous ?? {}) };
+  for (const [key, value] of Object.entries(incoming ?? {})) {
+    if (value === null || value === undefined) {
+      if (!Object.hasOwn(merged, key)) merged[key] = null;
+      continue;
+    }
+    if (key === "extension") {
+      if (typeof value === "string" && value.length > 0) merged[key] = value;
+      continue;
+    }
+    if (key === "fileAvailable") {
+      if (typeof value === "boolean") merged[key] = value;
+      continue;
+    }
+    if (key === "videoOperation" || key === "audioOperation") {
+      if (value === "copy" || value === "encode") merged[key] = value;
+      continue;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 ||
+        ((key === "fileLength" || key === "linkMbps") && value === 0)) continue;
+    merged[key] = value;
+  }
+  const hasIncomingAge = Number.isFinite(incoming?.linkSampleAgeMs) && incoming.linkSampleAgeMs >= 0;
+  if (Number.isFinite(merged.linkSampleAgeMs) && !hasIncomingAge) {
+    merged.linkSampleAgeMs += Number.isFinite(ageElapsedMs) ? Math.max(0, ageElapsedMs) : 0;
+  }
+  return merged;
+}