@torrent-tv/proxy 2.87.13 → 2.87.15

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.87.15
+
+- **Fix**: Integrate a bounded, nonnegative forecast of recent measured service rates, so an old faster link sample cannot predict permanent delivery failure and prevent playback of fully prepared media.
+- **Fix**: Treat the already-held browser buffer as a measured lower bound on capacity when its loader target has been reduced by fragment retries.
+- **Chore**: Record forecast measurements when the playback-readiness reason changes.
+
+## 2.87.14
+
+- **Fix**: Evaluate source-stall coverage against the continuous timeline already prepared on the proxy, while independently checking client-buffer continuity and delivery capacity.
+
 ## 2.87.13
 
 - **Fix**: Include distinct active piece reads in memory demand and preserve their slots immediately, so reads without priority-map ranges cannot deadlock the torrent piece store.

package/docs/browser-proxy-contract.md

@@ -101,6 +101,15 @@ remaining-work estimates and share the measured download rate of their torrent.
 The browser reports buffer state and delivery measurements, but does not
 calculate or override readiness.
 
+Service work is the integral of a nonnegative measured-rate forecast. The latest
+rate relaxes over the observed measurement span toward the lower of its latest
+value and the recent mean; the measurement history covers the output look-ahead.
+A positive measured rate cannot become permanently zero from an old declining
+linear fit. A measured zero remains zero until a new measurement arrives.
+The reported loader limit is bounded below by the browser buffer already held.
+During startup waiting the browser refreshes stale delivery measurements through
+the existing link probe and reports their age to avoid clock-offset errors.
+
 ## Subtitles
 
 `GET /api/subtitles` requires `sourceKey` and `fileIndex`. Without `trackIndex`

package/package.json

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

package/services/server/ViewerRequests.js

@@ -663,7 +663,7 @@ export class ViewerRequests {
       return Number.isFinite(segmentSeconds) && segmentSeconds > 0 ? segmentSeconds : 0;
     }));
 
-    return predictPlaybackReadiness({
+    const input = {
       now,
       positionSeconds,
       durationSeconds: session.file.durationSeconds,
@@ -675,7 +675,24 @@ export class ViewerRequests {
       sources: [...sourceMeasurements.values()],
       tracks,
       linkReadings: measurement.link.snapshot()
-    });
+    };
+    const forecast = predictPlaybackReadiness(input);
+    if (measurement.forecastReason !== forecast.reason) {
+      measurement.forecastReason = forecast.reason;
+      logger.info(`playback readiness ${session.id} consumer=${consumerId} ${JSON.stringify({
+        ...forecast,
+        positionSeconds,
+        durationSeconds: input.durationSeconds,
+        bufferLimitSeconds: input.bufferLimitSeconds,
+        lookaheadSeconds: input.lookaheadSeconds,
+        link: input.linkReadings,
+        sources: input.sources,
+        tracks: tracks.map(({ id, processedSeconds, readings, segments, readySegmentIndices }) => ({
+          id, processedSeconds, readings, segments: segments.length, prepared: readySegmentIndices.length
+        }))
+      })}`);
+    }
+    return forecast;
   }
 
   #rateStateFor(session, consumerId) {
@@ -687,7 +704,7 @@ export class ViewerRequests {
     const id = typeof consumerId === "string" ? consumerId : "";
     let state = byViewer.get(id);
     if (!state) {
-      state = { link: new RateTrend(), downloads: new Map(), tracks: new Map() };
+      state = { link: new RateTrend(this.#host.lookaheadSeconds), downloads: new Map(), tracks: new Map() };
       byViewer.set(id, state);
     }
     return state;
@@ -696,7 +713,7 @@ export class ViewerRequests {
   #downloadRateReadings(state, serviceId, downloadSpeed, now) {
     let trend = state.downloads.get(serviceId);
     if (!trend) {
-      trend = new RateTrend();
+      trend = new RateTrend(this.#host.lookaheadSeconds);
       state.downloads.set(serviceId, trend);
     }
     const speed = Number(downloadSpeed);
@@ -710,7 +727,7 @@ export class ViewerRequests {
     const id = output.outputKey;
     let trend = state.tracks.get(id);
     if (!trend) {
-      trend = new RateTrend();
+      trend = new RateTrend(this.#host.lookaheadSeconds);
       state.tracks.set(id, trend);
     }
     const reading = this.#host.encodeSpeedReadingOf?.(output, now) ?? null;

package/services/server/playback-readiness.js

@@ -6,14 +6,15 @@
  * measurements and physical limits: source bytes and download rate, encoded
  * media and encoder rate, segment sizes and client-link rate, the existing
  * browser buffer, its capacity, the proxy look-ahead, and the measured reserve
- * for interruptions. Rates are extrapolated from their measured linear trend;
- * there are no fitted weights or rate multipliers.
+ * for interruptions. A measured rate relaxes toward the lower of its latest
+ * value and its observed mean over the measurement span. Its integral remains
+ * unbounded for a positive measured rate; an old slope cannot invent a permanent
+ * cessation of service. There are no fitted weights or rate multipliers.
  */
 
 /**
- * The mean rate predicted over a horizon by the trend in all supplied
- * measurements. With no trend this is the measured rate. The regression treats
- * every measurement equally.
+ * The mean rate predicted over a horizon by the integral of the measured rate.
+ * Every supplied measurement contributes equally to the observed mean.
  *
  * @param {Array<{ at: number, value: number }>} readings
  * @param {number} now
@@ -30,48 +31,36 @@ export function forecastRate(readings, now = Date.now(), horizonSeconds = 0) {
 }
 
 /**
- * Constant-space measurements for one rate trend. Linear regression can be
- * evaluated from these sums without retaining every poll for the life of a
- * film.
+ * Measurements over the output's existing look-ahead horizon. The oldest
+ * boundary sample is retained until another sample replaces it, so a repeated
+ * report never changes the history or invents a new measurement.
  */
 export class RateTrend {
-  #originAt = null;
-  #lastAt = null;
-  #count = 0;
-  #sumTime = 0;
-  #sumTimeSquared = 0;
-  #sumValue = 0;
-  #sumTimeValue = 0;
+  #readings = [];
+  #horizonMs;
+
+  constructor(horizonSeconds = Number.POSITIVE_INFINITY) {
+    this.#horizonMs = Math.max(0, horizonSeconds) * 1000;
+  }
 
   add(at, value) {
     if (!Number.isFinite(at) || !Number.isFinite(value) || value < 0 ||
-      (this.#lastAt !== null && at <= this.#lastAt)) {
+      at <= (this.#readings.at(-1)?.at ?? Number.NEGATIVE_INFINITY)) {
       return false;
     }
-    this.#originAt ??= at;
-    const elapsed = (at - this.#originAt) / 1000;
-    this.#count += 1;
-    this.#sumTime += elapsed;
-    this.#sumTimeSquared += elapsed ** 2;
-    this.#sumValue += value;
-    this.#sumTimeValue += elapsed * value;
-    this.#lastAt = at;
+    this.#readings.push({ at, value });
+    const cutoff = at - this.#horizonMs;
+    while (this.#readings.length > 1 && this.#readings[1].at <= cutoff) {
+      this.#readings.shift();
+    }
     return true;
   }
 
   snapshot() {
-    if (this.#count === 0) {
+    if (this.#readings.length === 0) {
       return null;
     }
-    return {
-      count: this.#count,
-      originAt: this.#originAt,
-      lastAt: this.#lastAt,
-      sumTime: this.#sumTime,
-      sumTimeSquared: this.#sumTimeSquared,
-      sumValue: this.#sumValue,
-      sumTimeValue: this.#sumTimeValue
-    };
+    return summarizeRate(this.#readings);
   }
 }
 
@@ -81,7 +70,7 @@ export class RateTrend {
  * @param {number} input.durationSeconds
  * @param {number} input.bufferedAheadSeconds
  * @param {number} input.bufferLimitSeconds
- * @param {number} input.reserveSeconds
+ * @param {number} input.reserveSeconds - Measured source-stall coverage, in media seconds.
  * @param {number} input.lookaheadSeconds
  * @param {number} input.now
  * @param {boolean} [input.requiredAudio]
@@ -100,7 +89,9 @@ export function predictPlaybackReadiness(input = {}) {
   const duration = finiteNonNegative(input.durationSeconds);
   const remaining = Math.max(0, duration - position);
   const buffered = finiteNonNegative(input.bufferedAheadSeconds);
-  const capacity = finiteNonNegative(input.bufferLimitSeconds);
+  // A loader target can be lowered after a fragment retry. Bytes already held
+  // prove a larger capacity, even when an older page reports only that target.
+  const capacity = Math.max(buffered, finiteNonNegative(input.bufferLimitSeconds));
   const reserve = Math.min(remaining, finiteNonNegative(input.reserveSeconds));
   const lookahead = finiteNonNegative(input.lookaheadSeconds);
   const tracks = Array.isArray(input.tracks) ? input.tracks : [];
@@ -110,12 +101,9 @@ export function predictPlaybackReadiness(input = {}) {
   if (remaining <= buffered) {
     return result(true, 0, buffered, reserve, 0, "client-buffer-covers-end", 0);
   }
-  if (!(duration > 0) || !(capacity > 0) || !(reserve > 0) || tracks.length === 0) {
+  if (!(duration > 0) || !(capacity > 0) || tracks.length === 0) {
     return result(false, null, buffered, reserve, null, "incomplete-state", 0);
   }
-  if (reserve > capacity) {
-    return result(false, null, buffered, reserve, null, "reserve-exceeds-client-capacity", 0);
-  }
   const requiredTracks = input.requiredAudio === true ? 2 : 1;
   if (tracks.length < requiredTracks) {
     return result(false, null, buffered, reserve, null, "separate-audio-not-observed", 0);
@@ -166,7 +154,7 @@ export function predictPlaybackReadiness(input = {}) {
 
   for (let trackIndex = 0; trackIndex < trackState.length; trackIndex += 1) {
     const state = trackState[trackIndex];
-    const { track, ready, segments } = state;
+    const { track, segments } = state;
     const measuredBitsPerMediaSecond = state.bitsPerMediaSecond;
     for (const segment of segments) {
       if (segment.endSeconds <= position + buffered) {
@@ -240,32 +228,6 @@ export function predictPlaybackReadiness(input = {}) {
     }
   }
 
-  const rateRecoveryDelays = [];
-  const sourceDemandByService = new Map();
-  for (const sourceId of new Set(jobs.flatMap(({ sourceIntervals }) => [...sourceIntervals.keys()]))) {
-    const source = sourceState.get(sourceId);
-    const demand = sourceDemandByService.get(source.serviceId) ?? new Map();
-    demand.set(sourceId, Number(source.source.bytesPerMediaSecond));
-    sourceDemandByService.set(source.serviceId, demand);
-  }
-  for (const [serviceId, demandBySource] of sourceDemandByService) {
-    const demand = [...demandBySource.values()].reduce((sum, value) => sum + value, 0);
-    rateRecoveryDelays.push(downloadServices.get(serviceId).curve.timeAtLeast(demand));
-  }
-  for (const { track, curve } of trackState) {
-    if (jobs.some((job) => job.track === track && !job.produced)) {
-      rateRecoveryDelays.push(curve.timeAtLeast(1));
-    }
-  }
-  const linkDemand = trackState.reduce((sum, { track, bitsPerMediaSecond }) =>
-    sum + (jobs.some((job) => job.track === track) ? bitsPerMediaSecond : 0), 0);
-  if (linkDemand > 0) {
-    rateRecoveryDelays.push(link.timeAtLeast(linkDemand));
-  }
-  const rateRecoveryDelay = rateRecoveryDelays
-    .filter(Number.isFinite)
-    .reduce((latest, delay) => Math.max(latest, delay), 0);
-
   jobs.sort((left, right) => left.segment.startSeconds - right.segment.startSeconds ||
     left.segment.endSeconds - right.segment.endSeconds || left.trackIndex - right.trackIndex);
 
@@ -277,6 +239,7 @@ export function predictPlaybackReadiness(input = {}) {
     const trackFinish = trackState.map(() => 0);
     let transferFinish = 0;
     const completions = [];
+    const productions = [];
     for (const job of jobs) {
       const { track, trackIndex, segment, ahead, sizeBits, encodeWork, sourceIntervals } = job;
       if (prefillOnly && (ahead > prefillReach || segment.endSeconds - position > capacity)) {
@@ -322,7 +285,14 @@ export function predictPlaybackReadiness(input = {}) {
       if (!job.produced) {
         trackFinish[trackIndex] = encodedAt;
       }
-      const producedAt = Math.max(sourceReadyAtLatest, encodedAt);
+      const producedAt = job.produced ? 0 : Math.max(sourceReadyAtLatest, encodedAt);
+      productions.push({
+        at: producedAt,
+        sourceReadyAt: sourceReadyAtLatest,
+        trackIndex,
+        segment,
+        requiresSource: sourceIntervals.size > 0
+      });
       const roomAt = segment.endSeconds - position <= capacity
         ? 0
         : startDelaySeconds + segment.endSeconds - position - capacity;
@@ -339,12 +309,17 @@ export function predictPlaybackReadiness(input = {}) {
       ? completions.filter(({ segment }) => segment.startSeconds - position <= prefillReach &&
         segment.endSeconds - position <= capacity)
       : completions;
-    const safety = isSafeSchedule(usefulCompletions, trackState, position, duration,
+    const usefulProductions = prefillOnly
+      ? productions.filter(({ segment }) => segment.startSeconds - position <= prefillReach &&
+        segment.endSeconds - position <= capacity)
+      : productions;
+    const safety = isSafeSchedule(usefulCompletions, usefulProductions, trackState, position, duration,
       buffered, capacity, reserve, startDelaySeconds);
     return { safe: safety.safe,
       bufferedAtStart: safety.bufferedAtStart,
-      finishAt: usefulCompletions.reduce((latest, item) => Math.max(latest, item.at), 0),
-      completions: usefulCompletions };
+      neededSeconds: safety.neededSeconds,
+      completionTimes: usefulCompletions.map(({ at }) => at),
+      finishAt: usefulCompletions.reduce((latest, item) => Math.max(latest, item.at), 0) };
   };
 
   const prefillReach = Math.min(capacity, lookahead, remaining);
@@ -353,10 +328,11 @@ export function predictPlaybackReadiness(input = {}) {
   if (!Number.isFinite(maximumUsefulDelay)) {
     return result(false, null, buffered, reserve, null, "prefill-cannot-complete", preparedSegments);
   }
-  if (schedule(0).safe) {
+  const immediate = schedule(0);
+  if (immediate.safe) {
     return result(true, 0, buffered, reserve, 0, "trajectory-safe-now", preparedSegments);
   }
-  const searchLimit = Math.max(maximumUsefulDelay, rateRecoveryDelay);
+  const searchLimit = maximumUsefulDelay;
   if (!(searchLimit > 0)) {
     return result(false, null, buffered, reserve, null, "no-safe-start-found", preparedSegments);
   }
@@ -366,7 +342,7 @@ export function predictPlaybackReadiness(input = {}) {
   const breakpoints = [...new Set([
     maximumUsefulDelay,
     searchLimit,
-    ...rateRecoveryDelays.filter(Number.isFinite)
+    ...prefillSchedule.completionTimes
   ])]
     .filter((delay) => delay > 0 && delay <= searchLimit)
     .sort((left, right) => left - right);
@@ -396,23 +372,15 @@ export function predictPlaybackReadiness(input = {}) {
     }
   }
   const readiness = schedule(high);
-  return result(false, high, buffered, reserve, Math.max(0, reserve - buffered),
+  return result(false, high, buffered, reserve, immediate.neededSeconds,
     "minimum-safe-delay", preparedSegments, readiness.bufferedAtStart);
 }
 
 function rateCurve(readings, now) {
   if (readings && Number.isFinite(readings.count) && readings.count > 0 &&
-    Number.isFinite(readings.originAt) && Number.isFinite(readings.lastAt) &&
-    Number.isFinite(readings.sumTime) && Number.isFinite(readings.sumTimeSquared) &&
-    Number.isFinite(readings.sumValue) && Number.isFinite(readings.sumTimeValue)) {
-    const { count, originAt, sumTime, sumTimeSquared, sumValue, sumTimeValue } = readings;
-    const meanAt = sumTime / count;
-    const meanValue = sumValue / count;
-    const denominator = sumTimeSquared - count * meanAt ** 2;
-    const numerator = sumTimeValue - count * meanAt * meanValue;
-    const slope = denominator > 0 ? numerator / denominator : 0;
-    const current = Math.max(0, meanValue + slope * ((now - originAt) / 1000 - meanAt));
-    return rateCurveFrom(current, slope);
+    Number.isFinite(readings.lastAt) && Number.isFinite(readings.lastValue) &&
+    Number.isFinite(readings.meanValue) && Number.isFinite(readings.spanSeconds)) {
+    return rateCurveFrom(readings, now);
   }
   const ordered = (Array.isArray(readings) ? readings : [])
     .filter((reading) => Number.isFinite(reading?.at) && Number.isFinite(reading?.value) && reading.value >= 0)
@@ -423,71 +391,70 @@ function rateCurve(readings, now) {
     return null;
   }
 
-  const points = ordered.map((reading) => ({
-    at: (reading.at - now) / 1000,
-    value: reading.value
-  }));
-  const meanAt = points.reduce((sum, point) => sum + point.at, 0) / points.length;
-  const meanValue = points.reduce((sum, point) => sum + point.value, 0) / points.length;
-  const numerator = points.reduce((sum, point) =>
-    sum + (point.at - meanAt) * (point.value - meanValue), 0);
-  const denominator = points.reduce((sum, point) =>
-    sum + (point.at - meanAt) ** 2, 0);
-  const slope = denominator > 0 ? numerator / denominator : 0;
-  const current = Math.max(0, meanValue - slope * meanAt);
-  return rateCurveFrom(current, slope);
+  return rateCurveFrom(summarizeRate(ordered), now);
 }
 
-function rateCurveFrom(current, slope) {
-  const zeroAt = slope < 0 ? -current / slope : Number.POSITIVE_INFINITY;
-
-  const workBy = (seconds) => {
-    const span = Math.min(Math.max(0, seconds), zeroAt);
-    return Math.max(0, current * span + (slope * span ** 2) / 2);
-  };
-  const timeFor = (work) => {
-    if (!(work > 0)) {
-      return 0;
-    }
-    if (!(current > 0) && !(slope > 0)) {
-      return Number.POSITIVE_INFINITY;
-    }
-    const discriminant = current ** 2 + 2 * slope * work;
-    if (discriminant < 0) {
-      return Number.POSITIVE_INFINITY;
-    }
-    if (slope < 0 && work > workBy(zeroAt)) {
-      return Number.POSITIVE_INFINITY;
-    }
-    if (slope === 0) {
-      return current > 0 ? work / current : Number.POSITIVE_INFINITY;
-    }
-    const root = Math.sqrt(discriminant);
-    const denominator = current + root;
-    return denominator > 0 ? (2 * work) / denominator : Number.POSITIVE_INFINITY;
+function summarizeRate(readings) {
+  const latest = readings.at(-1);
+  return {
+    count: readings.length,
+    lastAt: latest.at,
+    lastValue: latest.value,
+    meanValue: readings.reduce((sum, reading) => sum + reading.value, 0) / readings.length,
+    spanSeconds: (latest.at - readings[0].at) / 1000
   };
+}
+
+function rateCurveFrom({ lastAt, lastValue, meanValue, spanSeconds }, now) {
+  const baseline = Math.max(0, Math.min(lastValue, meanValue));
+  const span = Math.max(Number.EPSILON, spanSeconds);
+  const age = Math.max(0, (now - lastAt) / 1000);
+  const excess = Math.max(0, lastValue - baseline) * Math.exp(-age / span);
+  // r(t) = baseline + excess * exp(-t/span).
+  // W(t) = integral(0..t, r(u)du). Positive measured service has no finite
+  // total-work ceiling merely because an old sample was faster.
+  const workBy = (seconds) => rateIntegral(Math.max(0, seconds), baseline, excess, span);
   return {
-    timeAtLeast: (target) => {
-      if (!Number.isFinite(target) || target < 0) {
-        return Number.POSITIVE_INFINITY;
-      }
-      if (current >= target) {
-        return 0;
-      }
-      return slope > 0 ? (target - current) / slope : Number.POSITIVE_INFINITY;
-    },
-    rateAt: (seconds) => Math.max(0, current + slope * Math.min(Math.max(0, seconds), zeroAt)),
+    rateAt: (seconds) => baseline + excess * Math.exp(-Math.max(0, seconds) / span),
     workBy,
     finish: (work, startAt) => {
-      if (!(work > 0)) {
-        return Math.max(0, startAt);
-      }
       const start = Math.max(0, startAt);
-      return start + (timeFor(work + workBy(start)) - start);
+      return start + invertRateIntegral(Math.max(0, work), baseline,
+        excess * Math.exp(-start / span), span);
     }
   };
 }
 
+function rateIntegral(seconds, baseline, excess, span) {
+  return baseline * seconds - excess * span * Math.expm1(-seconds / span);
+}
+
+/** Invert the strictly increasing service integral, with no playback rule. */
+function invertRateIntegral(work, baseline, excess, span) {
+  if (work === 0) {
+    return 0;
+  }
+  if (!(baseline > 0) || !Number.isFinite(work)) {
+    return Number.POSITIVE_INFINITY;
+  }
+  let low = 0;
+  let high = work / baseline;
+  if (excess === 0) {
+    return high;
+  }
+  while (true) {
+    const middle = (low + high) / 2;
+    if (middle === low || middle === high) {
+      return high;
+    }
+    if (rateIntegral(middle, baseline, excess, span) >= work) {
+      high = middle;
+    } else {
+      low = middle;
+    }
+  }
+}
+
 function averageBitsPerMediaSecond(track, segments, ready) {
   let bits = 0;
   let mediaSeconds = 0;
@@ -508,53 +475,104 @@ function averageBitsPerMediaSecond(track, segments, ready) {
   return finiteNonNegative(track.bitsPerMediaSecond);
 }
 
-function isSafeSchedule(completions, trackState, position, duration, buffered, capacity, reserve, startDelay) {
-  const ranges = trackState.map(() => [{ start: position, end: position + buffered }]);
-  const ordered = [...completions]
+function isSafeSchedule(completions, productions, trackState, position, duration, buffered, capacity, reserve,
+  startDelay) {
+  // Client continuity is constrained by its buffer limit; source-stall reserve
+  // is covered by the larger union of client data and output already prepared here.
+  const clientRanges = trackState.map(() => [{ start: position, end: position + buffered }]);
+  const preparedRanges = trackState.map(() => [{ start: position, end: position + buffered }]);
+  const orderedCompletions = [...completions]
+    .filter(({ at }) => Number.isFinite(at))
+    .sort((left, right) => left.at - right.at || left.trackIndex - right.trackIndex);
+  const orderedProductions = [...productions]
     .filter(({ at }) => Number.isFinite(at))
     .sort((left, right) => left.at - right.at || left.trackIndex - right.trackIndex);
+  const reserveUntil = trackState.map(() => Number.NEGATIVE_INFINITY);
+  // The measured reserve applies only until this track's last required source
+  // interval has arrived; encoding and client delivery stay in the schedule.
+  for (const production of productions) {
+    if (production.requiresSource) {
+      reserveUntil[production.trackIndex] = Math.max(reserveUntil[production.trackIndex],
+        production.sourceReadyAt);
+    }
+  }
   let completionIndex = 0;
+  let productionIndex = 0;
 
   const addThrough = (time) => {
-    while (completionIndex < ordered.length && ordered[completionIndex].at <= time) {
-      const { trackIndex, segment } = ordered[completionIndex];
-      addRange(ranges[trackIndex], segment.startSeconds, segment.endSeconds);
+    while (productionIndex < orderedProductions.length && orderedProductions[productionIndex].at <= time) {
+      const { trackIndex, segment } = orderedProductions[productionIndex];
+      addRange(preparedRanges[trackIndex], segment.startSeconds, segment.endSeconds);
+      productionIndex += 1;
+    }
+    while (completionIndex < orderedCompletions.length && orderedCompletions[completionIndex].at <= time) {
+      const { trackIndex, segment } = orderedCompletions[completionIndex];
+      addRange(clientRanges[trackIndex], segment.startSeconds, segment.endSeconds);
+      addRange(preparedRanges[trackIndex], segment.startSeconds, segment.endSeconds);
       completionIndex += 1;
     }
   };
-  const safeAt = (time) => {
+  const safeAt = (time, checkClient = true) => {
     const playerPosition = position + Math.max(0, time - startDelay);
-    const available = Math.min(capacity, ...ranges.map((trackRanges) =>
+    if (playerPosition >= duration) {
+      return { safe: true, stockSafe: true, available: 0, neededSeconds: 0 };
+    }
+    const available = Math.min(capacity, ...clientRanges.map((trackRanges) =>
       Math.max(0, contiguousEnd(trackRanges, playerPosition) - playerPosition)));
-    const required = Math.min(reserve, Math.max(0, duration - playerPosition));
-    return { safe: available >= required, available };
+    let neededSeconds = 0;
+    let stockSafe = true;
+    for (let trackIndex = 0; trackIndex < trackState.length; trackIndex += 1) {
+      const required = time <= reserveUntil[trackIndex]
+        ? Math.min(reserve, Math.max(0, duration - playerPosition))
+        : 0;
+      const preparedAhead = Math.max(0,
+        contiguousEnd(preparedRanges[trackIndex], playerPosition) - playerPosition);
+      const deficit = Math.max(0, required - preparedAhead);
+      neededSeconds = Math.max(neededSeconds, deficit);
+      stockSafe &&= deficit === 0;
+    }
+    return {
+      safe: (!checkClient || available > 0) && stockSafe,
+      stockSafe,
+      available,
+      neededSeconds
+    };
   };
 
   addThrough(startDelay);
   const atStart = safeAt(startDelay);
   if (!atStart.safe) {
-    return { safe: false, bufferedAtStart: atStart.available };
-  }
-
-  while (completionIndex < ordered.length) {
-    const time = ordered[completionIndex].at;
-    if (time > startDelay) {
-      const beforeArrival = safeAt(time);
-      if (!beforeArrival.safe) {
-        return { safe: false, bufferedAtStart: atStart.available };
-      }
+    return { safe: false, bufferedAtStart: atStart.available, neededSeconds: atStart.neededSeconds };
+  }
+
+  const playbackEnd = startDelay + Math.max(0, duration - position);
+  const playbackBoundaries = [position + buffered,
+    ...trackState.flatMap(({ segments }) => segments.map(({ endSeconds }) => endSeconds))]
+    .filter((boundary) => boundary > position && boundary < duration)
+    .map((boundary) => startDelay + boundary - position);
+  const sourceReadyTimes = productions
+    .filter(({ requiresSource }) => requiresSource)
+    .map(({ sourceReadyAt }) => sourceReadyAt);
+  const eventTimes = [...orderedCompletions.map(({ at }) => at),
+    ...orderedProductions.map(({ at }) => at), ...playbackBoundaries, ...sourceReadyTimes]
+    .filter((time) => Number.isFinite(time) && time > startDelay && time < playbackEnd)
+    .sort((left, right) => left - right)
+    .filter((time, index, all) => index === 0 || time !== all[index - 1]);
+
+  for (const time of eventTimes) {
+    const beforeArrival = safeAt(time, false);
+    if (!beforeArrival.stockSafe) {
+      return { safe: false, bufferedAtStart: atStart.available, neededSeconds: beforeArrival.neededSeconds };
     }
     addThrough(time);
-    if (time > startDelay) {
-      const afterArrival = safeAt(time);
-      if (!afterArrival.safe) {
-        return { safe: false, bufferedAtStart: atStart.available };
-      }
+    const afterArrival = safeAt(time);
+    if (!afterArrival.safe) {
+      return { safe: false, bufferedAtStart: atStart.available, neededSeconds: afterArrival.neededSeconds };
     }
   }
 
-  const atEnd = safeAt(startDelay + Math.max(0, duration - position));
-  return { safe: atEnd.safe, bufferedAtStart: atStart.available };
+  const atEnd = safeAt(playbackEnd);
+  return { safe: atEnd.safe, bufferedAtStart: atStart.available, neededSeconds: atStart.neededSeconds };
 }
 
 function addRange(ranges, start, end) {

package/test/playback-readiness.test.js

@@ -36,7 +36,50 @@ test("finds the first safe start from segments delivered before playback", () =>
 
   assert.equal(forecast.ready, false);
   assert.equal(forecast.reason, "minimum-safe-delay");
-  assert.ok(Math.abs(forecast.delaySeconds - 3) < 1e-8);
+  assert.ok(Math.abs(forecast.delaySeconds - 1) < 1e-8);
+});
+
+test("keeps source-stall reserve in the proxy's prepared timeline, not the capped browser buffer", () => {
+  const now = 10_000;
+  const forecast = predictPlaybackReadiness({
+    now,
+    positionSeconds: 0,
+    durationSeconds: 12,
+    bufferedAheadSeconds: 2,
+    bufferLimitSeconds: 4,
+    reserveSeconds: 6,
+    lookaheadSeconds: 12,
+    sources: [{
+      id: "source",
+      complete: false,
+      bytesPerMediaSecond: 1,
+      readings: [{ at: now - 1_000, value: 2 }, { at: now, value: 2 }]
+    }],
+    tracks: [{
+      id: "video",
+      sourceIds: ["source"],
+      processedSeconds: 8,
+      bitsPerMediaSecond: 80,
+      readings: [{ at: now - 1_000, value: 2 }, { at: now, value: 2 }],
+      segments: [
+        { index: 0, startSeconds: 0, endSeconds: 2 },
+        { index: 1, startSeconds: 2, endSeconds: 4 },
+        { index: 2, startSeconds: 4, endSeconds: 6 },
+        { index: 3, startSeconds: 6, endSeconds: 8 },
+        { index: 4, startSeconds: 8, endSeconds: 10 },
+        { index: 5, startSeconds: 10, endSeconds: 12 }
+      ],
+      readySegmentIndices: [0, 1, 2, 3],
+      segmentSizesBytes: new Map([[0, 20], [1, 20], [2, 20], [3, 20], [4, 20], [5, 20]])
+    }],
+    linkReadings: [{ at: now - 1_000, value: 80_000 }, { at: now, value: 80_000 }]
+  });
+
+  assert.equal(forecast.ready, true);
+  assert.equal(forecast.reason, "trajectory-safe-now");
+  assert.equal(forecast.reserveSeconds, 6);
+  assert.equal(forecast.bufferedSeconds, 2);
+  assert.equal(forecast.preparedSegments, 4);
 });
 
 test("overlaps source reads and encoding, then waits for the slower stage and delivery", () => {
@@ -53,7 +96,7 @@ test("overlaps source reads and encoding, then waits for the slower stage and de
   const forecast = predictPlaybackReadiness(input({ sources: [source], tracks: [track] }));
 
   assert.equal(forecast.ready, false);
-  assert.ok(Math.abs(forecast.delaySeconds - 3) < 1e-8);
+  assert.ok(Math.abs(forecast.delaySeconds - 2) < 1e-8);
 });
 
 test("does not produce an ETA without a client-link measurement", () => {
@@ -64,12 +107,14 @@ test("does not produce an ETA without a client-link measurement", () => {
   assert.equal(forecast.reason, "link-rate-unavailable");
 });
 
-test("rate trend projects the measured linear trend without a fitted weight", () => {
+test("rate forecast does not extrapolate acceleration beyond observed service", () => {
   const trend = new RateTrend();
   trend.add(9_000, 2);
   trend.add(10_000, 4);
 
-  assert.equal(forecastRate(trend.snapshot(), 10_000, 2), 6);
+  const predicted = forecastRate(trend.snapshot(), 10_000, 2);
+  assert.ok(predicted > 3 && predicted < 4);
+  assert.ok(forecastRate(trend.snapshot(), 100_000, 2) >= 3);
 });
 
 test("uses each track's own segment boundaries and requires continuous coverage on both tracks", () => {
@@ -177,7 +222,7 @@ test("downloads an overlapping source interval once when two tracks use the same
 
   assert.equal(forecast.ready, false);
   assert.equal(forecast.reason, "minimum-safe-delay");
-  assert.ok(Math.abs(forecast.delaySeconds - 2.048) < 1e-8);
+  assert.ok(Math.abs(forecast.delaySeconds - 2.032) < 1e-8);
 });
 
 test("downloads sources on separate torrents concurrently", () => {
@@ -288,7 +333,7 @@ test("shares one torrent download rate across distinct video and audio files", (
   assert.ok(Math.abs(forecast.delaySeconds - 4.032) < 1e-8);
 });
 
-test("finds a safe interval when rising encode speed and falling link speed make the forecast non-monotonic", () => {
+test("does not invent future encode acceleration to start an unsustainable output", () => {
   const now = 1_000;
   const forecast = predictPlaybackReadiness({
     now,
@@ -317,7 +362,81 @@ test("finds a safe interval when rising encode speed and falling link speed make
   });
 
   assert.equal(forecast.ready, false);
-  assert.equal(forecast.reason, "minimum-safe-delay");
-  assert.ok(Number.isFinite(forecast.delaySeconds));
-  assert.ok(forecast.delaySeconds > 7 && forecast.delaySeconds < 10);
+  assert.equal(forecast.reason, "no-safe-start-found");
+  assert.equal(forecast.delaySeconds, null);
+});
+
+test("a faster old probe cannot turn positive delivery into a permanent zero rate", () => {
+  const trend = new RateTrend(120);
+  trend.add(0, 112_400_000);
+  trend.add(66_757, 37_640_000);
+  assert.equal(forecastRate(trend.snapshot(), 20 * 60_000, 1443.97), 37_640_000);
+  assert.equal(trend.add(66_757, 37_640_000), false);
+});
+
+test("the measurement window retains one boundary sample and discards older history", () => {
+  const trend = new RateTrend(2);
+  trend.add(0, 100);
+  trend.add(1_000, 40);
+  trend.add(4_000, 20);
+  assert.equal(trend.snapshot().count, 2);
+  assert.equal(trend.snapshot().meanValue, 30);
+});
+
+function preparedEpisode(bufferLimitSeconds, linkReadings) {
+  const durationSeconds = 1443.97;
+  const boundaries = [0, 10.01, 18.977, 29.488];
+  for (let index = 4; index <= 197; index += 1) {
+    boundaries.push(29.488 + (durationSeconds - 29.488) * (index - 3) / 194);
+  }
+  const segments = boundaries.slice(0, -1).map((startSeconds, index) => ({
+    index, startSeconds, endSeconds: boundaries[index + 1]
+  }));
+  const tracks = [9_257_176.8, 189_000].map((bitsPerMediaSecond, index) => ({
+    id: String(index),
+    sourceIds: ["source"],
+    processedSeconds: 1437.269,
+    bitsPerMediaSecond,
+    readings: [],
+    segments,
+    readySegmentIndices: segments.map(({ index }) => index),
+    segmentSizesBytes: new Map(segments.map((segment) => [segment.index,
+      (segment.endSeconds - segment.startSeconds) * bitsPerMediaSecond / 8]))
+  }));
+  return {
+    now: 20 * 60_000,
+    positionSeconds: 0,
+    durationSeconds,
+    bufferedAheadSeconds: 19.187,
+    bufferLimitSeconds,
+    reserveSeconds: 5.674,
+    lookaheadSeconds: 120,
+    requiredAudio: true,
+    sources: [{ id: "source", complete: false, bytesPerMediaSecond: 1, readings: [{ at: 0, value: 0 }] }],
+    tracks,
+    linkReadings
+  };
+}
+
+test("starts a prepared episode despite an old declining link measurement", () => {
+  const forecast = predictPlaybackReadiness(preparedEpisode(120, [
+    { at: 0, value: 112_400_000 }, { at: 66_757, value: 37_640_000 }
+  ]));
+  assert.equal(forecast.preparedSegments, 394);
+  assert.equal(forecast.ready, true);
+  assert.equal(forecast.reason, "trajectory-safe-now");
+});
+
+test("the measured buffer proves capacity even when the loader reports a smaller target", () => {
+  const forecast = predictPlaybackReadiness(preparedEpisode(9.092, [{ at: 0, value: 37_640_000 }]));
+  assert.equal(forecast.ready, true);
+});
+
+test("a measured source stop is not replaced by hypothetical future recovery", () => {
+  const forecast = predictPlaybackReadiness(input({ sources: [{
+    id: "source", complete: false, bytesPerMediaSecond: 1,
+    readings: [{ at: 9_000, value: 10 }, { at: 10_000, value: 0 }]
+  }] }));
+  assert.equal(forecast.ready, false);
+  assert.equal(forecast.delaySeconds, null);
 });