@torrent-tv/proxy 2.87.21 → 2.88.0

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

@@ -1,475 +1,475 @@
-/**
- * @file A finished segment on disk must reach the viewer as bytes.
- *
- * The module tests cover each piece of the fMP4 path on its own, and every one
- * of them passed while playback was dead: 2.9.124 called
- * `readSelfContainedStartSeconds` from `fmp4.js` without importing it, and the
- * unit test imports that function straight from `mp4-boxes.js`, so the gap
- * between a module and its CALLER was invisible. This test asks the session
- * manager for a segment that exists and insists on getting it.
- *
- * The second half pins the reason a one-word slip cost a whole release: the
- * failure was reported as "still being produced". Measured 2026-08-08 — segment
- * #0 was held for 45 281 ms with twelve finished segments in the directory, and
- * the log said nothing at all. Anything that goes wrong while preparing a file
- * that EXISTS must be named and answered, never turned into an endless wait.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-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 { rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { wireOutputs } from "../services/server/wire-outputs.js";
-import { ENCODE_RUN_STATE } from "../services/encode/encode-run-state.js";
-import { startRunOn } from "./helpers/encode-run.js";
-import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
-import { outputSpec } from "./helpers/output-spec.js";
-
-const MOVIE_TIMESCALE = 1000;
-const VIDEO_TIMESCALE = 90_000;
-const AUDIO_TIMESCALE = 48_000;
-const SEGMENT_START_SECONDS = 12.5;
-const SESSION_ID = "1111111122223333";
-// Its own address, so this file's directory in the shared store is nobody
-// else's.
-const OUTPUT_KEY = "serve-wiring:fmt=fmp4:grid=uniform:video-only:v=0/copy";
-
-/**
- * @param {string} type
- * @param {Buffer} body
- * @returns {Buffer}
- */
-function box(type, body) {
-  const head = Buffer.alloc(8);
-  head.writeUInt32BE(8 + body.length, 0);
-  head.write(type, 4, "latin1");
-  return Buffer.concat([head, body]);
-}
-
-/**
- * `elst` holding one empty edit — how the `segment` muxer records where the
- * piece sits on the source timeline.
- *
- * @param {number} offsetSeconds
- * @returns {Buffer}
- */
-function emptyEdit(offsetSeconds) {
-  const body = Buffer.alloc(16);
-  body.writeUInt32BE(1, 4);                                        // entry count
-  body.writeUInt32BE(Math.round(offsetSeconds * MOVIE_TIMESCALE), 8); // duration
-  body.writeInt32BE(-1, 12);                                       // media_time
-  return box("elst", body);
-}
-
-/**
- * @param {number} trackId
- * @param {number} timescale
- * @param {number} offsetSeconds
- * @returns {Buffer}
- */
-function trak(trackId, timescale, offsetSeconds) {
-  const tkhdBody = Buffer.alloc(84);
-  tkhdBody.writeUInt32BE(trackId, 12);
-  const mdhdBody = Buffer.alloc(20);
-  mdhdBody.writeUInt32BE(timescale, 12);
-  return box("trak", Buffer.concat([
-    box("tkhd", tkhdBody),
-    box("edts", emptyEdit(offsetSeconds)),
-    box("mdia", box("mdhd", mdhdBody))
-  ]));
-}
-
-/**
- * @param {number} trackId
- * @returns {Buffer}
- */
-function traf(trackId) {
-  const tfhdBody = Buffer.alloc(8);
-  tfhdBody.writeUInt32BE(trackId, 4);
-  const tfdtBody = Buffer.alloc(12);
-  tfdtBody.writeUInt8(1, 0);                       // version 1 — 64-bit
-  tfdtBody.writeBigUInt64BE(0n, 4);                // what ffmpeg writes: zero
-  return box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
-}
-
-/**
- * A piece shaped like the `segment` muxer's output: header, two fragments and a
- * trailing random-access index, all in one file.
- *
- * @param {number} offsetSeconds
- * @returns {Buffer}
- */
-function selfContainedPiece(offsetSeconds) {
-  const mvhdBody = Buffer.alloc(100);
-  mvhdBody.writeUInt32BE(MOVIE_TIMESCALE, 12);
-  const moov = box("moov", Buffer.concat([
-    box("mvhd", mvhdBody),
-    trak(1, VIDEO_TIMESCALE, offsetSeconds),
-    trak(2, AUDIO_TIMESCALE, offsetSeconds)
-  ]));
-  const moof = box("moof", Buffer.concat([traf(1), traf(2)]));
-  const mdat = box("mdat", Buffer.alloc(64, 0x5a));
-  const mfra = box("mfra", Buffer.alloc(24, 0));
-  return Buffer.concat([box("ftyp", Buffer.alloc(16, 0)), moov, moof, mdat, mfra]);
-}
-
-/**
- * A manager holding one session whose segments are already on disk, cut at
- * explicit times — the ordinary keyframe-cut path.
- *
- * @param {{ segmentFormat?: object, audioOnly?: boolean, withRun?: boolean }} [overrides]
- * @returns {Promise<{ manager: object, session: object, dirPath: string }>}
- */
-async function managerWithReadySegment(overrides = {}) {
-  const manager = wireOutputs({
-    enabled: true,
-    ffmpegBin: "ffmpeg",
-    localBindHost: "127.0.0.1",
-    localPort: 9090
-  });
-  // ADDRESSED THE WAY PRODUCTION ADDRESSES IT. A session's segments live in the
-  // store's directory for its OUTPUT, and whether one is finished is asked of
-  // the store by that same address. This fixture used to make a directory of its
-  // own and leave the session with no output address at all, so it described a
-  // proxy that no longer exists and asked for a segment the store had never
-  // heard of.
-  manager.segmentStore.useFormat(OUTPUT_KEY, overrides.segmentFormat ?? fmp4Format);
-  const dirPath = manager.segmentStore.directoryFor(OUTPUT_KEY);
-  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
-  // Two segments, because a piece is only finished once the next one exists.
-  await writeFile(path.join(dirPath, "segment-00000.mp4"), piece);
-  await writeFile(path.join(dirPath, "segment-00001.mp4"), piece);
-
-  const session = {
-    id: SESSION_ID,
-    spec: outputSpec({
-      transcodeVideo: overrides.transcodeVideo === true,
-      audioOnly: overrides.audioOnly === true,
-      cutGrid: "uniform"
-    }),
-    outputKey: OUTPUT_KEY,
-    dirPath,
-    // Where this file is cut, held by the file. A fixture that stated it
-    // on the session was describing what production no longer does.
-    // LONGER THAN WHAT IS ON DISK. Two segments exist; the film runs to five, so
-    // there is film left to make and an encoder on it is warranted. With the
-    // whole film already made, an encoder is not — the plan stops it, correctly,
-    // and a fixture that wants a live run has to give it something to do.
-    timeline: new Timeline({
-      boundaries: [0, SEGMENT_START_SECONDS, 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 }),
-    // An ordinary session reads its own file, and its sound is inside it. The
-    // three differ only for a soundtrack shipped as a file of its own.
-    get inputFile() { return this.file; },
-    get audioFile() { return this.file; },
-    // WHAT THIS HOST ENCODES AT. Every real host measures it before a viewer
-    // exists, and the plan compares arrivals — which cannot be computed without
-    // it. A fixture that leaves it out describes a machine that has never
-    // measured itself: every arrangement is then equally hopeless, they all tie,
-    // and the plan takes the encoder away for changing nothing.
-    lastAloneSpeed: 2,
-    startedAt: Date.now(),
-    lastAccessedAt: Date.now(),
-    runs: new Set(),
-    lastError: "",
-    consumers: new Set(),
-    // Who is watching this output, and how long it is. Without the first the
-    // output has no viewers to build a priority map from, so it states no zones
-    // at all — which reads as nobody watching and stops every encoder on it.
-    viewers: new Map(),
-    segmentCount: 5,
-    segmentFormat: overrides.segmentFormat ?? fmp4Format,
-    useSyntheticPlaylist: true,
-    playlistText: "#EXTM3U\n",
-    // WHAT IS BEING PRODUCED, which is also where a produced piece's landing is
-    // recorded. Per output, so one output's reading of a piece number cannot
-    // silence another output's reading of its own.
-    output: new Output({ encodeWidth: 0, encodeHeight: 0, outputFps: 25, softwarePreset: null, applyTonemap: false }),
-    // WHERE THIS FILE'S KEYFRAMES ARE, held by the file. A copied picture is cut
-    // at these and nowhere else, which is what makes its landing evidence about
-    // this table — and what makes a soundtrack's landing evidence about nothing
-    // of the sort.
-    keyframes: new KeyframeTable().learn({ times: [0, 12.5, 25, 37.5, 50], format: "matroska" }),
-    audioOnly: overrides.audioOnly === true,
-    waitEpoch: 0
-  };
-  // THE INIT IS THE STORE'S, and a player fetches it before any segment — so a
-  // fixture that wants segments served as production serves them has to put it
-  // there first. It used to sit on the session, which nothing reads any more:
-  // `prepareSegmentBytes` has no timescales without it and hands the piece back
-  // unstamped, which is silent and is exactly the fault stamping exists to
-  // prevent.
-  manager.segmentStore.keepInit(OUTPUT_KEY, fmp4Format.extractInit(piece));
-  manager.outputs.set(SESSION_ID, session);
-  // SOMEBODY IS WATCHING IT. A segment is requested by a viewer, so a fixture
-  // that asks for one without stating a viewer describes a state production
-  // never reaches — and an output nobody is watching has every encoder on it
-  // stopped, which is right and is what left the run here reading STOPPED.
-  // NO PLAN RUNS HERE. This file is about the path that answers a request for a
-  // segment. Deciding how many encoders there should be and where is a separate
-  // question with its own checks, and letting it run inside these would spawn
-  // real ffmpeg processes and replace the very run each test is watching — the
-  // test would then be about the plan, and about it at its least stable.
-  manager.encodeRuns.planEncodersNow = () => {};
-  manager.encodeRuns.planEncodersSoon = () => {};
-  // The run in force. The fixture's segments live directly in the session
-  // directory, which is exactly what one run's directory is here.
-  if (overrides.withRun !== false) {
-    const run = startRunOn(session, { from: 0, usesExplicitCuts: true, speedX: 2 });
-    manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
-  }
-  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.lifecycle.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
-  // grid for every output forever, which is worse than no measurement.
-  assert.equal(session.output.landing, null, "nothing has been produced yet");
-
-  await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(session.output.landing.checked, 1, "the piece that was just produced must have been examined");
-});
-
-test("only a copied picture's landing is taken as evidence about the file's keyframe table", async (t) => {
-  // The one reading, sent to the two owners the manager decides between. A
-  // soundtrack is cut exactly where it is asked to be and has no keyframes, so
-  // its landing is about its own output and about nothing else; sent to the
-  // file's table it would report the file's index wrong on the strength of a
-  // stream that never consulted it.
-  const sound = await managerWithReadySegment({ audioOnly: true });
-  t.after(async () => {
-    await sound.manager.lifecycle.disposeAll();
-    await rm(sound.dirPath, { recursive: true, force: true });
-  });
-
-  await sound.manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(sound.session.output.landing.checked, 1, "the sound's own landing is recorded");
-  assert.equal(
-    sound.session.keyframes.evidence,
-    null,
-    "and nothing it produced is evidence about where the file's keyframes are"
-  );
-
-  const picture = await managerWithReadySegment();
-  t.after(async () => {
-    await picture.manager.lifecycle.disposeAll();
-    await rm(picture.dirPath, { recursive: true, force: true });
-  });
-
-  await picture.manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(picture.session.keyframes.evidence.checked, 1, "a copy's landing does reach the file's table");
-});
-
-test("a segment that exists is served, not reported as still being produced", async (t) => {
-  const { manager, dirPath, session } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-
-  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(result.kind, "file", "a finished segment on disk must come back as bytes");
-  assert.equal(result.contentType, fmp4Format.segmentContentType);
-
-  const chunks = [];
-  for await (const chunk of result.stream) {
-    chunks.push(chunk);
-  }
-  const served = Buffer.concat(chunks);
-  assert.equal(served.toString("latin1", 4, 8), "moof", "the init header must be stripped off a media segment");
-
-  // The piece's OWN start, carried into the fragment it belongs to. Two
-  // releases tried moving it toward the playlist instead (2.24.1 per session,
-  // 2.25.0 by one family offset) and both desynced picture from sound in the
-  // field the same day: the first segment of a run is not cut, it begins where
-  // the seek landed, and the picture must land on a keyframe while the sound
-  // need not. Reading the piece's position is also the step that threw in
-  // 2.9.124, and it still feeds the index tally and the grid correction.
-  assert.equal(
-    Number(served.readBigUInt64BE(served.indexOf("tfdt") + 8)),
-    Math.round(SEGMENT_START_SECONDS * VIDEO_TIMESCALE),
-    "the segment must be stamped with where it really begins"
-  );
-  assert.equal(
-    session.output.landing.checked,
-    1,
-    "and the piece's own position must still have been read, or nothing measures the landing"
-  );
-});
-
-test("a fault while preparing an existing segment is named, not turned into a wait", async (t) => {
-  const broken = {
-    ...fmp4Format,
-    readSegmentStartSeconds() {
-      throw new ReferenceError("readSelfContainedStartSeconds is not defined");
-    }
-  };
-  const { manager, dirPath } = await managerWithReadySegment({ segmentFormat: broken });
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-
-  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(
-    result.kind,
-    "failed",
-    "answering 'warming-up' hides the fault and holds every request until the viewer gives up"
-  );
-  assert.match(result.message, /readSelfContainedStartSeconds is not defined/);
-});
-
-test("a run's FIRST segment is served once the encoder has passed it, without waiting for a next one", async (t) => {
-  const { manager, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // The shape a resume takes: a run begun mid-file, so its first segment has no
-  // successor and nothing is producing one. Waiting for that successor is what
-  // held #317 for 46 s and then answered 404 to a browser that had given up.
-  await rm(path.join(dirPath, "segment-00001.mp4"));
-  // WHAT PROVES IT INSTEAD: its own NAME. A piece is called something else while
-  // it is being written and takes its served name when its writer says it is
-  // closed, so a run's first piece is proven the moment it is finished and the
-  // absence of a next one says nothing. This used to be inferred from the
-  // encoder's reported position — a different question, where it has read to
-  // rather than what it has closed.
-
-  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(
-    result.kind,
-    "file",
-    "the encoder is past this segment's end, so it is finished — the absence of a next one says nothing"
-  );
-});
-
-test("a segment an earlier run made is served by whatever run is going now", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // Every run of an output writes into that output's own directory — there is
-  // one, and runs are kept apart by their stretches instead. So a viewer who
-  // seeks back is served what an earlier run made, with no restart and no
-  // search: the run going now began at #40 and #0 is simply there.
-  const run = startRunOn(session, { from: 40, usesExplicitCuts: true });
-  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
-
-  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.equal(result.kind, "file", "what any run of this output made is what this output holds");
-  const chunks = [];
-  for await (const chunk of result.stream) {
-    chunks.push(chunk);
-  }
-  assert.ok(Buffer.concat(chunks).length > 0);
-});
-
-test("serving a run's own segment moves the run out of STARTING", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment({ withRun: false });
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // The table lives in `encode/encode-run-state.js` and is tested there as a graph.
-  // What this pins is that a real serve REACHES it: a state nothing writes
-  // describes every run as still starting, for ever, and the log built on it
-  // would say so too.
-  // A run that has not yet made anything: starting. The fixture's own run is
-  // let go first, because this test is about ONE run and what serving does to
-  // it.
-  // ITS OWN PIECE, AND FILM STILL TO MAKE BEHIND IT. A run standing on material
-  // that already exists is moved forward — correctly — so a fixture that wants a
-  // live run has to put it where the work is. #1 is what it is making; #2..#4
-  // are unmade, so it is wanted; and #1 stands under its served name, which is
-  // what makes the piece servable at all.
-  const run = startRunOn(session, { from: 1, producing: false, usesExplicitCuts: true, speedX: 2 });
-  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
-  assert.equal(run.state, ENCODE_RUN_STATE.STARTING);
-  assert.deepEqual(run.produced, [], "it has made nothing yet");
-
-  await manager.serving.getFileStream(SESSION_ID, "segment-00001.mp4");
-
-  // ASKED OF WHAT THE SERVE WROTE, not of the state that happens to follow it.
-  // The plan owns a run's life and may end it in the same turn for reasons of
-  // its own — the machine's budget, a viewer leaving, nothing left to make —
-  // and a check that reads the state afterwards is really asking what the plan
-  // decided. What the SERVE does is tell the run the piece is finished, and that
-  // is what moves it out of starting.
-  assert.deepEqual(run.produced, [1], "the serve told the run its piece is finished");
-  assert.equal(run.head, 2, "so the run stands one past it");
-});
-
-test("a segment behind a run's own start does not claim that run has produced", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment({ withRun: false });
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // What moves a run out of starting is ITS OWN first segment. An earlier run's
-  // output sits in the same directory, and after a backward seek some of it
-  // lies ahead of the new run's beginning — so the question cannot be asked of
-  // the number alone, and a run believed to be producing is one the look-ahead
-  // may suspend and the seek path may wave through as "already covered".
-  const run = startRunOn(session, { from: 5, producing: false, usesExplicitCuts: true, speedX: 2 });
-  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
-
-  await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
-
-  assert.deepEqual(run.produced, [], "#0 is somebody else's work and says nothing about this run");
-  assert.equal(run.head, 5, "which is still where it began");
-});
-
-test("a request behind the run that nobody is coming for is answered absent, not held", async (t) => {
-  // A HOLD IS ONLY RIGHT WHILE SOMETHING IS COMING. Field 2026-08-15: hls.js
-  // asked a freshly prepared track for segment #0 while the run stood at #354,
-  // the request was held for the whole minute, and only when it failed did the
-  // player ask for the segment it actually needed — 63 s of spinner after a
-  // track that had been ready in 7. Answered absent, the player moves on at
-  // once.
-  //
-  // Whether anybody is coming is the encoding's answer, from the map it was
-  // given. An EMPTY map is not that answer: a session created a moment ago has
-  // no map yet, and read as "nobody is coming" every request behind the run
-  // would be refused for as long as that lasted.
-  const { manager, session, dirPath } = await managerWithReadySegment({ withRun: false });
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  const run = startRunOn(session, { from: 3, producing: true, usesExplicitCuts: true, speedX: 2 });
-  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
-
-  // No map yet: the request is HELD, because nothing has said otherwise.
-  const held = await manager.serving.getFileStream(SESSION_ID, "segment-00002.mp4");
-  assert.notEqual(held.kind, "not-found", "a session with no map waits, it does not refuse");
-
-  // Now the map says where the viewers are, and #2 is not in it.
-  manager.encodeOrchestrator.notePriorityMap(OUTPUT_KEY, [
-    { from: 3, to: 4, priority: 100, withinSeconds: 0 }
-  ]);
-  const refused = await manager.serving.getFileStream(SESSION_ID, "segment-00002.mp4");
-
-  assert.equal(refused.kind, "not-found");
-});
+/**
+ * @file A finished segment on disk must reach the viewer as bytes.
+ *
+ * The module tests cover each piece of the fMP4 path on its own, and every one
+ * of them passed while playback was dead: 2.9.124 called
+ * `readSelfContainedStartSeconds` from `fmp4.js` without importing it, and the
+ * unit test imports that function straight from `mp4-boxes.js`, so the gap
+ * between a module and its CALLER was invisible. This test asks the session
+ * manager for a segment that exists and insists on getting it.
+ *
+ * The second half pins the reason a one-word slip cost a whole release: the
+ * failure was reported as "still being produced". Measured 2026-08-08 — segment
+ * #0 was held for 45 281 ms with twelve finished segments in the directory, and
+ * the log said nothing at all. Anything that goes wrong while preparing a file
+ * that EXISTS must be named and answered, never turned into an endless wait.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+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 { rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { wireOutputs } from "../services/server/wire-outputs.js";
+import { ENCODE_RUN_STATE } from "../services/encode/encode-run-state.js";
+import { startRunOn } from "./helpers/encode-run.js";
+import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
+import { outputSpec } from "./helpers/output-spec.js";
+
+const MOVIE_TIMESCALE = 1000;
+const VIDEO_TIMESCALE = 90_000;
+const AUDIO_TIMESCALE = 48_000;
+const SEGMENT_START_SECONDS = 12.5;
+const SESSION_ID = "1111111122223333";
+// Its own address, so this file's directory in the shared store is nobody
+// else's.
+const OUTPUT_KEY = "serve-wiring:fmt=fmp4:grid=uniform:video-only:v=0/copy";
+
+/**
+ * @param {string} type
+ * @param {Buffer} body
+ * @returns {Buffer}
+ */
+function box(type, body) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(8 + body.length, 0);
+  head.write(type, 4, "latin1");
+  return Buffer.concat([head, body]);
+}
+
+/**
+ * `elst` holding one empty edit — how the `segment` muxer records where the
+ * piece sits on the source timeline.
+ *
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function emptyEdit(offsetSeconds) {
+  const body = Buffer.alloc(16);
+  body.writeUInt32BE(1, 4);                                        // entry count
+  body.writeUInt32BE(Math.round(offsetSeconds * MOVIE_TIMESCALE), 8); // duration
+  body.writeInt32BE(-1, 12);                                       // media_time
+  return box("elst", body);
+}
+
+/**
+ * @param {number} trackId
+ * @param {number} timescale
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function trak(trackId, timescale, offsetSeconds) {
+  const tkhdBody = Buffer.alloc(84);
+  tkhdBody.writeUInt32BE(trackId, 12);
+  const mdhdBody = Buffer.alloc(20);
+  mdhdBody.writeUInt32BE(timescale, 12);
+  return box("trak", Buffer.concat([
+    box("tkhd", tkhdBody),
+    box("edts", emptyEdit(offsetSeconds)),
+    box("mdia", box("mdhd", mdhdBody))
+  ]));
+}
+
+/**
+ * @param {number} trackId
+ * @returns {Buffer}
+ */
+function traf(trackId) {
+  const tfhdBody = Buffer.alloc(8);
+  tfhdBody.writeUInt32BE(trackId, 4);
+  const tfdtBody = Buffer.alloc(12);
+  tfdtBody.writeUInt8(1, 0);                       // version 1 — 64-bit
+  tfdtBody.writeBigUInt64BE(0n, 4);                // what ffmpeg writes: zero
+  return box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
+}
+
+/**
+ * A piece shaped like the `segment` muxer's output: header, two fragments and a
+ * trailing random-access index, all in one file.
+ *
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function selfContainedPiece(offsetSeconds) {
+  const mvhdBody = Buffer.alloc(100);
+  mvhdBody.writeUInt32BE(MOVIE_TIMESCALE, 12);
+  const moov = box("moov", Buffer.concat([
+    box("mvhd", mvhdBody),
+    trak(1, VIDEO_TIMESCALE, offsetSeconds),
+    trak(2, AUDIO_TIMESCALE, offsetSeconds)
+  ]));
+  const moof = box("moof", Buffer.concat([traf(1), traf(2)]));
+  const mdat = box("mdat", Buffer.alloc(64, 0x5a));
+  const mfra = box("mfra", Buffer.alloc(24, 0));
+  return Buffer.concat([box("ftyp", Buffer.alloc(16, 0)), moov, moof, mdat, mfra]);
+}
+
+/**
+ * A manager holding one session whose segments are already on disk, cut at
+ * explicit times — the ordinary keyframe-cut path.
+ *
+ * @param {{ segmentFormat?: object, audioOnly?: boolean, withRun?: boolean }} [overrides]
+ * @returns {Promise<{ manager: object, session: object, dirPath: string }>}
+ */
+async function managerWithReadySegment(overrides = {}) {
+  const manager = wireOutputs({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  // ADDRESSED THE WAY PRODUCTION ADDRESSES IT. A session's segments live in the
+  // store's directory for its OUTPUT, and whether one is finished is asked of
+  // the store by that same address. This fixture used to make a directory of its
+  // own and leave the session with no output address at all, so it described a
+  // proxy that no longer exists and asked for a segment the store had never
+  // heard of.
+  manager.segmentStore.useFormat(OUTPUT_KEY, overrides.segmentFormat ?? fmp4Format);
+  const dirPath = manager.segmentStore.directoryFor(OUTPUT_KEY);
+  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
+  // Two segments, because a piece is only finished once the next one exists.
+  await writeFile(path.join(dirPath, "segment-00000.mp4"), piece);
+  await writeFile(path.join(dirPath, "segment-00001.mp4"), piece);
+
+  const session = {
+    id: SESSION_ID,
+    spec: outputSpec({
+      transcodeVideo: overrides.transcodeVideo === true,
+      audioOnly: overrides.audioOnly === true,
+      cutGrid: "uniform"
+    }),
+    outputKey: OUTPUT_KEY,
+    dirPath,
+    // Where this file is cut, held by the file. A fixture that stated it
+    // on the session was describing what production no longer does.
+    // LONGER THAN WHAT IS ON DISK. Two segments exist; the film runs to five, so
+    // there is film left to make and an encoder on it is warranted. With the
+    // whole film already made, an encoder is not — the plan stops it, correctly,
+    // and a fixture that wants a live run has to give it something to do.
+    timeline: new Timeline({
+      boundaries: [0, SEGMENT_START_SECONDS, 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 }),
+    // An ordinary session reads its own file, and its sound is inside it. The
+    // three differ only for a soundtrack shipped as a file of its own.
+    get inputFile() { return this.file; },
+    get audioFile() { return this.file; },
+    // WHAT THIS HOST ENCODES AT. Every real host measures it before a viewer
+    // exists, and the plan compares arrivals — which cannot be computed without
+    // it. A fixture that leaves it out describes a machine that has never
+    // measured itself: every arrangement is then equally hopeless, they all tie,
+    // and the plan takes the encoder away for changing nothing.
+    lastAloneSpeed: 2,
+    startedAt: Date.now(),
+    lastAccessedAt: Date.now(),
+    runs: new Set(),
+    lastError: "",
+    consumers: new Set(),
+    // Who is watching this output, and how long it is. Without the first the
+    // output has no viewers to build a priority map from, so it states no zones
+    // at all — which reads as nobody watching and stops every encoder on it.
+    viewers: new Map(),
+    segmentCount: 5,
+    segmentFormat: overrides.segmentFormat ?? fmp4Format,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    // WHAT IS BEING PRODUCED, which is also where a produced piece's landing is
+    // recorded. Per output, so one output's reading of a piece number cannot
+    // silence another output's reading of its own.
+    output: new Output({ encodeWidth: 0, encodeHeight: 0, outputFps: 25, softwarePreset: null, applyTonemap: false }),
+    // WHERE THIS FILE'S KEYFRAMES ARE, held by the file. A copied picture is cut
+    // at these and nowhere else, which is what makes its landing evidence about
+    // this table — and what makes a soundtrack's landing evidence about nothing
+    // of the sort.
+    keyframes: new KeyframeTable().learn({ times: [0, 12.5, 25, 37.5, 50], format: "matroska" }),
+    audioOnly: overrides.audioOnly === true,
+    waitEpoch: 0
+  };
+  // THE INIT IS THE STORE'S, and a player fetches it before any segment — so a
+  // fixture that wants segments served as production serves them has to put it
+  // there first. It used to sit on the session, which nothing reads any more:
+  // `prepareSegmentBytes` has no timescales without it and hands the piece back
+  // unstamped, which is silent and is exactly the fault stamping exists to
+  // prevent.
+  manager.segmentStore.keepInit(OUTPUT_KEY, fmp4Format.extractInit(piece));
+  manager.outputs.set(SESSION_ID, session);
+  // SOMEBODY IS WATCHING IT. A segment is requested by a viewer, so a fixture
+  // that asks for one without stating a viewer describes a state production
+  // never reaches — and an output nobody is watching has every encoder on it
+  // stopped, which is right and is what left the run here reading STOPPED.
+  // NO PLAN RUNS HERE. This file is about the path that answers a request for a
+  // segment. Deciding how many encoders there should be and where is a separate
+  // question with its own checks, and letting it run inside these would spawn
+  // real ffmpeg processes and replace the very run each test is watching — the
+  // test would then be about the plan, and about it at its least stable.
+  manager.encodeRuns.planEncodersNow = () => {};
+  manager.encodeRuns.planEncodersSoon = () => {};
+  // The run in force. The fixture's segments live directly in the session
+  // directory, which is exactly what one run's directory is here.
+  if (overrides.withRun !== false) {
+    const run = startRunOn(session, { from: 0, usesExplicitCuts: true, speedX: 2 });
+    manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
+  }
+  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.lifecycle.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
+  // grid for every output forever, which is worse than no measurement.
+  assert.equal(session.output.landing, null, "nothing has been produced yet");
+
+  await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(session.output.landing.checked, 1, "the piece that was just produced must have been examined");
+});
+
+test("only a copied picture's landing is taken as evidence about the file's keyframe table", async (t) => {
+  // The one reading, sent to the two owners the manager decides between. A
+  // soundtrack is cut exactly where it is asked to be and has no keyframes, so
+  // its landing is about its own output and about nothing else; sent to the
+  // file's table it would report the file's index wrong on the strength of a
+  // stream that never consulted it.
+  const sound = await managerWithReadySegment({ audioOnly: true });
+  t.after(async () => {
+    await sound.manager.lifecycle.disposeAll();
+    await rm(sound.dirPath, { recursive: true, force: true });
+  });
+
+  await sound.manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(sound.session.output.landing.checked, 1, "the sound's own landing is recorded");
+  assert.equal(
+    sound.session.keyframes.evidence,
+    null,
+    "and nothing it produced is evidence about where the file's keyframes are"
+  );
+
+  const picture = await managerWithReadySegment();
+  t.after(async () => {
+    await picture.manager.lifecycle.disposeAll();
+    await rm(picture.dirPath, { recursive: true, force: true });
+  });
+
+  await picture.manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(picture.session.keyframes.evidence.checked, 1, "a copy's landing does reach the file's table");
+});
+
+test("a segment that exists is served, not reported as still being produced", async (t) => {
+  const { manager, dirPath, session } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(result.kind, "file", "a finished segment on disk must come back as bytes");
+  assert.equal(result.contentType, fmp4Format.segmentContentType);
+
+  const chunks = [];
+  for await (const chunk of result.stream) {
+    chunks.push(chunk);
+  }
+  const served = Buffer.concat(chunks);
+  assert.equal(served.toString("latin1", 4, 8), "moof", "the init header must be stripped off a media segment");
+
+  // The piece's OWN start, carried into the fragment it belongs to. Two
+  // releases tried moving it toward the playlist instead (2.24.1 per session,
+  // 2.25.0 by one family offset) and both desynced picture from sound in the
+  // field the same day: the first segment of a run is not cut, it begins where
+  // the seek landed, and the picture must land on a keyframe while the sound
+  // need not. Reading the piece's position is also the step that threw in
+  // 2.9.124, and it still feeds the index tally and the grid correction.
+  assert.equal(
+    Number(served.readBigUInt64BE(served.indexOf("tfdt") + 8)),
+    Math.round(SEGMENT_START_SECONDS * VIDEO_TIMESCALE),
+    "the segment must be stamped with where it really begins"
+  );
+  assert.equal(
+    session.output.landing.checked,
+    1,
+    "and the piece's own position must still have been read, or nothing measures the landing"
+  );
+});
+
+test("a fault while preparing an existing segment is named, not turned into a wait", async (t) => {
+  const broken = {
+    ...fmp4Format,
+    readSegmentStartSeconds() {
+      throw new ReferenceError("readSelfContainedStartSeconds is not defined");
+    }
+  };
+  const { manager, dirPath } = await managerWithReadySegment({ segmentFormat: broken });
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(
+    result.kind,
+    "failed",
+    "answering 'warming-up' hides the fault and holds every request until the viewer gives up"
+  );
+  assert.match(result.message, /readSelfContainedStartSeconds is not defined/);
+});
+
+test("a run's FIRST segment is served once the encoder has passed it, without waiting for a next one", async (t) => {
+  const { manager, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The shape a resume takes: a run begun mid-file, so its first segment has no
+  // successor and nothing is producing one. Waiting for that successor is what
+  // held #317 for 46 s and then answered 404 to a browser that had given up.
+  await rm(path.join(dirPath, "segment-00001.mp4"));
+  // WHAT PROVES IT INSTEAD: its own NAME. A piece is called something else while
+  // it is being written and takes its served name when its writer says it is
+  // closed, so a run's first piece is proven the moment it is finished and the
+  // absence of a next one says nothing. This used to be inferred from the
+  // encoder's reported position — a different question, where it has read to
+  // rather than what it has closed.
+
+  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(
+    result.kind,
+    "file",
+    "the encoder is past this segment's end, so it is finished — the absence of a next one says nothing"
+  );
+});
+
+test("a segment an earlier run made is served by whatever run is going now", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // Every run of an output writes into that output's own directory — there is
+  // one, and runs are kept apart by their stretches instead. So a viewer who
+  // seeks back is served what an earlier run made, with no restart and no
+  // search: the run going now began at #40 and #0 is simply there.
+  const run = startRunOn(session, { from: 40, usesExplicitCuts: true });
+  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
+
+  const result = await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.equal(result.kind, "file", "what any run of this output made is what this output holds");
+  const chunks = [];
+  for await (const chunk of result.stream) {
+    chunks.push(chunk);
+  }
+  assert.ok(Buffer.concat(chunks).length > 0);
+});
+
+test("serving a run's own segment moves the run out of STARTING", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment({ withRun: false });
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The table lives in `encode/encode-run-state.js` and is tested there as a graph.
+  // What this pins is that a real serve REACHES it: a state nothing writes
+  // describes every run as still starting, for ever, and the log built on it
+  // would say so too.
+  // A run that has not yet made anything: starting. The fixture's own run is
+  // let go first, because this test is about ONE run and what serving does to
+  // it.
+  // ITS OWN PIECE, AND FILM STILL TO MAKE BEHIND IT. A run standing on material
+  // that already exists is moved forward — correctly — so a fixture that wants a
+  // live run has to put it where the work is. #1 is what it is making; #2..#4
+  // are unmade, so it is wanted; and #1 stands under its served name, which is
+  // what makes the piece servable at all.
+  const run = startRunOn(session, { from: 1, producing: false, usesExplicitCuts: true, speedX: 2 });
+  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
+  assert.equal(run.state, ENCODE_RUN_STATE.STARTING);
+  assert.deepEqual(run.produced, [], "it has made nothing yet");
+
+  await manager.serving.getFileStream(SESSION_ID, "segment-00001.mp4");
+
+  // ASKED OF WHAT THE SERVE WROTE, not of the state that happens to follow it.
+  // The plan owns a run's life and may end it in the same turn for reasons of
+  // its own — the machine's budget, a viewer leaving, nothing left to make —
+  // and a check that reads the state afterwards is really asking what the plan
+  // decided. What the SERVE does is tell the run the piece is finished, and that
+  // is what moves it out of starting.
+  assert.deepEqual(run.produced, [1], "the serve told the run its piece is finished");
+  assert.equal(run.head, 2, "so the run stands one past it");
+});
+
+test("a segment behind a run's own start does not claim that run has produced", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment({ withRun: false });
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // What moves a run out of starting is ITS OWN first segment. An earlier run's
+  // output sits in the same directory, and after a backward seek some of it
+  // lies ahead of the new run's beginning — so the question cannot be asked of
+  // the number alone, and a run believed to be producing is one the look-ahead
+  // may suspend and the seek path may wave through as "already covered".
+  const run = startRunOn(session, { from: 5, producing: false, usesExplicitCuts: true, speedX: 2 });
+  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
+
+  await manager.serving.getFileStream(SESSION_ID, "segment-00000.mp4");
+
+  assert.deepEqual(run.produced, [], "#0 is somebody else's work and says nothing about this run");
+  assert.equal(run.head, 5, "which is still where it began");
+});
+
+test("a request behind the run that nobody is coming for is answered absent, not held", async (t) => {
+  // A HOLD IS ONLY RIGHT WHILE SOMETHING IS COMING. Field 2026-08-15: hls.js
+  // asked a freshly prepared track for segment #0 while the run stood at #354,
+  // the request was held for the whole minute, and only when it failed did the
+  // player ask for the segment it actually needed — 63 s of spinner after a
+  // track that had been ready in 7. Answered absent, the player moves on at
+  // once.
+  //
+  // Whether anybody is coming is the encoding's answer, from the map it was
+  // given. An EMPTY map is not that answer: a session created a moment ago has
+  // no map yet, and read as "nobody is coming" every request behind the run
+  // would be refused for as long as that lasted.
+  const { manager, session, dirPath } = await managerWithReadySegment({ withRun: false });
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const run = startRunOn(session, { from: 3, producing: true, usesExplicitCuts: true, speedX: 2 });
+  manager.encodeOrchestrator.adopt(OUTPUT_KEY, run);
+
+  // No map yet: the request is HELD, because nothing has said otherwise.
+  const held = await manager.serving.getFileStream(SESSION_ID, "segment-00002.mp4");
+  assert.notEqual(held.kind, "not-found", "a session with no map waits, it does not refuse");
+
+  // Now the map says where the viewers are, and #2 is not in it.
+  manager.encodeOrchestrator.notePriorityMap(OUTPUT_KEY, [
+    { from: 3, to: 4, priority: 100, withinSeconds: 0 }
+  ]);
+  const refused = await manager.serving.getFileStream(SESSION_ID, "segment-00002.mp4");
+
+  assert.equal(refused.kind, "not-found");
+});