@torrent-tv/proxy 2.86.0 → 2.87.0

package/test/seek-frees-the-viewers-requests.test.js

@@ -0,0 +1,217 @@
+/**
+ * @file A seek must free the requests it made pointless, on every output that
+ * viewer watches, and only theirs.
+ *
+ * hls.js keeps ONE fragment load outstanding per track, so a request held for a
+ * segment the viewer has just left blocks the request for where they now are.
+ * Measured 2026-08-04: 57 s of a 58 s backward seek was that wait, and the
+ * segment they wanted was served in 15 ms once it was asked for.
+ *
+ * The guard against it was built — the route compares a seek epoch and asks
+ * whether each held request is still wanted — and nothing moved that epoch: no
+ * caller of `invalidateWaits` was a seek.
+ *
+ * TWO THINGS THIS CHECK HAS TO DO, and the first version of it did neither.
+ * It must wait until the store really HOLDS the waits, because a seek that
+ * happens before they are registered frees nothing and passes all the same; and
+ * it must cover the three outputs one viewer watches — the picture the browser
+ * addresses, the step on their screen, their soundtrack — because waking only
+ * the one the browser named leaves two thirds of their requests standing.
+ *
+ * And waking is not cancelling: one viewer's seek must leave another viewer's
+ * request for the same segment of the same output exactly where it was.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { wireOutputs } from "../services/server/wire-outputs.js";
+import { waitForSessionFile } from "../routes/transcode/session-file/get.js";
+import { SourceFile } from "../services/media/SourceFile.js";
+import { Timeline } from "../services/encode/output/Timeline.js";
+import { Output } from "../services/encode/output/Output.js";
+import { KeyframeTable } from "../services/media/container/KeyframeTable.js";
+import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
+import { outputSpec } from "./helpers/output-spec.js";
+
+const SESSION_ID = "2222222233334444";
+const OUTPUT_KEY = "seek-frees:fmt=fmp4:grid=uniform:video-only:v=0/copy";
+const STEP_ID = "3333333344445555";
+const STEP_KEY = "seek-frees:fmt=fmp4:grid=uniform:video-only:v=0/libx264/960x540";
+const SOUND_ID = "4444444455556666";
+const SOUND_KEY = "seek-frees:fmt=fmp4:grid=uniform:audio-only:a=0/0/aac";
+/** Long enough that running out of it is a failure and never the measurement. */
+const HOLD_MS = 30_000;
+
+/**
+ * One output of the film, with nothing produced for it yet.
+ *
+ * @param {object} manager
+ * @param {{ id: string, key: string, audioOnly?: boolean, height?: number }} what
+ * @returns {object}
+ */
+function outputOn(manager, { id, key, audioOnly = false, height = 0 }) {
+  manager.segmentStore.useFormat(key, fmp4Format);
+  const dirPath = manager.segmentStore.directoryFor(key);
+  const session = {
+    id,
+    spec: outputSpec({ transcodeVideo: height > 0, height, audioOnly, cutGrid: "uniform" }),
+    outputKey: key,
+    dirPath,
+    timeline: new Timeline({ boundaries: [0, 12.5, 25, 37.5, 50, 62.5], cutGrid: "uniform" }),
+    state: "ready",
+    file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "video.mkv" }).learn({ durationSeconds: 62.5 }),
+    get inputFile() { return this.file; },
+    get audioFile() { return this.file; },
+    lastAloneSpeed: 2,
+    startedAt: Date.now(),
+    lastAccessedAt: Date.now(),
+    runs: new Set(),
+    lastError: "",
+    consumers: new Set(),
+    viewers: new Map(),
+    segmentCount: 5,
+    segmentFormat: fmp4Format,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    output: new Output({ encodeWidth: 0, encodeHeight: height, outputFps: 25, softwarePreset: null, applyTonemap: false }),
+    keyframes: new KeyframeTable().learn({ times: [0, 12.5, 25, 37.5, 50], format: "matroska" }),
+    audioOnly,
+    waitEpoch: 0
+  };
+  manager.outputs.set(id, session);
+  return session;
+}
+
+/**
+ * Wait until the store really holds this many waits on an output.
+ *
+ * The deadline is a backstop and never the measurement: what is waited for is
+ * the registration itself, which is the store's own state.
+ *
+ * @param {object} manager
+ * @param {string} key
+ * @param {number} howMany
+ * @returns {Promise<void>}
+ */
+async function untilWaitsAreRegistered(manager, key, howMany) {
+  const giveUpAt = Date.now() + 5_000;
+  while (manager.segmentStore.waitingFor(key) < howMany) {
+    if (Date.now() > giveUpAt) {
+      throw new Error(`only ${manager.segmentStore.waitingFor(key)} wait(s) on ${key} after 5s`);
+    }
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+}
+
+/**
+ * The picture, one quality step and one soundtrack of a film, with two viewers
+ * on the picture and one of them also on the step and the soundtrack.
+ *
+ * @returns {{ manager: object, session: object, step: object, sound: object }}
+ */
+function filmWithThreeOutputs() {
+  const manager = wireOutputs({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  // No plan runs here: this is about the path that answers a request, and
+  // letting the plan run would spawn real encoders.
+  manager.encodeRuns.planEncodersNow = () => {};
+  manager.encodeRuns.planEncodersSoon = () => {};
+  const session = outputOn(manager, { id: SESSION_ID, key: OUTPUT_KEY });
+  const step = outputOn(manager, { id: STEP_ID, key: STEP_KEY, height: 540 });
+  const sound = outputOn(manager, { id: SOUND_ID, key: SOUND_KEY, audioOnly: true });
+  for (const consumerId of ["viewer-a", "viewer-b"]) {
+    manager.viewers.of(session, consumerId).moveTo(0);
+  }
+  for (const output of [step, sound]) {
+    manager.viewers.of(step === output ? step : sound, "viewer-a").moveTo(0);
+  }
+  return { manager, session, step, sound };
+}
+
+/**
+ * @param {object} manager
+ * @param {string} consumerId
+ * @param {string} sessionId
+ * @returns {Promise<{ kind: string }>}
+ */
+function holdFor(manager, consumerId, sessionId = SESSION_ID) {
+  return waitForSessionFile(manager.serving, sessionId, "segment-00000.mp4", {
+    holdMs: HOLD_MS,
+    consumerId
+  });
+}
+
+test("a seek frees the seeker's requests on every output they watch", async (t) => {
+  const { manager, session, step, sound } = filmWithThreeOutputs();
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    for (const output of [session, step, sound]) {
+      await rm(output.dirPath, { recursive: true, force: true });
+    }
+  });
+
+  const onPicture = holdFor(manager, "viewer-a");
+  const onStep = holdFor(manager, "viewer-a", STEP_ID);
+  const onSound = holdFor(manager, "viewer-a", SOUND_ID);
+  let stayed = "still held";
+  const stayer = holdFor(manager, "viewer-b").then((result) => {
+    stayed = result.kind;
+    return result;
+  });
+  // Every one of them must EXIST before the seek, or the check proves nothing.
+  await untilWaitsAreRegistered(manager, OUTPUT_KEY, 2);
+  await untilWaitsAreRegistered(manager, STEP_KEY, 1);
+  await untilWaitsAreRegistered(manager, SOUND_KEY, 1);
+
+  const startedAt = Date.now();
+  assert.equal(manager.viewerRequests.requestSeek(SESSION_ID, 50, "viewer-a"), true);
+
+  const released = await Promise.all([onPicture, onStep, onSound]);
+  const heldMs = Date.now() - startedAt;
+
+  for (const [index, answer] of released.entries()) {
+    assert.equal(
+      answer.kind,
+      "superseded",
+      `the request on output ${index} was made for a position its viewer has left`
+    );
+  }
+  assert.ok(heldMs < HOLD_MS / 2, `they were freed after ${heldMs}ms, which is the hold running out`);
+
+  // A grace before asserting that something did NOT happen: it can only ever
+  // pass too easily, never fail by luck.
+  await delay(300);
+  assert.equal(stayed, "still held", "the other viewer is where they were and still wants this segment");
+  void stayer;
+});
+
+test("the request that was kept is served when its segment appears", async (t) => {
+  const { manager, session, step, sound } = filmWithThreeOutputs();
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    for (const output of [session, step, sound]) {
+      await rm(output.dirPath, { recursive: true, force: true });
+    }
+  });
+
+  const seeker = holdFor(manager, "viewer-a");
+  const stayer = holdFor(manager, "viewer-b");
+  await untilWaitsAreRegistered(manager, OUTPUT_KEY, 2);
+  manager.viewerRequests.requestSeek(SESSION_ID, 50, "viewer-a");
+  assert.equal((await seeker).kind, "superseded");
+
+  // The piece the viewer who stayed was waiting for, written as a run writes
+  // it: under its served name, which is the whole of what says it is closed.
+  await writeFile(path.join(session.dirPath, fmp4Format.segmentFileName(0)), Buffer.alloc(256, 0x5a));
+
+  const answer = await stayer;
+
+  assert.equal(answer.kind, "file", `a wake is a re-check, not a cancellation — got ${answer.kind}`);
+});

package/test/seek-landing.test.js

@@ -14,34 +14,34 @@
  */
 
 import assert from "node:assert/strict";
-import { SourceFile } from "../services/source/SourceFile.js";
+import { KeyframeTable } from "../services/media/container/KeyframeTable.js";
 import test from "node:test";
 
-import { seekLandingOffsetFor } from "../services/hls-session-manager.js";
+import { seekLandingOffsetFor } from "../services/encode/run-command.js";
 
 const OFFSET = 3 / 23;
 
 test("a copied picture is asked for one heuristic later than the keyframe", () => {
-  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 2.002, 4.004, 6.006] }) };
+  const session = { transcodeVideo: false, keyframes: new KeyframeTable().learn({ times: [0, 2.002, 4.004, 6.006] }) };
   assert.equal(seekLandingOffsetFor(session, 2.002), OFFSET);
 });
 
 test("a re-encode is asked for exactly what it should produce", () => {
   // It decodes from the keyframe and discards frames up to the requested time,
   // so pushing the request later would start its output late.
-  const session = { transcodeVideo: true, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 2.002, 4.004] }) };
+  const session = { transcodeVideo: true, keyframes: new KeyframeTable().learn({ times: [0, 2.002, 4.004] }) };
   assert.equal(seekLandingOffsetFor(session, 2.002), 0);
 });
 
 test("the offset never reaches the next keyframe", () => {
   // Keyframes 0.1 s apart: half of that is the most that can be added without
   // risking a landing on the NEXT one where the heuristic does not fire.
-  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 0.1, 0.2, 0.3] }) };
+  const session = { transcodeVideo: false, keyframes: new KeyframeTable().learn({ times: [0, 0.1, 0.2, 0.3] }) };
   assert.equal(seekLandingOffsetFor(session, 0.1), 0.05);
 });
 
 test("the last keyframe has nothing after it to collide with", () => {
-  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 2.002, 4.004] }) };
+  const session = { transcodeVideo: false, keyframes: new KeyframeTable().learn({ times: [0, 2.002, 4.004] }) };
   assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET);
 });
 
@@ -58,7 +58,7 @@ test("a grid whose times are approximate is asked for that much later again", ()
   // the one before that, which is the fault this offset exists for.
   const session = {
     transcodeVideo: false,
-    file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 4.004, 8.008, 12.012], keyframeTolerance: 0.04 })
+    keyframes: new KeyframeTable().learn({ times: [0, 4.004, 8.008, 12.012], tolerance: 0.04 })
   };
   assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET + 0.04);
 });
@@ -66,12 +66,12 @@ test("a grid whose times are approximate is asked for that much later again", ()
 test("an exact grid claims no tolerance", () => {
   // Matroska and MP4 state instants outright — measured the same day, nine
   // files and 11 665 keyframes with not one disagreement.
-  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 4.004, 8.008], keyframeTolerance: 0 }) };
+  const session = { transcodeVideo: false, keyframes: new KeyframeTable().learn({ times: [0, 4.004, 8.008], tolerance: 0 }) };
   assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET);
 });
 
 test("the bound still holds once a tolerance is added", () => {
-  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 0.1, 0.2], keyframeTolerance: 1 }) };
+  const session = { transcodeVideo: false, keyframes: new KeyframeTable().learn({ times: [0, 0.1, 0.2], tolerance: 1 }) };
   assert.equal(seekLandingOffsetFor(session, 0.1), 0.05);
 });
 
@@ -89,8 +89,8 @@ test("an output carrying only sound is not pushed past what it asked for", () =>
   const soundtrack = {
     audioOnly: true,
     transcodeVideo: false,
-    file: new SourceFile({ sourceKey: "s", fileIndex: 0 })
-      .learn({ keyframeTimes: [0, 4.004, 8.008, 12.012], keyframeTolerance: 0 })
+    keyframes: new KeyframeTable()
+      .learn({ times: [0, 4.004, 8.008, 12.012], tolerance: 0 })
   };
   assert.equal(seekLandingOffsetFor(soundtrack, 4.004), 0);
 });
@@ -102,8 +102,8 @@ test("the picture of the same film still gets the offset", () => {
   const picture = {
     audioOnly: false,
     transcodeVideo: false,
-    file: new SourceFile({ sourceKey: "s", fileIndex: 0 })
-      .learn({ keyframeTimes: [0, 4.004, 8.008, 12.012], keyframeTolerance: 0 })
+    keyframes: new KeyframeTable()
+      .learn({ times: [0, 4.004, 8.008, 12.012], tolerance: 0 })
   };
   assert.equal(seekLandingOffsetFor(picture, 4.004), OFFSET);
 });

package/test/seek-target-not-superseded.test.js

@@ -15,16 +15,15 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { SourceFile } from "../services/source/SourceFile.js";
-import { Timeline } from "../services/output/Timeline.js";
+import { SourceFile } from "../services/media/SourceFile.js";
+import { Timeline } from "../services/encode/output/Timeline.js";
 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 { viewerOf } from "../services/viewer/Viewer.js";
-import { fmp4Format } from "../services/segment-formats/fmp4.js";
+import { wireOutputs } from "../services/server/wire-outputs.js";
+import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
 
-const SESSION_ID = "aaaaaaaa-1111-2222-3333-444444444444";
+const SESSION_ID = "aaaaaaaa11112222";
 const SEGMENT_SECONDS = 10.4;
 const SEEK_TO_SECONDS = 1061;
 const SEGMENT_AT_SEEK = Math.floor(SEEK_TO_SECONDS / SEGMENT_SECONDS);
@@ -32,11 +31,11 @@ const SEGMENT_AT_SEEK = Math.floor(SEEK_TO_SECONDS / SEGMENT_SECONDS);
 /**
  * A session whose viewer has just landed at {@link SEEK_TO_SECONDS}.
  *
- * @returns {Promise<{ manager: HlsSessionManager, dirPath: string }>}
+ * @returns {Promise<{ manager: object, dirPath: string }>}
  */
 async function managerAfterSeek() {
   const dirPath = await mkdtemp(path.join(os.tmpdir(), "seek-target-"));
-  const manager = new HlsSessionManager({
+  const manager = wireOutputs({
     enabled: true,
     ffmpegBin: "ffmpeg",
     localBindHost: "127.0.0.1",
@@ -68,9 +67,9 @@ async function managerAfterSeek() {
     waitEpoch: 1,
     runState: "PRODUCING"
   };
-  manager.sessionsById.set(SESSION_ID, session);
-  viewerOf(session, "").moveTo(SEEK_TO_SECONDS);
-  viewerOf(session, "").playing = false;
+  manager.outputs.set(SESSION_ID, session);
+  manager.viewers.of(session, "viewer").moveTo(SEEK_TO_SECONDS);
+  manager.viewers.of(session, "viewer").playing = false;
   return { manager, dirPath };
 }
 
@@ -78,7 +77,7 @@ test("the segment at the seek target is still wanted", async () => {
   const { manager, dirPath } = await managerAfterSeek();
 
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK).padStart(5, "0")}.mp4`),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK).padStart(5, "0")}.mp4`),
     true,
     "this is the segment the viewer is waiting for; refusing it is what froze the field session"
   );
@@ -90,7 +89,7 @@ test("a segment behind the viewer is not wanted any more", async () => {
   const { manager, dirPath } = await managerAfterSeek();
 
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK - 3).padStart(5, "0")}.mp4`),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK - 3).padStart(5, "0")}.mp4`),
     false,
     "a request for the position the viewer left is exactly what the epoch exists to release"
   );
@@ -102,7 +101,7 @@ test("a segment far beyond what the run will reach is not wanted", async () => {
   const { manager, dirPath } = await managerAfterSeek();
 
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK + 200).padStart(5, "0")}.mp4`),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK + 200).padStart(5, "0")}.mp4`),
     false,
     "nothing will produce it before the viewer moves again"
   );
@@ -113,8 +112,8 @@ test("a segment far beyond what the run will reach is not wanted", async () => {
 test("a playlist belongs to no position and is never stale", async () => {
   const { manager, dirPath } = await managerAfterSeek();
 
-  assert.equal(manager.requestStillWanted(SESSION_ID, "index.m3u8"), true);
-  assert.equal(manager.requestStillWanted(SESSION_ID, "init.mp4"), true);
+  assert.equal(manager.serving.requestStillWanted(SESSION_ID, "index.m3u8"), true);
+  assert.equal(manager.serving.requestStillWanted(SESSION_ID, "init.mp4"), true);
 
   await rm(dirPath, { recursive: true, force: true });
 });
@@ -131,7 +130,7 @@ test("a request as deep as the cushion the browser is told to hold is still want
 
   assert.ok(edge - SEGMENT_AT_SEEK > 8, "the case only exists past the old eight-segment width");
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(edge).padStart(5, "0")}.mp4`),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(edge).padStart(5, "0")}.mp4`),
     true,
     "the far edge of the cushion the proxy itself keeps produced"
   );
@@ -141,25 +140,25 @@ test("a request as deep as the cushion the browser is told to hold is still want
 
 test("the viewer who made the request is the one it is judged against", async () => {
   const { manager, dirPath } = await managerAfterSeek();
-  const session = manager.sessionsById.get(SESSION_ID);
+  const session = manager.outputs.get(SESSION_ID);
   session.viewers = new Map();
   // Two people watching one copied picture: one at the seek target, one a
   // hundred segments back and waiting for a segment there. Asked about nobody
   // in particular the answer is the FURTHEST of them, because what lies behind
   // that one has already been made.
   const behind = SEGMENT_AT_SEEK - 100;
-  viewerOf(session, "behind").moveTo(behind * SEGMENT_SECONDS);
-  viewerOf(session, "behind").playing = false;
-  viewerOf(session, "ahead").moveTo(SEEK_TO_SECONDS);
-  viewerOf(session, "ahead").playing = false;
+  manager.viewers.of(session, "behind").moveTo(behind * SEGMENT_SECONDS);
+  manager.viewers.of(session, "behind").playing = false;
+  manager.viewers.of(session, "ahead").moveTo(SEEK_TO_SECONDS);
+  manager.viewers.of(session, "ahead").playing = false;
 
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(behind).padStart(5, "0")}.mp4`, "behind"),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(behind).padStart(5, "0")}.mp4`, "behind"),
     true,
     "held for the viewer who is there, whatever the viewer in front is doing"
   );
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(behind).padStart(5, "0")}.mp4`),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(behind).padStart(5, "0")}.mp4`),
     false,
     "unnamed, it is judged against the furthest viewer, which is the leader"
   );
@@ -169,25 +168,25 @@ test("the viewer who made the request is the one it is judged against", async ()
 
 test("a seek moves the seeking viewer's own head, and nobody else's", async () => {
   const { manager, dirPath } = await managerAfterSeek();
-  const session = manager.sessionsById.get(SESSION_ID);
+  const session = manager.outputs.get(SESSION_ID);
   session.viewers = new Map();
   const staying = SEGMENT_AT_SEEK - 40;
-  viewerOf(session, "staying").position = {
+  manager.viewers.of(session, "staying").position = {
     segment: staying,
     seconds: staying * SEGMENT_SECONDS,
     at: Date.now()
   };
 
   const jumpTo = 120;
-  manager.requestSeek(SESSION_ID, jumpTo, "jumping");
+  manager.viewerRequests.requestSeek(SESSION_ID, jumpTo, "jumping");
 
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(Math.floor(jumpTo / SEGMENT_SECONDS)).padStart(5, "0")}.mp4`, "jumping"),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(Math.floor(jumpTo / SEGMENT_SECONDS)).padStart(5, "0")}.mp4`, "jumping"),
     true,
     "the segment at the seek target — the request that raced the epoch in 2026-08-18"
   );
   assert.equal(
-    manager.requestStillWanted(SESSION_ID, `segment-${String(staying).padStart(5, "0")}.mp4`, "staying"),
+    manager.serving.requestStillWanted(SESSION_ID, `segment-${String(staying).padStart(5, "0")}.mp4`, "staying"),
     true,
     "somebody else's seek does not move where this viewer is"
   );

package/test/segment-closed-on-both-branches.test.js

@@ -0,0 +1,96 @@
+/**
+ * @file A piece is closed by one of two writers, and both must say so.
+ *
+ * The `segment` muxer writes under a working name and reports the closure on a
+ * channel of its own, which reaches `SegmentStore.publish`. The `hls` muxer
+ * writes through a temporary name of its own (`+temp_file`) and reports
+ * nothing: the file simply appears under the name it is served as. That branch
+ * is taken by every re-encoded output cut on the even grid — an ordinary
+ * quality step — and for it a wait could only end on its deadline, so a segment
+ * lying finished on disk was answered 503 after the whole hold.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SegmentStore } from "../services/storage/segment-store/SegmentStore.js";
+import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
+
+const KEY = "torrent:abc:fmt=fmp4:grid=uniform@0:video-only:v=libx264/854x480";
+
+/** A deadline is the backstop of these waits, never what they measure. */
+const BACKSTOP_MS = 10_000;
+
+/**
+ * @returns {{ store: SegmentStore, root: string }}
+ */
+function storeInATempRoot() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "segment-closed-"));
+  const store = new SegmentStore({ root, logger: { info: () => {}, warn: () => {} } });
+  store.useFormat(KEY, fmp4Format);
+  return { store, root };
+}
+
+test("a piece that simply appears ends the wait that began before it", async (t) => {
+  const { store, root } = storeInATempRoot();
+  t.after(() => {
+    store.dropAll("the test is over");
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const dir = store.directoryFor(KEY);
+  // The wait begins on a segment nobody has written yet — the cold case, and
+  // the only one the deadline used to decide.
+  const waited = store.waitFor(KEY, 7, BACKSTOP_MS);
+
+  // What the `hls` muxer does: a temporary name of its own, renamed into place
+  // when the piece is whole. Nothing is told; the directory simply moves.
+  const temp = path.join(dir, "segment-00007.mp4.tmp");
+  writeFileSync(temp, Buffer.alloc(64));
+  renameSync(temp, path.join(dir, fmp4Format.segmentFileName(7)));
+
+  assert.equal(await waited, true, "the piece was on disk and the wait did not end");
+  assert.ok(store.pathOf(KEY, 7), "and the store must be able to hand it over");
+});
+
+test("clearing up after a run is not its pieces arriving", async (t) => {
+  const { store, root } = storeInATempRoot();
+  t.after(() => {
+    store.dropAll("the test is over");
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const dir = store.directoryFor(KEY);
+  const unfinished = path.join(dir, fmp4Format.makingFileNameTemplate("3").replace("%05d", "00009"));
+  writeFileSync(unfinished, Buffer.alloc(64));
+
+  let ended = false;
+  // 200 ms is a grace before asserting that something did NOT happen, which can
+  // only ever pass too easily — never a measurement.
+  const waited = store.waitFor(KEY, 9, 200).then((value) => {
+    ended = value;
+    return value;
+  });
+  rmSync(unfinished, { force: true });
+
+  assert.equal(await waited, false, "a directory that moved because a file went holds nothing new");
+  assert.equal(ended, false);
+});
+
+test("the writer that does report a closure is unaffected", async (t) => {
+  const { store, root } = storeInATempRoot();
+  t.after(() => {
+    store.dropAll("the test is over");
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const dir = store.directoryFor(KEY);
+  const making = fmp4Format.makingFileNameTemplate("4").replace("%05d", "00004");
+  writeFileSync(path.join(dir, making), Buffer.alloc(64));
+
+  const waited = store.waitFor(KEY, 4, BACKSTOP_MS);
+  assert.equal(store.publish(KEY, making, fmp4Format), fmp4Format.segmentFileName(4));
+  assert.equal(await waited, true);
+});

package/test/segment-cut-times.test.js

@@ -12,7 +12,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { segmentCutTimesFrom } from "../services/hls-session-manager.js";
+import { segmentCutTimesFrom } from "../services/encode/run-command.js";
 
 test("cut times are the interior boundaries, rebased on the run start", () => {
   // Segments 0-10, 10-20, 20-30, 30-40 (file ends at 40).

package/test/segment-hold-supersede.test.js

@@ -10,6 +10,13 @@
  * `research/hls-seek-prior-art-2026-08-02.md` prescribed this guard from
  * `hls-media-server` — one outstanding wait per session — and it was never
  * built.
+ *
+ * WHAT IS LEFT HERE IS THE ROUTE'S OWN BEHAVIOUR: a segment that arrives while
+ * a request is held must still be served. The release itself moved to
+ * `test/seek-frees-the-viewers-requests.test.js`, and the check that stood here
+ * is why: it replaced `waitForSegment` with a function returning true and moved
+ * the epoch by hand, so it described the route against a stand-in and passed
+ * for months while no seek moved that epoch at all.
  */
 
 import test from "node:test";
@@ -40,47 +47,33 @@ function recordingReply() {
   return { reply, sent };
 }
 
-const request = (fileName) => ({
-  params: { sessionId: "11111111-2222-3333-4444-555555555555", fileName },
-  raw: { on() {}, off() {} }
+/**
+ * What the file route asks of the viewer operations besides the hold itself:
+ * whether the request's generation is still taken, the record of what answered
+ * it, and the hold a response keeps. Everything is taken and recorded nowhere,
+ * because these checks are about the hold.
+ *
+ * @param {object} serving
+ * @returns {object}
+ */
+const routeViewerRequests = (serving) => ({
+  ...serving,
+  acceptsRequest: () => true,
+  noteAnsweredDirectly: () => {},
+  holdResponse: () => () => {}
 });
 
-test("a seek releases a held segment request instead of running out the hold", async () => {
-  let epoch = 0;
-  let polls = 0;
-  const hlsSessionManager = {
-    nextRequestSeq: () => 1,
-    seekEpoch: () => epoch,
-    // The viewer seeked AWAY from this segment, so it is genuinely stale. A
-    // request for the segment they seeked TO is kept instead — see
-    // `test/seek-target-not-superseded.test.js`.
-    requestStillWanted: () => false,
-    viewerPositionOf: () => 0,
-    async getFileStream() {
-      polls += 1;
-      // The viewer moves while this request is being held.
-      if (polls === 2) {
-        epoch += 1;
-      }
-      return { kind: "warming-up" };
-    }
-  };
-
-  const { reply, sent } = recordingReply();
-  const startedAt = Date.now();
-  await handleTranscodeSessionFileGet(request("segment-00609.mp4"), reply, { hlsSessionManager });
-  const heldMs = Date.now() - startedAt;
-
-  assert.equal(sent.code, 503, "the player must get a retryable answer, not a stream");
-  assert.equal(sent.headers["retry-after"], "0", "nothing to wait for — this segment is not being watched");
-  assert.ok(heldMs < 5_000, `the request was held ${heldMs}ms after the seek`);
+const request = (fileName) => ({
+  params: { sessionId: "1111111122223333", fileName },
+  raw: { on() {}, off() {} }
 });
 
 test("without a seek the request is still held until the segment appears", async () => {
   let polls = 0;
-  const hlsSessionManager = {
-    nextRequestSeq: () => 1,
+  const serving = {
     seekEpoch: () => 7,
+    // The segment is published between polls.
+    waitForSegment: async () => true,
     async getFileStream() {
       polls += 1;
       if (polls < 3) {
@@ -91,7 +84,7 @@ test("without a seek the request is still held until the segment appears", async
   };
 
   const { reply, sent } = recordingReply();
-  await handleTranscodeSessionFileGet(request("segment-00610.mp4"), reply, { hlsSessionManager });
+  await handleTranscodeSessionFileGet(request("segment-00610.mp4"), reply, { serving: serving, viewerRequests: routeViewerRequests(serving) });
 
   assert.equal(sent.body, "bytes", "a segment that arrives late must still be served");
   assert.equal(sent.headers["content-type"], "video/mp4");