@torrent-tv/proxy 2.107.47 → 2.107.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.107.47",
+  "version": "2.107.49",
   "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

@@ -20,6 +20,7 @@ import { performance } from "node:perf_hooks";
  * @returns {Promise<void>}
  */
 export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool, viewerRequests }) {
+  const requestReceivedAtProxyMs = performance.now();
   const sourceKey = typeof req.params.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
     return reply.code(400).send({ error: "sourceKey is required." });
@@ -67,10 +68,12 @@ 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) {
@@ -154,5 +157,11 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
       fileName: torrent.files?.[fileIndex]?.name ?? requestedFileName, fileLength: requestedFileLength,
       stats, ...earlyLink });
   }
-  return reply.send(stats);
+  const responsePreparedAtProxyMs = performance.now();
+  return reply.send({ ...stats, sourceSnapshotTransport: {
+    requestReceivedAtProxyMs,
+    snapshotStartedAtProxyMs: statsStartedAt,
+    snapshotCompletedAtProxyMs: statsCompletedAt,
+    responsePreparedAtProxyMs
+  } });
 }

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

@@ -8,7 +8,9 @@ import { recordViewerReport } from "../../../../services/viewer/report-intake.js
  *
  * POST /api/transcode-sessions/:sessionId/net-report
  * Body: { consumerId: string, bufferedAheadSec: number, linkMbps?: number,
- *         positionSeconds?: number, playingHeight?: number, … }
+ *         positionSeconds?: number, playingHeight?: number, appendEpoch?: string,
+ *         appendEpochStartedAt?: number, appendSnapshotAt?: number,
+ *         appendService?: object, fragmentService?: object, … }
  *
  * `consumerId` and `positionSeconds` say WHO is reporting and WHERE they are.
  * A copied picture is one session shared by every viewer of it, so without them
@@ -115,6 +117,14 @@ 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,
+      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,
+      appendService: body.appendService && typeof body.appendService === "object" ? body.appendService : undefined,
+      fragmentService: body.fragmentService && typeof body.fragmentService === "object" ? body.fragmentService : undefined,
       bufferedAheadSec,
       bufferedRanges: body.bufferedRanges,
       timestampOffsets: body.bufferedRanges?.timestampOffsets,

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

@@ -9,6 +9,7 @@
  * @returns {Promise<void>}
  */
 export async function handleApiTranscodeSessionsProgressGet(req, reply, { viewerRequests }) {
+  const requestReceivedAtProxyMs = performance.now();
   const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
   if (!sessionId) {
     return reply.code(400).send({ error: "sessionId is required." });
@@ -23,5 +24,11 @@ export async function handleApiTranscodeSessionsProgressGet(req, reply, { viewer
     return reply.code(404).send({ error: "Transcode session was not found." });
   }
 
+  const responsePreparedAtProxyMs = performance.now();
+  progress.snapshotTransport = {
+    requestReceivedAtProxyMs,
+    snapshotAtProxyMs: progress.playbackReadiness?.snapshotAtProxyMs ?? null,
+    responsePreparedAtProxyMs
+  };
   return reply.send(progress);
 }

package/services/server/OutputLifecycle.js

@@ -427,6 +427,7 @@ export class OutputLifecycle {
     if (!output) {
       return false;
     }
+    this.#host.releasePlaybackStorageDemand?.(output.outputKey ?? "", consumerId);
     // Nothing to release in the encoding: it holds one map per output, built
     // from where the viewers are, and the map that arrives next simply does not
     // have this one in it. A name to release was the last place a viewer

package/services/server/ViewerRequests.js

@@ -41,6 +41,36 @@ function sameInputs(left, right) {
   return left.every((input, index) => input.sourceId === right[index].sourceId && input.ranges === right[index].ranges);
 }
 
+function browserServiceSummary(value) {
+  if (!value || typeof value !== "object") return null;
+  return Object.fromEntries(["init", "media"].filter(kind => value[kind]).map(kind => [kind, value[kind]]).map(([kind, service]) => [kind, {
+    bytes: service.bytes,
+    elapsedMs: service.elapsedMs,
+    operations: service.operations,
+    sampleCount: service.samples.length,
+    newestSampleAgeMs: service.samples.reduce((age, sample) => age === null ? sample.ageMs : Math.min(age, sample.ageMs), null),
+    samples: service.samples.map(({ bytes, elapsedMs, ageMs, fragmentId, fragmentSequence, partIndex, fragmentStartSeconds,
+      parseElapsedMs, bufferingElapsedMs, bufferingAgeMs, eventAgesMs }) => ({ bytes, elapsedMs, ageMs, fragmentId,
+      fragmentSequence, partIndex, fragmentStartSeconds,
+      ...(parseElapsedMs === null || parseElapsedMs === undefined ? {} : { parseElapsedMs }),
+      ...(bufferingElapsedMs === null || bufferingElapsedMs === undefined ? {} : { bufferingElapsedMs }),
+      ...(bufferingAgeMs === null || bufferingAgeMs === undefined ? {} : { bufferingAgeMs }),
+      ...(eventAgesMs ? { eventAgesMs } : {}) }))
+  }]));
+}
+
+function browserServiceFingerprint(tracks) {
+  const serviceFingerprint = service => service ? ["init", "media"].map(kind => {
+    const value = service[kind];
+    return value ? [kind, value.bytes, value.elapsedMs, value.operations, value.samples.map(sample => [
+      sample.bytes, sample.elapsedMs, sample.fragmentId, sample.fragmentSequence, sample.partIndex,
+      sample.fragmentStartSeconds, sample.parseElapsedMs, sample.bufferingElapsedMs
+    ])] : [kind, null];
+  }) : null;
+  return JSON.stringify(tracks.map(track => [track.id,
+    serviceFingerprint(track.appendService), serviceFingerprint(track.fragmentService)]));
+}
+
 export function forecastInputState(tracks, identity) {
   if (!identity) return null;
   const track = tracks.find(candidate => candidate.id === identity.trackId);
@@ -912,6 +942,19 @@ export class ViewerRequests {
         clockOffsetSeconds: placedByPlayer ? playerOffset : 0,
         clientRanges: viewerReading?.bufferedRanges?.[output === session ? "video" : "audio"] ??
           viewerReading?.bufferedRanges?.media,
+        // 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]
+          ? { ...viewerReading.appendService[trackName], epoch: viewerReading.appendEpoch,
+            epochStartedAt: viewerReading.appendEpochStartedAt, snapshotAt: viewerReading.appendSnapshotAt,
+            receivedAt: viewerReading.appendServiceReceivedAt }
+          : null,
+        fragmentService: 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,
@@ -970,9 +1013,8 @@ export class ViewerRequests {
       bufferLimitSeconds: viewerReading?.bufferLimitSeconds,
       reserveSeconds,
       lookaheadSeconds: this.#host.lookaheadSeconds,
-      // What this proxy may keep of downloaded pieces on disk: the most a
-      // start can hold of the film ahead of the viewer.
-      sourceStorageBytes: this.#host.sourceStorageBytes?.() ?? null,
+      // Disk room remaining after stock reserved for other active outputs.
+      sourceStorageBytes: this.#host.sourceStorageBytes?.(session.outputKey ?? session.id) ?? null,
       requiredAudio: requiresSeparateAudio,
       sources: [...sourceMeasurements.values()],
       tracks,
@@ -985,6 +1027,9 @@ export class ViewerRequests {
       viewer.subtitle.fileIndex === session.file.fileIndex ? viewer.subtitle : null;
     const startedAt = performance.now();
     const predicted = this.#host.playbackReadiness.predict(input);
+    if (consumerId && viewer && this.#host.viewers.get(consumerId) === viewer && Number.isFinite(predicted.cushionBytes)) {
+      this.#host.notePlaybackStorageDemand?.(session.outputKey ?? session.id, consumerId, predicted.cushionBytes);
+    }
     const predictMs = performance.now() - startedAt;
     this.#noteForecast(predictMs, tracks.map(track => track.geometry?.reason ?? "none"));
     logger.info(`readiness parts ${session.id} consumer=${consumerId}: source stats ${Math.round(parts.statsMs)}ms ` +
@@ -992,6 +1037,7 @@ export class ViewerRequests {
       `start forecast ${Math.round(predictMs)}ms, in all ${Math.round(performance.now() - parts.enteredAt)}ms`);
     const forecast = withSubtitleReadiness(predicted, subtitle,
       subtitle ? this.#host.subtitleReadyFor?.(viewer) !== false : true);
+    forecast.snapshotAtProxyMs = startedAt;
     forecast.operations = outputs.flatMap((output, index) => {
       const common = { speed: this.#host.playbackReadiness.forecastRate(tracks[index].readings, now, 0, "piece"),
         processedSeconds: tracks[index].processedSeconds,
@@ -1049,9 +1095,13 @@ export class ViewerRequests {
     const forecastInputKey = unavailableInput ? JSON.stringify([
       unavailableInput.sourceId, unavailableInput.trackId, unavailableInput.segmentIndex, unavailableInput.phase
     ]) : null;
-    if (measurement.forecastReason !== forecast.reason || measurement.forecastInputKey !== forecastInputKey) {
+    const browserEvidenceKey = browserServiceFingerprint(tracks);
+    const browserEvidenceChanged = measurement.browserEvidenceKey !== browserEvidenceKey;
+    if (measurement.forecastReason !== forecast.reason || measurement.forecastInputKey !== forecastInputKey ||
+        browserEvidenceChanged) {
       measurement.forecastReason = forecast.reason;
       measurement.forecastInputKey = forecastInputKey;
+      measurement.browserEvidenceKey = browserEvidenceKey;
       if (forecast.subtitles) this.#host.observeWait?.(session.file.sourceKey, "process", {
         process: "C3", phase: "event", fileIndex: session.file.fileIndex,
         trackIndex: forecast.subtitles.trackIndex, ready: forecast.subtitles.ready,
@@ -1073,8 +1123,10 @@ export class ViewerRequests {
           downloadRateBytesPerSecond: this.#host.playbackReadiness.forecastRate(downloadRateReadings, now, 0, "time"),
           downloadRateSummaries
         })),
-        tracks: tracks.map(({ id, processedSeconds, readings, segments, readySegmentIndices }) => ({
-          id, processedSeconds, readings, segments: segments.length, prepared: readySegmentIndices.length
+        tracks: tracks.map(({ id, processedSeconds, readings, segments, readySegmentIndices, appendService, fragmentService }) => ({
+          id, processedSeconds, readings, appendService: browserServiceSummary(appendService),
+          fragmentService: browserServiceSummary(fragmentService), segments: segments.length,
+          prepared: readySegmentIndices.length
         }))
       })}`);
     }

package/services/server/wire-outputs.js

@@ -95,6 +95,7 @@ import { audioReadingFor } from "../encode/audio-work-rate.js";
 import { wireMachineBudget } from "../storage/wire.js";
 import { Returns } from "../storage/returns.js";
 import { freeBytesFor } from "../storage/free.js";
+import { PlaybackStorageDemand } from "../storage/PlaybackStorageDemand.js";
 import { inputCacheRoot, probeInputCache } from "../encode/input-cache.js";
 import path from "node:path";
 import { contentOf, LocalObservations, PROXY_ROOT } from "../encode/LocalObservations.js";
@@ -579,6 +580,7 @@ export function wireOutputs({
     get encodeRuns() { return parts.encodeRuns; },
     get keyframeTables() { return parts.keyframeTables; },
     get machineBudget() { return parts.machineBudget; },
+    releasePlaybackStorageDemand: (key, consumerId) => parts.playbackStorageDemand.release(key, consumerId),
     get outputTimes() { return parts.outputTimes; },
     get outputs() { return parts.outputs; },
     get returns() { return parts.returns; },
@@ -629,7 +631,13 @@ export function wireOutputs({
     viewerSecondsOn: (output, consumerId, now) => viewerSecondsOn(parts.viewers, output, consumerId, now),
     minimumBufferSecondsFor: (output) => minimumBufferSecondsOf(output),
     // What this proxy may keep of downloaded pieces on disk.
-    sourceStorageBytes: () => parts.machineBudget?.allowedFor("spilled pieces") ?? null,
+    sourceStorageBytes: outputKey => {
+      const capacity = parts.machineBudget?.storageBytes();
+      return Number.isFinite(capacity)
+        ? Math.max(0, capacity - parts.playbackStorageDemand.bytesExcept(outputKey))
+        : null;
+    },
+    notePlaybackStorageDemand: (key, consumerId, bytes) => parts.playbackStorageDemand.note(key, consumerId, bytes),
     getSourceStats: (...args) => parts.getSourceStats?.(...args) ?? null,
     disposeSession: (...args) => parts.lifecycle.disposeSession(...args),
     planEncodersSoon: (...args) => parts.encodeRuns.planEncodersSoon(...args),
@@ -1173,6 +1181,11 @@ export function wireOutputs({
   // one term of the keeping period that is guessed rather than measured, and
   // the only place it can be measured from.
   parts.returns = new Returns();
+  parts.playbackStorageDemand = new PlaybackStorageDemand(() => {
+    if (parts.machineBudget) {
+      void parts.machineBudget.revise(parts.machineBudget.storageResource, "playback stock");
+    }
+  });
   parts.encodeInputs = encodeInputs ?? (typeof resolveEncodeInput === "function" ? new EncodeInputs({
     resolve: resolveEncodeInput,
     readRanges: readEncodeRanges,
@@ -1221,6 +1234,7 @@ export function wireOutputs({
     // FFmpeg's cache keeps its file in /tmp, or where FFmpeg runs on a build
     // without `mkstemp` — an output directory of the segments.
     inputCaches: { held: () => parts.encodeRuns?.inputCacheBytes() ?? 0, root: inputCacheRoot() },
+    playbackStorage: parts.playbackStorageDemand,
     policy: parts.budgetPolicy ?? undefined,
     readFree: freeBytesFor,
     logger

package/services/storage/PlaybackStorageDemand.js

@@ -0,0 +1,64 @@
+/**
+ * The bytes an active playback forecast says must remain available on disk.
+ * Viewers of one output share its stored bytes, so its demand is the largest
+ * live viewer demand; distinct outputs add their requirements.
+ */
+export class PlaybackStorageDemand {
+  #byOutput = new Map();
+  #changed;
+
+  constructor(changed = () => {}) {
+    this.#changed = changed;
+  }
+
+  /** @returns {number} */
+  bytes() {
+    let total = 0;
+    for (const viewers of this.#byOutput.values()) {
+      let shared = 0;
+      for (const bytes of viewers.values()) shared = Math.max(shared, bytes);
+      total += shared;
+    }
+    return total;
+  }
+
+  /** @param {string} outputKey @returns {number} */
+  bytesExcept(outputKey) {
+    let total = 0;
+    for (const [key, viewers] of this.#byOutput) {
+      if (key === outputKey) continue;
+      let shared = 0;
+      for (const bytes of viewers.values()) shared = Math.max(shared, bytes);
+      total += shared;
+    }
+    return total;
+  }
+
+  /** @param {string} outputKey @param {string} consumerId @param {number} bytes */
+  note(outputKey, consumerId, bytes) {
+    if (!outputKey || !consumerId || !Number.isFinite(bytes) || bytes < 0) return;
+    const before = this.bytes();
+    let viewers = this.#byOutput.get(outputKey);
+    if (!viewers) {
+      viewers = new Map();
+      this.#byOutput.set(outputKey, viewers);
+    }
+    viewers.set(consumerId, bytes);
+    this.#notifyIfChanged(before);
+  }
+
+  /** @param {string} outputKey @param {string} consumerId */
+  release(outputKey, consumerId) {
+    const viewers = this.#byOutput.get(outputKey);
+    if (!viewers?.has(consumerId)) return;
+    const before = this.bytes();
+    viewers.delete(consumerId);
+    if (viewers.size === 0) this.#byOutput.delete(outputKey);
+    this.#notifyIfChanged(before);
+  }
+
+  #notifyIfChanged(before) {
+    const after = this.bytes();
+    if (after !== before) this.#changed(after);
+  }
+}

package/services/storage/wire.js

@@ -10,7 +10,9 @@
  * segments an encoder produced, the files downloaded whole — and the evidence,
  * which is a claimant with a rule of its own (`Diagnostics.js`). Three of the
  * five live on the torrent thread, so they arrive as pairs of closures over its
- * channel rather than as the objects themselves.
+ * channel rather than as the objects themselves. Active playback also
+ * reserves its forecasted source stock here; that is a requirement, not a
+ * store holding bytes yet.
  *
  * **Which RESOURCE each takes is read, not assumed.** Memory is one. Disk is
  * one per device, because two filesystems cannot pay for each other: measured
@@ -56,7 +58,7 @@ import { availableMemoryBytes } from "./machine-memory.js";
  * @param {import("./MachineBudget.js").BudgetPolicy} [params.policy] - What the
  *   operator has said this proxy may take. Absent, the measured default.
  * @param {{ info: Function, warn?: Function }} [params.logger]
- * @returns {{ revise: () => Promise<unknown>, segmentBytes: () => number | null, diagnostics: object | null, describe: () => string }}
+ * @returns {{ revise: (resource?: string | null, because?: string | null) => Promise<unknown>, segmentBytes: () => number | null, storageBytes: () => number | null, storageResource: string, diagnostics: object | null, describe: () => string }}
  *   What the segments may hold is asked for rather than pushed: null until the
  *   first revision, then the measured allowance, including a measured zero.
  */
@@ -68,6 +70,7 @@ export function wireMachineBudget({
   indexMemory,
   wholeFiles,
   inputCaches,
+  playbackStorage,
   diagnostics,
   diagnosticsRoot = "",
   readFree,
@@ -177,6 +180,17 @@ export function wireMachineBudget({
     });
   }
 
+  if (typeof playbackStorage?.bytes === "function") {
+    budget.register({
+      name: "playback stock",
+      resource: segmentsOn,
+      held: () => 0,
+      wanted: () => playbackStorage.bytes(),
+      required: () => playbackStorage.bytes(),
+      allow: () => {}
+    });
+  }
+
   let evidenceOn = null;
   if (diagnostics) {
     evidenceOn = diagnosticsRoot ? deviceOf(diagnosticsRoot) : segmentsOn;
@@ -194,6 +208,8 @@ export function wireMachineBudget({
 
   return {
     capacityOf: name => budget.capacityOf(name),
+    storageBytes: () => budget.capacityOf(segmentsOn),
+    storageResource: segmentsOn,
     /** What one claimant was last allowed, or null before a measured division. */
     allowedFor: name => budget.allowedFor(name),
     /**

package/services/viewer/Viewer.js

@@ -43,6 +43,104 @@
 import { Assignments } from "./Assignments.js";
 import { bufferTrend, trendRunStart } from "./buffer-trend.js";
 
+const APPEND_TRACKS = ["video", "audio"];
+const APPEND_KINDS = ["init", "media"];
+const FRAGMENT_EVENT_AGES = ["loadStart", "loadFirstByte", "loadEnd", "parseStart", "parseEnd",
+  "bufferingStart", "bufferingEnd"];
+
+function fragmentEventAges(value) {
+  return Object.fromEntries(FRAGMENT_EVENT_AGES.map(name => [name,
+    Number.isFinite(value?.[name]) && value[name] >= 0 ? value[name] : null]));
+}
+
+function appendServiceSnapshot(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const snapshot = {};
+  for (const track of APPEND_TRACKS) {
+    if (!value[track] || typeof value[track] !== "object" || Array.isArray(value[track])) return null;
+    snapshot[track] = {};
+    for (const kind of APPEND_KINDS) {
+      const item = value[track][kind];
+      if (!item || !Number.isSafeInteger(item.bytes) || item.bytes < 0 || !Number.isSafeInteger(item.operations) ||
+          item.operations < 0 || !Number.isFinite(item.elapsedMs) || item.elapsedMs < 0 ||
+          (item.operations === 0 && (item.bytes > 0 || item.elapsedMs > 0)) ||
+          (item.operations > 0 && (item.bytes === 0 || item.elapsedMs === 0)) || !Array.isArray(item.samples) ||
+          !item.samples.every(sample => Number.isSafeInteger(sample?.bytes) && sample.bytes > 0 &&
+            Number.isFinite(sample.elapsedMs) && sample.elapsedMs > 0 &&
+            Number.isFinite(sample.ageMs) && sample.ageMs >= 0 &&
+            (sample.fragmentId === null || typeof sample.fragmentId === "string" && sample.fragmentId.length <= 128) &&
+            (sample.fragmentSequence === undefined || sample.fragmentSequence === null ||
+              Number.isSafeInteger(sample.fragmentSequence) && sample.fragmentSequence >= 0) &&
+            (sample.partIndex === undefined || sample.partIndex === null ||
+              Number.isSafeInteger(sample.partIndex) && sample.partIndex >= 0) &&
+            (sample.fragmentStartSeconds === null || Number.isFinite(sample.fragmentStartSeconds)))) return null;
+      snapshot[track][kind] = { bytes: item.bytes, elapsedMs: item.elapsedMs, operations: item.operations,
+        samples: item.samples.map(({ bytes, elapsedMs, ageMs, fragmentId, fragmentSequence, partIndex,
+          fragmentStartSeconds }) => ({ bytes, elapsedMs, ageMs, fragmentId,
+          fragmentSequence: fragmentSequence ?? null, partIndex: partIndex ?? null, fragmentStartSeconds })) };
+    }
+  }
+  return snapshot;
+}
+
+function fragmentServiceSnapshot(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const snapshot = {};
+  for (const track of APPEND_TRACKS) {
+    if (!value[track] || typeof value[track] !== "object" || Array.isArray(value[track])) return null;
+    snapshot[track] = {};
+    for (const kind of APPEND_KINDS) {
+      const item = value[track][kind];
+      if (!item || typeof item !== "object" || Array.isArray(item) || !Number.isSafeInteger(item.bytes) || item.bytes < 0 ||
+          !Number.isFinite(item.elapsedMs) || item.elapsedMs < 0 || !Number.isSafeInteger(item.operations) ||
+          item.operations < 0 || (item.operations === 0 && (item.bytes > 0 || item.elapsedMs > 0)) ||
+          (item.operations > 0 && (item.bytes === 0 || item.elapsedMs === 0)) || !Array.isArray(item.samples) ||
+          !item.samples.every(sample => Number.isSafeInteger(sample?.bytes) && sample.bytes > 0 &&
+            Number.isFinite(sample.elapsedMs) && sample.elapsedMs > 0 &&
+            Number.isFinite(sample.ageMs) && sample.ageMs >= 0 &&
+            (sample.parseElapsedMs === undefined || sample.parseElapsedMs === null ||
+              Number.isFinite(sample.parseElapsedMs) && sample.parseElapsedMs >= 0) &&
+            (sample.bufferingElapsedMs === undefined || sample.bufferingElapsedMs === null ||
+              Number.isFinite(sample.bufferingElapsedMs) && sample.bufferingElapsedMs >= 0) &&
+            (sample.bufferingAgeMs === undefined || sample.bufferingAgeMs === null ||
+              Number.isFinite(sample.bufferingAgeMs) && sample.bufferingAgeMs >= 0) &&
+            (sample.eventAgesMs === undefined || sample.eventAgesMs && typeof sample.eventAgesMs === "object" &&
+              !Array.isArray(sample.eventAgesMs) && Object.values(sample.eventAgesMs).every(age =>
+                age === null || Number.isFinite(age) && age >= 0)) &&
+            (sample.fragmentId === null || typeof sample.fragmentId === "string" && sample.fragmentId.length <= 128) &&
+            (sample.fragmentSequence === undefined || sample.fragmentSequence === null ||
+              Number.isSafeInteger(sample.fragmentSequence) && sample.fragmentSequence >= 0) &&
+            (sample.partIndex === undefined || sample.partIndex === null ||
+              Number.isSafeInteger(sample.partIndex) && sample.partIndex >= 0) &&
+            (sample.fragmentStartSeconds === null || Number.isFinite(sample.fragmentStartSeconds)))) {
+        return null;
+      }
+      snapshot[track][kind] = { bytes: item.bytes, elapsedMs: item.elapsedMs, operations: item.operations,
+        samples: item.samples.map(({ bytes, elapsedMs, ageMs, fragmentId, fragmentSequence, partIndex, fragmentStartSeconds,
+          parseElapsedMs, bufferingElapsedMs, bufferingAgeMs, eventAgesMs }) =>
+          ({ bytes, elapsedMs, ageMs, fragmentId, fragmentSequence: fragmentSequence ?? null,
+            partIndex: partIndex ?? null, fragmentStartSeconds,
+            parseElapsedMs: parseElapsedMs ?? null, bufferingElapsedMs: bufferingElapsedMs ?? null,
+            bufferingAgeMs: bufferingAgeMs ?? null, eventAgesMs: fragmentEventAges(eventAgesMs) })) };
+    }
+  }
+  return snapshot;
+}
+
+function appendServiceIsMonotonic(next, previous) {
+  return APPEND_TRACKS.every(track => APPEND_KINDS.every(kind =>
+    next[track][kind].bytes >= previous[track][kind].bytes &&
+    next[track][kind].elapsedMs >= previous[track][kind].elapsedMs &&
+    next[track][kind].operations >= previous[track][kind].operations));
+}
+
+function fragmentServiceIsMonotonic(next, previous) {
+  return APPEND_TRACKS.every(track => APPEND_KINDS.every(kind =>
+    next[track][kind].bytes >= previous[track][kind].bytes &&
+    next[track][kind].elapsedMs >= previous[track][kind].elapsedMs &&
+    next[track][kind].operations >= previous[track][kind].operations));
+}
+
 /**
  * How long a generation this viewer has left behind goes on accepting NEW
  * requests.
@@ -373,6 +471,11 @@ export class Viewer {
    *   report still stands: this is a statement about a viewer, not about a link.
    * @param {number} [report.linkSampleAgeMs] - How old the newest raw link
    *   sample was when this report was made.
+   * @param {string} [report.appendSessionId] - Which output the page measured appends for.
+   * @param {string} [report.appendEpoch] - Counter identity; a new page reporter starts a new epoch.
+   * @param {number} [report.appendEpochStartedAt] - Browser epoch start clock used to reject delayed reports from an older reporter.
+   * @param {object} [report.appendService] - Cumulative append totals and recent per-operation byte/time samples.
+   * @param {object} [report.fragmentService] - Cumulative fragment parse totals and recent per-fragment samples.
    * @param {number} report.bufferedAheadSec
    * @param {number} [report.bufferLimitSeconds] - The largest forward buffer
    *   this browser accepted for the current player.
@@ -399,6 +502,12 @@ export class Viewer {
       linkSampleMbps = null,
       linkSampleAt = null,
       linkSampleAgeMs = null,
+      appendSessionId = null,
+      appendEpoch = null,
+      appendEpochStartedAt = null,
+      appendSnapshotAt = null,
+      appendService: appendServiceReading = null,
+      fragmentService: fragmentServiceReading = null,
       bufferedAheadSec,
       bufferedRanges,
       timestampOffsets,
@@ -439,6 +548,20 @@ export class Viewer {
     const sampleMbps = Number(linkSampleMbps);
     const sampleAt = Number(linkSampleAt);
     const previous = this.netReport;
+    const incomingAppendService = typeof appendEpoch === "string" && appendEpoch.length > 0
+      ? appendServiceSnapshot(appendServiceReading) : null;
+    const incomingFragmentService = typeof appendEpoch === "string" && appendEpoch.length > 0
+      ? fragmentServiceSnapshot(fragmentServiceReading) : null;
+    const sameAppendEpoch = appendSessionId === previous?.appendSessionId && appendEpoch === previous?.appendEpoch;
+    const validAppendEpochTime = Number.isFinite(appendEpochStartedAt) && appendEpochStartedAt > 0;
+    const validAppendSnapshotTime = Number.isFinite(appendSnapshotAt) && appendSnapshotAt >= appendEpochStartedAt;
+    const useBrowserService = !stale && typeof appendSessionId === "string" && appendSessionId.length > 0 &&
+      incomingAppendService && incomingFragmentService &&
+      validAppendEpochTime && validAppendSnapshotTime && (sameAppendEpoch
+        ? appendEpochStartedAt === previous?.appendEpochStartedAt && appendSnapshotAt > (previous?.appendSnapshotAt ?? 0) &&
+          (!previous?.appendService || appendServiceIsMonotonic(incomingAppendService, previous.appendService)) &&
+          (!previous?.fragmentService || fragmentServiceIsMonotonic(incomingFragmentService, previous.fragmentService))
+        : appendEpochStartedAt > (previous?.appendEpochStartedAt ?? 0));
     const hasPlaybackSample = Number.isFinite(sampleMbps) && sampleMbps > 0 &&
       Number.isFinite(sampleAt) && sampleAt > 0;
     const newerPlaybackSample = hasPlaybackSample && sampleAt > (this.netReport?.linkSampleAt ?? 0);
@@ -452,6 +575,13 @@ export class Viewer {
           ? now - linkSampleAgeMs
           : now
         : this.netReport?.linkSampleMeasuredAt ?? null,
+      appendSessionId: useBrowserService ? appendSessionId : previous?.appendSessionId ?? null,
+      appendEpoch: useBrowserService ? appendEpoch : 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,
       timestampOffsets: Object.fromEntries(["video", "audio"].filter((key) =>
         Number.isFinite(timestampOffsets?.[key])).map((key) => [key, timestampOffsets[key]])),

package/services/viewer/playback-readiness.js

@@ -42,6 +42,46 @@ import {
 // timestamps can extend slightly beyond its nominal playlist boundary.
 export const PLAYER_SEEK_TOLERANCE_SECONDS = 0.25;
 
+/**
+ * Choose a point for a supported completion-time distribution under absolute
+ * relative error. For positive completions, minimizing E[|x - T| / T] is a
+ * weighted-median problem with mass p/T. A distribution mixing immediate and
+ * positive completion has no point under this loss definition.
+ *
+ * This summarizes an already-supported probability distribution; it does not
+ * fit one from completed whole waits or supply missing service observations.
+ *
+ * @param {Array<{ completionSeconds: number, probability: number }>} support
+ * @returns {{ pointSeconds: number | null, immediateProbability: number, supportCount: number } | null}
+ */
+export function completionPointUnderRelativeLoss(support) {
+  if (!Array.isArray(support) || support.length === 0 || support.some(sample =>
+    !Number.isFinite(sample?.completionSeconds) || sample.completionSeconds < 0 ||
+    !Number.isFinite(sample?.probability) || sample.probability < 0)) return null;
+  const positiveMass = support.filter(sample => sample.probability > 0);
+  const totalProbability = positiveMass.reduce((sum, sample) => sum + sample.probability, 0);
+  if (!(totalProbability > 0) || !Number.isFinite(totalProbability)) return null;
+  const immediateProbability = positiveMass.filter(sample => sample.completionSeconds === 0)
+    .reduce((sum, sample) => sum + sample.probability, 0) / totalProbability;
+  const positive = positiveMass.filter(sample => sample.completionSeconds > 0);
+  if (positive.length === 0) return { pointSeconds: 0, immediateProbability: 1, supportCount: positiveMass.length };
+  if (immediateProbability > 0) {
+    return { pointSeconds: null, immediateProbability, supportCount: positiveMass.length };
+  }
+  const weighted = positive.map(sample => ({ seconds: sample.completionSeconds,
+    weight: sample.probability / sample.completionSeconds })).sort((left, right) => left.seconds - right.seconds);
+  const totalWeight = weighted.reduce((sum, sample) => sum + sample.weight, 0);
+  if (!(totalWeight > 0) || !Number.isFinite(totalWeight)) return null;
+  let cumulativeWeight = 0;
+  for (const sample of weighted) {
+    cumulativeWeight += sample.weight;
+    if (cumulativeWeight * 2 >= totalWeight) {
+      return { pointSeconds: sample.seconds, immediateProbability: 0, supportCount: positiveMass.length };
+    }
+  }
+  return null;
+}
+
 /**
  * @param {number} segmentEndSeconds
  * @param {number} positionSeconds
@@ -191,6 +231,7 @@ export class RateTrend {
  *   segmentCount?: number,
  *   bitsPerMediaSecond: number, readings: Array<{ at: number, value: number }>,
  *   clockOffsetSeconds?: number, clientRanges?: Array<{ start: number, end: number }>,
+ *   appendService?: object, fragmentService?: object,
  *   segments: Array<{ index: number, startSeconds: number, endSeconds: number,
  *     mediaRanges?: { timescale: bigint | null, ranges: Array<{ start: bigint, end: bigint, frame: bigint }> } }>,
  *   readySegmentIndices: number[], segmentSizesBytes: Map<number, number> | object }>} input.tracks
@@ -300,6 +341,13 @@ export function predictPlaybackReadiness(input = {}) {
       : Math.max(0, ...track.segments.map(segment => segment.index + 1)),
     clockSeconds: Number.isFinite(track.clockOffsetSeconds) ? track.clockOffsetSeconds : 0
   }));
+  const missingFirstGeometry = trackState.slice(0, requiredTracks).some(({ segments }) => {
+    const first = segments.find(segment => segment.endSeconds > position);
+    return first && first.ranges.length === 0;
+  });
+  if (missingFirstGeometry) {
+    return result(false, null, buffered, reserve, null, "first-required-media-ranges-unavailable", 0);
+  }
   for (const state of trackState) {
     state.tailEndSeconds = Number.isFinite(horizonEnd) && horizonEnd < duration
       ? Math.min(duration, state.durationSeconds + state.clockSeconds) : null;
@@ -707,16 +755,68 @@ export function predictPlaybackReadiness(input = {}) {
     const first = state.segments.find(segment => segment.endSeconds > position);
     if (!first) return { track: state.track.id ?? trackIndex, segment: null, alreadyBuffered: true,
       sourceArrivalSeconds: 0, runAdmissionSeconds: null, runOpenSeconds: 0, productionStartSeconds: 0,
-      productionCompleteSeconds: 0, deliveryCompleteSeconds: 0, appendSeconds: 0, completionSeconds: 0 };
+      productionCompleteSeconds: 0, deliveryCompleteSeconds: 0, browserLoadToParseSeconds: 0,
+      appendRequestToAckSeconds: 0, appendSeconds: 0, completionSeconds: 0 };
+    if (!Array.isArray(first.ranges) || first.ranges.length === 0) return {
+      track: state.track.id ?? trackIndex,
+      segment: first.index,
+      alreadyBuffered: null,
+      mediaRangesReason: "first-required-media-ranges-unavailable",
+      sourceArrivalSeconds: null,
+      runAdmissionSeconds: null,
+      runOpenSeconds: null,
+      productionStartSeconds: null,
+      productionCompleteSeconds: null,
+      deliveryCompleteSeconds: null,
+      browserLoadToParseSeconds: null,
+      browserLoadToParseReason: "fragment-load-to-parse-distribution-unavailable",
+      appendRequestToAckSeconds: null,
+      appendRequestToAckReason: "append-request-to-ack-distribution-unavailable",
+      appendSeconds: null,
+      appendReason: "append-request-to-ack-distribution-unavailable",
+      completionSeconds: null
+    };
     if (first.ranges.every(range => contains(state.clientRanges, range.start, range.end))) {
       return { track: state.track.id ?? trackIndex, segment: first.index, alreadyBuffered: true,
         sourceArrivalSeconds: 0, runAdmissionSeconds: null, runOpenSeconds: 0, productionStartSeconds: 0,
-        productionCompleteSeconds: 0, deliveryCompleteSeconds: 0, appendSeconds: 0, completionSeconds: 0 };
+        productionCompleteSeconds: 0, deliveryCompleteSeconds: 0, browserLoadToParseSeconds: 0,
+        appendRequestToAckSeconds: 0, appendSeconds: 0, completionSeconds: 0 };
     }
     const completion = completions.find(item => item.trackIndex === trackIndex && item.segment.index === first.index);
+    // HLS playlists for these generated outputs use MEDIA-SEQUENCE:0, so a
+    // complete media fragment's HLS sequence number is the output segment
+    // index. Keep matched browser observations as evidence only: their recent
+    // completed-work spans are not a future-service distribution.
+    const samplesForFirstSegment = (kind) => (service) => {
+      const samples = service?.[kind]?.samples;
+      return Array.isArray(samples) ? samples.filter(sample => sample.fragmentSequence === first.index &&
+        sample.partIndex === null) : [];
+    };
+    const observedBrowserWork = {
+      evidenceOnly: true,
+      fragmentLoadToParse: samplesForFirstSegment("media")(state.track.fragmentService).map(sample => ({
+        bytes: sample.bytes,
+        elapsedMs: sample.elapsedMs,
+        parseElapsedMs: sample.parseElapsedMs ?? null,
+        bufferingElapsedMs: sample.bufferingElapsedMs ?? null,
+        ageMs: sample.ageMs,
+        bufferingAgeMs: sample.bufferingAgeMs ?? null,
+        eventAgesMs: sample.eventAgesMs ?? null
+      })),
+      appendRequestToAck: samplesForFirstSegment("media")(state.track.appendService).map(sample => ({
+        bytes: sample.bytes,
+        elapsedMs: sample.elapsedMs,
+        ageMs: sample.ageMs
+      }))
+    };
+    const observedBrowserWorkField = observedBrowserWork.fragmentLoadToParse.length > 0 ||
+      observedBrowserWork.appendRequestToAck.length > 0 ? { observedBrowserWork } : {};
     if (!completion) return { track: state.track.id ?? trackIndex, segment: first.index, alreadyBuffered: false,
       sourceArrivalSeconds: null, runAdmissionSeconds: null, runOpenSeconds: null, productionStartSeconds: null,
-      productionCompleteSeconds: null, deliveryCompleteSeconds: null, appendSeconds: null, completionSeconds: null };
+      productionCompleteSeconds: null, deliveryCompleteSeconds: null, browserLoadToParseSeconds: null,
+      browserLoadToParseReason: "fragment-load-to-parse-distribution-unavailable",
+      appendRequestToAckSeconds: null, appendRequestToAckReason: "append-request-to-ack-distribution-unavailable",
+      appendSeconds: null, completionSeconds: null, ...observedBrowserWorkField };
     const production = productions.find(item => item.trackIndex === trackIndex && item.segment.index === first.index);
     return { track: state.track.id ?? trackIndex, segment: first.index, alreadyBuffered: false,
       sourceArrivalSeconds: production?.sourceArrivalAt ?? 0,
@@ -725,8 +825,14 @@ export function predictPlaybackReadiness(input = {}) {
       productionStartSeconds: production?.productionStartAt ?? null,
       productionCompleteSeconds: production?.at ?? null,
       deliveryCompleteSeconds: completion.deliveryAt,
-      appendSeconds: completion.appendSeconds,
-      completionSeconds: completion.at };
+      browserLoadToParseSeconds: null,
+      browserLoadToParseReason: "fragment-load-to-parse-distribution-unavailable",
+      appendRequestToAckSeconds: null,
+      appendRequestToAckReason: "append-request-to-ack-distribution-unavailable",
+      appendSeconds: null,
+      appendReason: "append-request-to-ack-distribution-unavailable",
+      completionSeconds: null,
+      ...observedBrowserWorkField };
   });
   const firstRequiredTrackSeconds = firstRequiredStages.map(stage => stage.completionSeconds);
   const firstRequiredSegmentsSeconds = firstRequiredTrackSeconds.every(Number.isFinite)
@@ -735,16 +841,19 @@ export function predictPlaybackReadiness(input = {}) {
   // THE STOCK THE START ASKS FOR HAS TO FIT. Starting without a stop while the
   // source comes slower than the film plays means holding, at the start, what
   // is already here and everything that arrives before it. Where that is more
-  // than this proxy may keep of downloaded pieces, the oldest of it would be
-  // given up before the viewer reached it, and no wait makes the start safe:
+  // than the disk room left after other active playback stock is reserved,
+  // some of it would be given up before the viewer reached it, so no wait
+  // makes the start safe:
   // Despicable Me 3 BDRemux at 1.4 MB/s asked for about 36 GB against a 29.5 GB
   // share (Home Assistant 2026-10-26, torrent-tv/meta#239). Said as such, and
   // the viewer keeps waiting rather than starting into stops.
   const storageBytes = Number(input.sourceStorageBytes);
   const tailParts = tailStock.filter(part => !part.skipped);
+  const cushionBytes = Number.isFinite(delay) && tailParts.length > 0
+    ? tailParts.reduce((sum, part) => sum + Math.max(0, part.totalBytes - part.missingBytes) +
+      Math.max(0, part.missingBytes - part.bytesPerSecond * Math.max(0, part.finish - delay)), 0)
+    : null;
   if (Number.isFinite(delay) && Number.isFinite(storageBytes) && storageBytes >= 0 && tailParts.length > 0) {
-    const cushionBytes = tailParts.reduce((sum, part) => sum + Math.max(0, part.totalBytes - part.missingBytes) +
-      Math.max(0, part.missingBytes - part.bytesPerSecond * Math.max(0, part.finish - delay)), 0);
     if (cushionBytes > storageBytes) {
       return { ...result(false, null, buffered, reserve, null, "cushion-exceeds-storage", preparedSegments),
         cushionBytes, storageBytes, tail: tailStock };
@@ -756,6 +865,7 @@ export function predictPlaybackReadiness(input = {}) {
     Math.max(0, reserve - buffered), ready ? 'trajectory-safe-now' :
       Number.isFinite(delay) ? 'minimum-safe-delay' : 'service-not-advancing', preparedSegments);
   return { ...forecast, measuredAt: now, predictedStartAt: Number.isFinite(delay) ? now + delay * 1000 : null,
+    ...(cushionBytes === null ? {} : { cushionBytes }),
     firstRequiredSegmentsSeconds,
     firstRequiredStages,
     // What the rest of the film weighs per source, at what rate it comes and