@torrent-tv/proxy 2.10.0 → 2.12.0

package/services/hwaccel.js

@@ -148,15 +148,37 @@ function safeDimensions(targetWidth, targetHeight) {
 
 /**
  * Force a keyframe on every segment boundary so each HLS segment is
- * independently decodable and exactly `segmentDurationSec` long.
+ * independently decodable.
+ *
+ * Two grids exist. The usual one is even — a keyframe every
+ * `segmentDurationSec` — and the encoder is free to place them because it is
+ * producing every frame anyway. The other is the SOURCE's own keyframe times,
+ * used when this encode has to be interchangeable with a stream that is
+ * COPIED: a copy can only be cut where the source already has a keyframe, so a
+ * rung meant to splice into it must be cut at exactly those times and nowhere
+ * else. Then the times are given outright.
  *
  * @param {number} segmentDurationSec
+ * @param {number[] | null} [forcedTimes] - Run-relative seconds, ascending.
  * @returns {string[]}
  */
-function keyFrameArgs(segmentDurationSec) {
+function keyFrameArgs(segmentDurationSec, forcedTimes = null) {
+  if (Array.isArray(forcedTimes) && forcedTimes.length > 0) {
+    return ["-force_key_frames", forcedTimes.join(",")];
+  }
   return ["-force_key_frames", `expr:gte(t,n_forced*${segmentDurationSec})`];
 }
 
+/**
+ * Whether an explicit cut list was supplied.
+ *
+ * @param {number[] | null | undefined} forcedTimes
+ * @returns {boolean}
+ */
+function hasForcedTimes(forcedTimes) {
+  return Array.isArray(forcedTimes) && forcedTimes.length > 0;
+}
+
 /** @returns {import("./hwaccel.js").VideoEncoderDescriptor} */
 export function softwareDescriptor() {
   return {
@@ -164,7 +186,7 @@ export function softwareDescriptor() {
     kind: "software",
     device: null,
     inputArgs: [],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, preset, fps, tonemap }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, preset, fps, tonemap, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       const chosenPreset = typeof preset === "string" && preset.length > 0 ? preset : SOFTWARE_PRESET;
       // Output frame rate: inherited from the source (rounded/capped) by the
@@ -200,11 +222,24 @@ export function softwareDescriptor() {
         // independent of the PTS offset used on seek-restart — every HLS segment
         // is exactly segmentDurationSec long and starts on a keyframe, so segment
         // boundaries line up with the synthetic playlist with no gaps. (The old
-        // `-force_key_frames expr:gte(t,n_forced*SEG)` broke after a seek because
-        // `t` is offset by `-output_ts_offset`, forcing keyframes at the wrong
-        // places.)
+        // the OLD `expr:` form of -force_key_frames broke after a seek, because
+        // the `t` it reads is shifted by `-output_ts_offset`.)
+        //
+        // An explicit cut LIST is a different thing and does work: verified by
+        // running it, its times are on the run's own timeline — the same one
+        // `-segment_times` is measured on — so both are given one list and
+        // cannot drift apart. It replaces the frame-count GOP, which cannot
+        // describe the source's keyframes because they are not evenly spaced.
+        // `-g` stays as an upper bound on the interval: an extra keyframe
+        // inside a segment costs a little bitrate and cuts nothing, while
+        // leaving the interval unbounded means a driver that ignores the list
+        // produces one enormous segment instead of a wrong but cut one.
+        // `-keyint_min` goes, since a MINIMUM interval is the one thing that
+        // could argue with a forced keyframe.
         "-g", String(segmentDurationSec * outFps),
-        "-keyint_min", String(segmentDurationSec * outFps),
+        ...(hasForcedTimes(forcedKeyframeTimes)
+          ? keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
+          : ["-keyint_min", String(segmentDurationSec * outFps)]),
         "-sc_threshold", "0"
       ];
     }
@@ -224,14 +259,14 @@ function vaapiDescriptor(device) {
     inputArgs: ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi", "-vaapi_device", device],
     // No fps filter: VAAPI inherits the source rate and keeps keyframes on the
     // grid via time-based -force_key_frames, so it already honours source fps.
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       return [
         "-vf",
         `scale_vaapi=w=${w}:h=${h}:force_original_aspect_ratio=decrease`,
         "-c:v", "h264_vaapi",
         "-qp", "24",
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -247,13 +282,13 @@ function qsvDescriptor(device) {
     kind: "qsv",
     device,
     inputArgs: ["-hwaccel", "qsv", "-qsv_device", device],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       return [
         "-vf", `scale_qsv=w=${w}:h=${h}`,
         "-c:v", "h264_qsv",
         "-global_quality", "24",
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -269,7 +304,7 @@ function nvencDescriptor() {
     // No fps filter: NVENC is fast and places keyframes by time-based
     // -force_key_frames, so it inherits the exact source rate (fractional
     // included) with no need to round or cap. Same rationale as VAAPI/QSV.
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       return [
         "-vf",
@@ -278,7 +313,7 @@ function nvencDescriptor() {
         "-preset", "p4",
         "-cq", "24",
         "-pix_fmt", "yuv420p",
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -296,7 +331,7 @@ function v4l2m2mDescriptor() {
     kind: "v4l2m2m",
     device: null,
     inputArgs: [],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, fps }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, fps, forcedKeyframeTimes }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       const outFps = Number.isInteger(fps) && fps > 0 ? fps : TRANSCODE_FPS;
       return [
@@ -308,8 +343,12 @@ function v4l2m2mDescriptor() {
         // userspace").
         "-num_capture_buffers", "32",
         "-b:v", "3M",
+        // Kept even with an explicit cut list, as an upper bound on the
+        // interval: this encoder is the one known not always to honour keyframe
+        // hints, and without any bound a list it ignores yields one segment for
+        // the whole file rather than a wrongly-cut one.
         "-g", String(outFps * segmentDurationSec),
-        ...keyFrameArgs(segmentDurationSec)
+        ...keyFrameArgs(segmentDurationSec, forcedKeyframeTimes)
       ];
     }
   };
@@ -322,7 +361,7 @@ function v4l2m2mDescriptor() {
  * @property {"software"|"vaapi"|"qsv"|"nvenc"|"v4l2m2m"} kind
  * @property {string|null} device
  * @property {string[]} inputArgs
- * @property {(opts: { targetWidth: number, targetHeight: number, segmentDurationSec: number }) => string[]} buildVideoArgs
+ * @property {(opts: { targetWidth: number, targetHeight: number, segmentDurationSec: number, preset?: string, fps?: number, tonemap?: boolean, forcedKeyframeTimes?: number[] | null }) => string[]} buildVideoArgs
  */
 
 /**

package/test/behind-head-repair.test.js

@@ -0,0 +1,187 @@
+/**
+ * @file A segment request below the running encode must not be held for ever.
+ *
+ * The encoder only moves forward from where its run began, so a request BELOW
+ * that point cannot be answered by anything the run does. Every other far
+ * request is a claim the running encode may yet reach; this one is a hole.
+ *
+ * Measured 2026-08-11: a quality switch placed a run at segment #770 while the
+ * player needed #757, and the request was held for two minutes forty-one while
+ * the encoder produced 409 s of video nobody had asked for at 2.48x. The
+ * placement that caused it is fixed; this is the guard that stops the SHAPE
+ * from hanging a session again, whatever puts it there.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const SESSION_ID = "bbbbbbbb-cccc-dddd-eeee-ffffffffffff";
+const SEGMENT_SECONDS = 4;
+const RUN_STARTS_AT = 770;
+const WANTED = 757;
+
+/**
+ * A session whose run began well past the segment being asked for.
+ *
+ * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string, restarts: number[] }>}
+ */
+async function managerWithRunAhead() {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "behind-head-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    fileName: "film.avi",
+    startedAt: Date.now(),
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    lastError: "",
+    consumers: new Set(),
+    segmentFormat: fmp4Format,
+    transcodeVideo: true,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentBoundaries: Array.from({ length: 1937 }, (_, index) => index * SEGMENT_SECONDS),
+    segmentCount: 1936,
+    encodeStartIndex: RUN_STARTS_AT,
+    encodeRunGeneration: 0,
+    lastRestartAt: 0,
+    seekFailureTarget: -1,
+    seekFailureCount: 0,
+    seekSettleTimer: null,
+    seekTarget: null,
+    waitEpoch: 0,
+    firstWantedAt: new Map(),
+    ffmpeg: { pid: 4321, exitCode: null, signalCode: null, kill() {}, once(event, handler) { if (event === "exit") handler(); } },
+    progress: { state: "running", processedSeconds: RUN_STARTS_AT * SEGMENT_SECONDS + 400, startPositionSeconds: RUN_STARTS_AT * SEGMENT_SECONDS }
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  const restarts = [];
+  return { manager, session, dirPath, restarts };
+}
+
+test("a request behind the run is repaired once it has waited", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // Asked for four seconds ago and still unanswerable.
+  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    WANTED - 1,
+    "the encoder must be moved back to it — one segment early, for the preceding keyframe"
+  );
+});
+
+test("a request behind the run is left alone at first", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "a burst around a reported seek settles by itself, and the seek is what should move the encoder"
+  );
+});
+
+test("a seek already settling is not overridden", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+  // The viewer has stated where they are and it is about to be acted on.
+  session.seekTarget = 1200;
+  session.seekSettleTimer = setTimeout(() => {}, 60_000);
+  t.after(() => clearTimeout(session.seekSettleTimer));
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    1200,
+    "a statement from the viewer outranks anything inferred from what the player is fetching"
+  );
+});
+
+test("a playlist scan far below the run is left where it belongs", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // A player that cannot get what it wants scans the playlist: field log
+  // 2026-08-02, probes at #178, #681, #725, #807, #74, #245, #387 within half a
+  // second. Steering on the lowest of those put the encoder at the start of the
+  // film and left the viewer's own requests unreachable ahead of it — the exact
+  // reason request-steering was removed from this proxy.
+  const probe = 74;
+  session.firstWantedAt.set(probe, Date.now() - 30_000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(probe), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "a misplaced run is out by a buffer; a scan probe is out by anything, and the two must not be confused"
+  );
+});
+
+test("a rung whose encoder was stopped is not brought back by a held request", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // What a quality switch leaves behind: the rung nobody is watching, parked.
+  session.ffmpeg = null;
+  session.firstWantedAt.set(WANTED, Date.now() - 4000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(WANTED), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "restarting it would put a second encoder on a host sized for one, for a rung nobody is watching"
+  );
+});
+
+test("a request ahead of the run is not touched", async (t) => {
+  const { manager, session, dirPath } = await managerWithRunAhead();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const ahead = RUN_STARTS_AT + 400;
+  session.firstWantedAt.set(ahead, Date.now() - 30_000);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(ahead), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    null,
+    "the running encode may yet reach it; restarting on a far request is what produced nine restarts in a minute"
+  );
+});

package/test/keyframe-index-accuracy.test.js

@@ -0,0 +1,68 @@
+/**
+ * @file How well a container's keyframe index describes its own file.
+ *
+ * The cut times of a copied video ARE its index — ffmpeg can only cut where a
+ * keyframe already is — and an index can be wrong: measured 2026-08-06, one
+ * claimed a keyframe at 157.99 s where the real ones were 153.82 and 164.247.
+ * Whether a re-encoded rung can be cut on that same grid and spliced into the
+ * copy depends entirely on how often that happens, so it is counted.
+ *
+ * No scan is involved and no undownloaded byte is touched: each produced piece
+ * states where it truly begins, and it is already read whole in order to be
+ * stamped. Only boundaries that were actually produced are counted — the parts
+ * somebody watched.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { newIndexCheck, noteIndexDeviation } from "../services/hls-session-manager.js";
+
+test("an index that describes its file exactly is reported as such", () => {
+  const check = newIndexCheck();
+
+  for (let index = 0; index < 4; index += 1) {
+    noteIndexDeviation(check, index, 0);
+  }
+
+  assert.equal(check.checked, 4);
+  assert.equal(check.disagreed, 0, "nothing disagreed — which is a finding, not silence");
+  assert.equal(check.maxDeviationSec, 0);
+});
+
+test("a boundary the index placed wrongly is counted, with how far out it was", () => {
+  const check = newIndexCheck();
+
+  noteIndexDeviation(check, 0, 0);
+  // The measured shape: the playlist said 157.99 s, the file cut at 153.82 s.
+  noteIndexDeviation(check, 2, 4.17);
+  noteIndexDeviation(check, 3, 0.01);
+
+  assert.equal(check.checked, 3);
+  assert.equal(check.disagreed, 1);
+  assert.equal(check.firstDisagreementIndex, 2);
+  assert.equal(
+    check.maxDeviationSec,
+    4.17,
+    "the size of the error is what decides whether a rung can be cut on this grid"
+  );
+});
+
+test("a deviation within tolerance is not a disagreement, but still shows in the worst case", () => {
+  const check = newIndexCheck();
+
+  noteIndexDeviation(check, 0, 0.2);
+
+  assert.equal(check.disagreed, 0, "rounding in a container's timestamps is not the index being wrong");
+  assert.equal(check.maxDeviationSec, 0.2, "and it is still worth knowing how close to the line it ran");
+});
+
+test("a segment requested again is not new evidence", () => {
+  const check = newIndexCheck();
+
+  noteIndexDeviation(check, 1, 0.9);
+  noteIndexDeviation(check, 1, 0.9);
+  noteIndexDeviation(check, 1, 0.9);
+
+  assert.equal(check.checked, 1, "a repeat request is the same boundary, counted once");
+  assert.equal(check.disagreed, 1);
+});

package/test/quality-variants.test.js

@@ -133,19 +133,37 @@ test("the master offers every rung, the session's own height among them", async
   );
 });
 
-test("a copied video is offered no variants", async (t) => {
+test("a copied video is offered variants when its cut grid is real", async (t) => {
   const { manager, base, dirPath } = await managerWithBase();
   t.after(async () => {
     await manager.disposeAll();
     await rm(dirPath, { recursive: true, force: true });
   });
+  // A copy is cut at the source's own keyframes — it has no other choice. A
+  // re-encoded rung CAN be cut there too, by being told those times, and then
+  // its segments cover the same spans and can stand in the copy's place.
   base.transcodeVideo = false;
+  base.cutGrid = "keyframe";
 
-  assert.equal(
-    manager.buildMasterPlaylist(BASE_ID),
-    null,
-    "its segments are cut at the source's own keyframes, so a re-encoded rung cannot be spliced into it"
-  );
+  const master = manager.buildMasterPlaylist(BASE_ID);
+
+  assert.ok(master, "the obstacle was never the encoder, it was the cut points");
+  assert.match(master, /^v\/1080\/index\.m3u8$/m, "the copy itself is the top rung — no encoder, no cost");
+  assert.match(master, /^v\/540\/index\.m3u8$/m);
+});
+
+test("a copied video with no readable keyframe index is offered nothing", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // Its playlist claims an even grid that ffmpeg does not cut on. Aligning a
+  // rung to that is aligning it to a fiction.
+  base.transcodeVideo = false;
+  base.cutGrid = "uniform";
+
+  assert.equal(manager.buildMasterPlaylist(BASE_ID), null);
 });
 
 test("the session's own height resolves to the session itself", async (t) => {
@@ -236,6 +254,62 @@ test("a segment request hands the encoder to the variant the viewer moved to", a
   );
 });
 
+test("a rung is placed where the player asked it for, not where the other rung had read to", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const variant = fakeSession({ id: VARIANT_ID, encodeHeight: 540, dirPath });
+  variant.variantHeight = 540;
+  variant.variantBases = new Set([BASE_ID]);
+  manager.sessionsById.set(VARIANT_ID, variant);
+  base.variants = new Map([[540, VARIANT_ID]]);
+  base.ffmpeg = fakeEncoder();
+  // The rung being left had read fourteen segments further than the picture had
+  // played — an encoder running at several times realtime fills the buffer far
+  // ahead. Measured 2026-08-11: 56 s of gap, and using the read head placed the
+  // new run past everything the player then asked for, which no request could
+  // ever be answered from.
+  base.lastRequestedSegment = 70;
+  base.viewerPositionSeconds = 280;
+
+  await manager.resolveVariantFile(BASE_ID, 540, "segment-00056.mp4");
+
+  assert.equal(
+    variant.seekTarget,
+    55,
+    "the segment the player asked this rung for is where it must begin (one back for the keyframe)"
+  );
+});
+
+test("warming a rung prepares it without taking the encoder from the one on screen", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const variant = fakeSession({ id: VARIANT_ID, encodeHeight: 540, dirPath });
+  variant.variantHeight = 540;
+  variant.variantBases = new Set([BASE_ID]);
+  manager.sessionsById.set(VARIANT_ID, variant);
+  base.variants = new Map([[540, VARIANT_ID]]);
+  const encoder = fakeEncoder();
+  base.ffmpeg = encoder;
+
+  const prepared = await manager.prepareVariant(BASE_ID, 540, 240);
+
+  assert.deepEqual(
+    prepared,
+    { sessionId: VARIANT_ID, fileName: "segment-00060.mp4" },
+    "the caller is told which segment to wait for — 240 s on a four-second grid"
+  );
+  assert.equal(variant.seekTarget, 59, "the rung is pointed at the switch position, one back for the keyframe");
+  assert.equal(base.activeVariantId, undefined, "nothing has switched yet");
+  assert.equal(base.ffmpeg, encoder, "the picture on screen keeps its encoder until the player actually moves");
+  assert.deepEqual(encoder.signals, [], "stopping it here is what would put the spinner back");
+});
+
 test("the viewer's position is kept current by the segments they ask for", async (t) => {
   const { manager, base, dirPath } = await managerWithBase();
   t.after(async () => {
@@ -306,21 +380,38 @@ test("a downshift does not rename the variant the viewer is watching", async (t)
   );
 });
 
-test("the cut grid does not depend on the encode height", () => {
-  // Why a segment from one encoder can stand where another's would have: on the
-  // re-encode path the boundaries are a uniform grid and the encoder is given a
-  // fixed GOP of the same length, so segment N covers the same span at every
-  // rung. Nothing about the height enters this — and nothing may, or the
-  // variants stop being interchangeable.
-  const shape = { transcodeVideo: true, durationSeconds: 100, segDur: SEGMENT_SECONDS, startTime: 0 };
-  const withIndex = computeSegmentBoundaries({ ...shape, keyframeTimes: [0, 3.1, 9.7, 14.2] });
-  const withoutIndex = computeSegmentBoundaries({ ...shape, keyframeTimes: null });
+test("the cut grid follows the grid asked for, not who produces the frames", () => {
+  // Why a segment from one encoder can stand where another's would have: both
+  // are cut at the same times. Which times is a property of the SESSION — the
+  // even grid, or the source's own keyframes — and it must not be re-derived
+  // from whether the video is copied, because a variant of a copied stream is
+  // re-encoded and still has to land on the copy's cuts.
+  const shape = { durationSeconds: 100, segDur: SEGMENT_SECONDS, startTime: 0 };
+  const keyframeTimes = [0, 3.1, 9.7, 14.2, 21.5, 40, 61.25];
 
+  const even = computeSegmentBoundaries({ ...shape, useKeyframeGrid: false, keyframeTimes });
+  assert.equal(even[1], SEGMENT_SECONDS, "the even grid ignores the source's keyframes");
+  assert.equal(even.at(-1), 100);
+
+  const source = computeSegmentBoundaries({ ...shape, useKeyframeGrid: true, keyframeTimes });
+  assert.deepEqual(
+    source,
+    [0, 9.7, 14.2, 21.5, 40, 61.25, 100],
+    "the source's own keyframes, kept only where they are at least a segment apart"
+  );
+
+  // The one that matters: a copy and a re-encoded rung of it, given the same
+  // grid, produce the SAME table. Segment N then covers the same span in both,
+  // which is what lets one stand where the other would have.
+  assert.deepEqual(
+    computeSegmentBoundaries({ ...shape, useKeyframeGrid: true, keyframeTimes }),
+    source,
+    "a variant inherits the grid, so its boundaries are the same values"
+  );
+  // And with no index there is nothing to align to — the even grid, whoever asks.
   assert.deepEqual(
-    withIndex,
-    withoutIndex,
-    "a re-encode forces its own keyframes onto the grid, so the source's keyframes cannot move the cuts"
+    computeSegmentBoundaries({ ...shape, useKeyframeGrid: true, keyframeTimes: null }),
+    even,
+    "no keyframes means no keyframe grid, however the caller asks"
   );
-  assert.equal(withIndex[1], SEGMENT_SECONDS);
-  assert.equal(withIndex.at(-1), 100);
 });

package/test/segment-serve-wiring.test.js

@@ -153,6 +153,22 @@ async function managerWithReadySegment(overrides = {}) {
   return { manager, session, dirPath };
 }
 
+test("serving a segment records what its real start says about the container's index", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The tally is counted in the module tests; what this pins is that serving a
+  // segment reaches it at all. A counter nothing increments reports a clean
+  // index for every file forever, which is worse than no measurement.
+  session.indexCheck = { checked: 0, disagreed: 0, maxDeviationSec: 0, firstDisagreementIndex: -1, seen: new Set() };
+
+  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(session.indexCheck.checked, 1, "the boundary that was just produced must have been examined");
+});
+
 test("a segment that exists is served, not reported as still being produced", async (t) => {
   const { manager, dirPath } = await managerWithReadySegment();
   t.after(async () => {
@@ -226,37 +242,37 @@ test("a run's FIRST segment is served once the encoder has passed it, without wa
     "the encoder is past this segment's end, so it is finished — the absence of a next one says nothing"
   );
 });
-
-test("a segment is found in the run directory that produced it, newest run first", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // Runs write into a directory each — that is what lets a restart begin
-  // without waiting for its predecessor to die, which measured 0.7-1.3 s of
-  // every seek. A later run's answer supersedes an earlier one's, because the
-  // older file may be the truncated output of a run that was killed mid-write.
-  const { mkdir } = await import("node:fs/promises");
-  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
-  await mkdir(path.join(dirPath, "run-1"), { recursive: true });
-  await mkdir(path.join(dirPath, "run-2"), { recursive: true });
-  await writeFile(path.join(dirPath, "run-1", "segment-00000.mp4"), Buffer.alloc(8));
-  await writeFile(path.join(dirPath, "run-2", "segment-00000.mp4"), piece);
-  await writeFile(path.join(dirPath, "run-2", "segment-00001.mp4"), piece);
-  await rm(path.join(dirPath, "segment-00000.mp4"));
-  await rm(path.join(dirPath, "segment-00001.mp4"));
-  session.encodeStartIndex = 0;
-
-  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(result.kind, "file", "a segment produced by a run must be found in that run's directory");
-  const chunks = [];
-  for await (const chunk of result.stream) {
-    chunks.push(chunk);
-  }
-  assert.ok(
-    Buffer.concat(chunks).length > 8,
-    "the newest run's output must win — the older file here is the 8-byte stub a killed run leaves"
-  );
-});
+
+test("a segment is found in the run directory that produced it, newest run first", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // Runs write into a directory each — that is what lets a restart begin
+  // without waiting for its predecessor to die, which measured 0.7-1.3 s of
+  // every seek. A later run's answer supersedes an earlier one's, because the
+  // older file may be the truncated output of a run that was killed mid-write.
+  const { mkdir } = await import("node:fs/promises");
+  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
+  await mkdir(path.join(dirPath, "run-1"), { recursive: true });
+  await mkdir(path.join(dirPath, "run-2"), { recursive: true });
+  await writeFile(path.join(dirPath, "run-1", "segment-00000.mp4"), Buffer.alloc(8));
+  await writeFile(path.join(dirPath, "run-2", "segment-00000.mp4"), piece);
+  await writeFile(path.join(dirPath, "run-2", "segment-00001.mp4"), piece);
+  await rm(path.join(dirPath, "segment-00000.mp4"));
+  await rm(path.join(dirPath, "segment-00001.mp4"));
+  session.encodeStartIndex = 0;
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(result.kind, "file", "a segment produced by a run must be found in that run's directory");
+  const chunks = [];
+  for await (const chunk of result.stream) {
+    chunks.push(chunk);
+  }
+  assert.ok(
+    Buffer.concat(chunks).length > 8,
+    "the newest run's output must win — the older file here is the 8-byte stub a killed run leaves"
+  );
+});