@torrent-tv/proxy 2.75.0 → 2.76.1

package/test/run-graph-drift.test.js

@@ -1,7 +1,7 @@
 /**
  * @file The drawing cannot disagree with the table.
  *
- * `docs/encode-run-state.md` is generated from `services/encode-run-state.js`.
+ * `docs/encode-run-state.md` is generated from `services/encode/encode-run-state.js`.
  * A picture kept beside the code drifts — this repository has the receipts —
  * so the check is mechanical: regenerate it and compare. A behavioural change
  * to the table that forgets `npm run graph` fails here, in the same commit.

package/test/run-intervals.test.js

@@ -0,0 +1,329 @@
+/**
+ * @file A run is given a stretch nobody else holds, and stops at the end of it.
+ *
+ * This is what removes the per-run directories. Runs used to be kept apart by a
+ * directory each, because two of them writing one segment name at the same time
+ * produce a file belonging to neither — which was also the only reason a restart
+ * ever had to wait for its predecessor to die. Intervals remove that by
+ * construction, so one flat directory per output is correct.
+ *
+ * The other half is the argument that states the end, and WHICH argument it is
+ * belongs to the branch — measured, not reasoned:
+ * `research/encoder-layer-2026-09-04.md` §11.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SourceFile } from "../services/source/SourceFile.js";
+import { startRunOn } from "./helpers/encode-run.js";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { SegmentStore } from "../services/encode/SegmentStore.js";
+import { Timeline } from "../services/output/Timeline.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+import { viewerOf } from "../services/viewer/Viewer.js";
+
+const KEY = "torrent:abc:fmt=fmp4:grid=kf@0:video-only:v=0/copy";
+
+/**
+ * @returns {{ manager: HlsSessionManager, store: SegmentStore, root: string, dirPath: string }}
+ */
+function managerWithAnEmptyOutput() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "run-intervals-"));
+  const store = new SegmentStore({ root });
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090,
+    segmentStore: store
+  });
+  const dirPath = store.directoryFor(KEY);
+  store.useFormat(KEY, fmp4Format);
+  return { manager, store, root, dirPath };
+}
+
+/**
+ * @param {object} params
+ * @returns {object}
+ */
+function sessionOn({ id, dirPath, segmentCount = 100, runState = null, encodeStartIndex = 0, runEndIndex = -1 }) {
+  const session = {
+    id,
+    outputKey: KEY,
+    dirPath,
+    state: "ready",
+    file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "video.mkv" }),
+    // 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; },
+    segmentFormat: fmp4Format,
+    segmentCount,
+    runs: new Set(),
+    consumers: new Set(),
+    lastAccessedAt: Date.now()
+  };
+  if (runState !== null) {
+    const run = startRunOn(session, { from: encodeStartIndex, to: runEndIndex });
+    if (runState === "ENDED_FAILED") {
+      // A run that failed, said so, and left what it had made behind.
+      run.process?.exit(255, null);
+    }
+  }
+  return session;
+}
+
+/**
+ * @param {string} dirPath
+ * @param {number[]} indexes
+ */
+function alreadyMade(dirPath, indexes) {
+  for (const index of indexes) {
+    writeFileSync(path.join(dirPath, fmp4Format.segmentFileName(index)), Buffer.alloc(16, 1));
+  }
+}
+
+test("with nothing made, a run gets everything from where it was asked", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const session = sessionOn({ id: "s", dirPath });
+  // -1 for the end means "to the end of the film", which is what every run had
+  // before ends existed — and the only case where that is still right.
+  assert.deepEqual(manager.planRunInterval(session, 0), { from: 0, to: -1 });
+});
+
+test("a run stops before material that is already made", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  // 10..20 on the disk. Only 10..19 are PROVEN — the highest has no successor,
+  // so nothing shows whether it was closed or was being written when its run
+  // died.
+  alreadyMade(dirPath, [10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]);
+  const session = sessionOn({ id: "s", dirPath });
+
+  assert.deepEqual(manager.planRunInterval(session, 0), { from: 0, to: 9 });
+});
+
+test("a run asked to start inside made material is moved forward to the gap", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  alreadyMade(dirPath, [10, 11, 12, 13, 14, 15]);
+  const session = sessionOn({ id: "s", dirPath });
+
+  // Asked for 11, which is made, and so is everything to 14. The first thing
+  // worth encoding is 15 — unproven, because 16 does not exist.
+  assert.deepEqual(manager.planRunInterval(session, 11), { from: 15, to: -1 });
+});
+
+test("a run stops before a stretch another live run was given", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const other = sessionOn({
+    id: "other",
+    dirPath,
+    runState: "PRODUCING",
+    encodeStartIndex: 40,
+    runEndIndex: 60
+  });
+  manager.sessionsById.set(other.id, other);
+  const session = sessionOn({ id: "s", dirPath });
+
+  // Two viewers of one film, one already encoding 40..60. The second run takes
+  // what is free in front of it and stops where the other one begins, so
+  // neither ever writes a name the other wants.
+  assert.deepEqual(manager.planRunInterval(session, 0), { from: 0, to: 39 });
+  assert.deepEqual(manager.planRunInterval(session, 45), { from: 61, to: -1 });
+});
+
+test("a run that has died holds nothing back", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  // The same stretch, but the process cannot be signalled — it has ended. What
+  // it did not finish is free again, without anything having to release it.
+  const dead = sessionOn({
+    id: "dead",
+    dirPath,
+    runState: "ENDED_FAILED",
+    encodeStartIndex: 40,
+    runEndIndex: 60
+  });
+  manager.sessionsById.set(dead.id, dead);
+  const session = sessionOn({ id: "s", dirPath });
+
+  assert.deepEqual(manager.planRunInterval(session, 0), { from: 0, to: -1 });
+});
+
+test("nothing left to make is answered with nothing, not with a run", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const session = sessionOn({ id: "s", dirPath, segmentCount: 5 });
+  alreadyMade(dirPath, [0, 1, 2, 3, 4]);
+  const other = sessionOn({
+    id: "other",
+    dirPath,
+    segmentCount: 5,
+    runState: "PRODUCING",
+    encodeStartIndex: 4,
+    runEndIndex: 4
+  });
+  manager.sessionsById.set(other.id, other);
+
+  // Starting an encoder here would only repeat somebody else's work, which is
+  // what three ffmpeg processes making one identical picture cost on a CM4.
+  assert.equal(manager.planRunInterval(session, 0), null);
+});
+
+test("a session with no address keeps the old shape: start here, no end", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const session = sessionOn({ id: "s", dirPath });
+  session.outputKey = "";
+
+  assert.deepEqual(manager.planRunInterval(session, 7), { from: 7, to: -1 });
+});
+
+test("a run without an end does not claim the whole film away from a later viewer", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  // The first viewer's run, at the beginning, with no end — which is every run
+  // whose output was empty when it started.
+  const first = sessionOn({
+    id: "first",
+    dirPath,
+    segmentCount: 1000,
+    runState: "PRODUCING",
+    encodeStartIndex: 0,
+    runEndIndex: -1
+  });
+  manager.sessionsById.set(first.id, first);
+  const second = sessionOn({ id: "second", dirPath, segmentCount: 1000 });
+
+  // A second viewer opens the same film in the middle. Counting the first run's
+  // claim as the whole film would leave them with no encoder at all, waiting for
+  // it to encode its way there — an hour on a long film. It only claims as far
+  // as it will actually get, which is its head plus the look-ahead.
+  const planned = manager.planRunInterval(second, 500);
+  assert.notEqual(planned, null);
+  assert.equal(planned.from, 500);
+});
+
+test("a run stops when it reaches a stretch another run was given", async (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const stopped = [];
+  const ahead = sessionOn({
+    id: "ahead",
+    dirPath,
+    runState: "PRODUCING",
+    encodeStartIndex: 500,
+    runEndIndex: 600
+  });
+  manager.sessionsById.set(ahead.id, ahead);
+  const behind = sessionOn({
+    id: "behind",
+    dirPath,
+    runState: "PRODUCING",
+    encodeStartIndex: 0,
+    runEndIndex: -1
+  });
+  manager.sessionsById.set(behind.id, behind);
+
+  // Its own end was set from the gaps of the moment it began, and the viewer who
+  // opened the film further on was not in that picture. Walking into their
+  // stretch means writing names they are writing.
+  const behindRun = [...behind.runs][0];
+  const aheadRun = [...ahead.runs][0];
+  assert.equal(manager.runMakingSegment(behind, 550, behindRun), aheadRun);
+  assert.equal(manager.runMakingSegment(behind, 499, behindRun), null);
+  assert.equal(
+    manager.runMakingSegment(ahead, 550, aheadRun),
+    null,
+    "a run without an end owns only as far as it will get, not the rest of the film"
+  );
+  void stopped;
+});
+
+test("a seek backwards does not drag the picture away from a viewer watching ahead", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const shared = sessionOn({
+    id: "shared",
+    dirPath,
+    segmentCount: 1000,
+    runState: "PRODUCING",
+    encodeStartIndex: 200,
+    runEndIndex: -1
+  });
+  shared.sourceKey = "torrent:abc";
+  shared.fileIndex = 0;
+  shared.timeline = new Timeline({ boundaries: Array.from({ length: 1001 }, (_, index) => index * 4), cutGrid: "uniform" });
+  shared.acquireSource = null;
+  shared.progress = { processedSeconds: 900, startPositionSeconds: 800 };
+  manager.sessionsById.set(shared.id, shared);
+
+  // One viewer is at segment 250 and being served. The other jumps back an hour.
+  viewerOf(shared, "ahead").head = { segment: 250, seconds: 1000, at: Date.now() };
+  viewerOf(shared, "back").head = { segment: 250, seconds: 1000, at: Date.now() };
+
+  const servingAhead = [...shared.runs][0];
+  const startedAt = servingAhead.from;
+  manager.requestSeek("shared", 40, "back");
+
+  assert.equal(
+    servingAhead.from,
+    startedAt,
+    "the run serving the viewer in front is left exactly where it was"
+  );
+  assert.ok(shared.runs.has(servingAhead), "and it is not stopped");
+  // A run start claims its attempt before it awaits anything, so the assertion
+  // holds without the test needing an ffmpeg. 40 s is segment #10 on this grid.
+  assert.equal(
+    shared.pendingRun?.startIndex,
+    10,
+    "and the one who jumped is given a run of their own, there"
+  );
+});
+
+test("a seek backwards with nobody else watching still moves the run", (t) => {
+  const { manager, root, dirPath } = managerWithAnEmptyOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  let created = 0;
+  manager.createOrGetSession = async () => {
+    created += 1;
+    return null;
+  };
+
+  const alone = sessionOn({
+    id: "alone",
+    dirPath,
+    segmentCount: 1000,
+    runState: "PRODUCING",
+    encodeStartIndex: 200,
+    runEndIndex: -1
+  });
+  alone.timeline = new Timeline({ boundaries: Array.from({ length: 1001 }, (_, index) => index * 4), cutGrid: "uniform" });
+  alone.progress = { processedSeconds: 900, startPositionSeconds: 800 };
+  manager.sessionsById.set(alone.id, alone);
+  viewerOf(alone, "only").head = { segment: 250, seconds: 1000, at: Date.now() };
+
+  manager.requestSeek("alone", 40, "only");
+
+  // Nobody is left behind, so a second run would be an encoder for one viewer
+  // who is not there any more.
+  assert.equal(created, 0);
+  assert.equal(alone.seekTarget !== undefined, true, "the run itself is repositioned, as before");
+});

package/test/run-position-follows-published-grid.test.js

@@ -19,6 +19,7 @@
  */
 
 import assert from "node:assert/strict";
+import { Timeline } from "../services/output/Timeline.js";
 import test from "node:test";
 
 import { HlsSessionManager, describeGridDrift, segmentCutTimesFrom } from "../services/hls-session-manager.js";
@@ -40,8 +41,7 @@ function sessionWithDriftedGrid() {
   });
   const session = {
     id: "picture",
-    segmentBoundaries: [...CORRECTED],
-    publishedBoundaries: [...PUBLISHED]
+    timeline: new Timeline({ boundaries: [...CORRECTED], published: [...PUBLISHED], cutGrid: "uniform" })
   };
   return { manager, session };
 }
@@ -49,7 +49,7 @@ function sessionWithDriftedGrid() {
 test("a run starts at the time the player was told, not at the corrected one", () => {
   const { manager, session } = sessionWithDriftedGrid();
   assert.equal(manager.runStartTimeFor(session, 2), 16.684);
-  assert.notEqual(manager.runStartTimeFor(session, 2), session.segmentBoundaries[2]);
+  assert.notEqual(manager.runStartTimeFor(session, 2), session.timeline.boundaries[2]);
 });
 
 test("position and cut list come from the same table", () => {
@@ -65,7 +65,7 @@ test("position and cut list come from the same table", () => {
 
 test("a session that published no grid positions on the live one", () => {
   const { manager } = sessionWithDriftedGrid();
-  const session = { id: "no-playlist", segmentBoundaries: [...CORRECTED], publishedBoundaries: [] };
+  const session = { id: "no-playlist", timeline: new Timeline({ boundaries: [...CORRECTED], published: [], cutGrid: "uniform" }) };
   assert.equal(manager.runStartTimeFor(session, 2), CORRECTED[2]);
 });
 

package/test/seek-landing.test.js

@@ -14,6 +14,7 @@
  */
 
 import assert from "node:assert/strict";
+import { SourceFile } from "../services/source/SourceFile.js";
 import test from "node:test";
 
 import { seekLandingOffsetFor } from "../services/hls-session-manager.js";
@@ -21,26 +22,26 @@ import { seekLandingOffsetFor } from "../services/hls-session-manager.js";
 const OFFSET = 3 / 23;
 
 test("a copied picture is asked for one heuristic later than the keyframe", () => {
-  const session = { transcodeVideo: false, keyframeTimes: [0, 2.002, 4.004, 6.006] };
+  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [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, keyframeTimes: [0, 2.002, 4.004] };
+  const session = { transcodeVideo: true, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [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, keyframeTimes: [0, 0.1, 0.2, 0.3] };
+  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [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, keyframeTimes: [0, 2.002, 4.004] };
+  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 2.002, 4.004] }) };
   assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET);
 });
 
@@ -57,8 +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,
-    keyframeTolerance: 0.04,
-    keyframeTimes: [0, 4.004, 8.008, 12.012]
+    file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 4.004, 8.008, 12.012], keyframeTolerance: 0.04 })
   };
   assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET + 0.04);
 });
@@ -66,11 +66,11 @@ 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, keyframeTolerance: 0, keyframeTimes: [0, 4.004, 8.008] };
+  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 4.004, 8.008], keyframeTolerance: 0 }) };
   assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET);
 });
 
 test("the bound still holds once a tolerance is added", () => {
-  const session = { transcodeVideo: false, keyframeTolerance: 1, keyframeTimes: [0, 0.1, 0.2] };
+  const session = { transcodeVideo: false, file: new SourceFile({ sourceKey: "s", fileIndex: 0 }).learn({ keyframeTimes: [0, 0.1, 0.2], keyframeTolerance: 1 }) };
   assert.equal(seekLandingOffsetFor(session, 0.1), 0.05);
 });

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

@@ -15,10 +15,13 @@
 
 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 { 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";
 
 const SESSION_ID = "aaaaaaaa-1111-2222-3333-444444444444";
@@ -42,19 +45,28 @@ async function managerAfterSeek() {
   manager.sessionsById.set(SESSION_ID, {
     id: SESSION_ID,
     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.
+    timeline: new Timeline({
+      boundaries: Array.from({ length: 400 }, (_, index) => index * SEGMENT_SECONDS),
+      cutGrid: "uniform"
+    }),
     state: "ready",
-    fileName: "film.mkv",
+    file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "film.mkv" }),
+    // 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; },
     startedAt: Date.now(),
     lastAccessedAt: Date.now(),
     consumers: new Set(),
     segmentFormat: fmp4Format,
     transcodeVideo: false,
     useSyntheticPlaylist: true,
-    segmentBoundaries: Array.from({ length: 400 }, (_, index) => index * SEGMENT_SECONDS),
     segmentCount: 399,
     encodeStartIndex: SEGMENT_AT_SEEK,
     waitEpoch: 1,
-    viewerPositionSeconds: SEEK_TO_SECONDS,
+    furthestViewerSeconds: SEEK_TO_SECONDS,
     runState: "PRODUCING"
   });
   return { manager, dirPath };
@@ -128,16 +140,16 @@ 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);
-  session.consumerHeads = new Map();
+  session.viewers = new Map();
   // Two people watching one copied picture. The shared position belongs to the
   // one in front — it is the furthest segment anybody asked for — and the one
   // behind is a hundred segments back, waiting for a segment there.
   const behind = SEGMENT_AT_SEEK - 100;
-  session.consumerHeads.set("behind", {
+  viewerOf(session, "behind").head = {
     segment: behind,
     seconds: behind * SEGMENT_SECONDS,
     at: Date.now()
-  });
+  };
 
   assert.equal(
     manager.requestStillWanted(SESSION_ID, `segment-${String(behind).padStart(5, "0")}.mp4`, "behind"),
@@ -156,13 +168,13 @@ 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);
-  session.consumerHeads = new Map();
+  session.viewers = new Map();
   const staying = SEGMENT_AT_SEEK - 40;
-  session.consumerHeads.set("staying", {
+  viewerOf(session, "staying").head = {
     segment: staying,
     seconds: staying * SEGMENT_SECONDS,
     at: Date.now()
-  });
+  };
 
   const jumpTo = 120;
   manager.requestSeek(SESSION_ID, jumpTo, "jumping");

package/test/segment-demand.test.js

@@ -0,0 +1,82 @@
+/**
+ * @file What viewers want of an output, stated once each and read as a union.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SegmentDemand } from "../services/encode/SegmentDemand.js";
+
+const PICTURE = "torrent:abc:fmt=fmp4:grid=kf@0:video-only:v=0/copy";
+const SOUND = "torrent:abc:fmt=fmp4:grid=kf@0:audio-only:a=0/1/copy";
+
+test("a viewer restating a window replaces it rather than adding to it", () => {
+  // A player restates its window every few seconds. Accumulated, the demand
+  // would grow to the whole film within a minute.
+  const demand = new SegmentDemand();
+  demand.state({ claimant: "one", address: PICTURE, from: 0, to: 10, statedAt: 1 });
+  demand.state({ claimant: "one", address: PICTURE, from: 30, to: 40, statedAt: 2 });
+  assert.deepEqual(demand.spanOn(PICTURE), { from: 30, to: 40 });
+  assert.equal(demand.stats().windows, 1);
+});
+
+test("one viewer states a window per output, and both stand", () => {
+  const demand = new SegmentDemand();
+  demand.state({ claimant: "one", address: PICTURE, from: 0, to: 10, statedAt: 1 });
+  demand.state({ claimant: "one", address: SOUND, from: 0, to: 10, statedAt: 1 });
+  assert.equal(demand.stats().windows, 2);
+  assert.deepEqual(demand.addresses().sort(), [SOUND, PICTURE].sort());
+});
+
+test("two viewers of one output are a union, not a sum", () => {
+  // Two viewers seconds apart want mostly the same segments; counted twice, a
+  // stretch would look twice as wanted as it is.
+  const demand = new SegmentDemand();
+  demand.state({ claimant: "one", address: PICTURE, from: 10, to: 14, statedAt: 1 });
+  demand.state({ claimant: "two", address: PICTURE, from: 12, to: 16, statedAt: 1 });
+  assert.deepEqual(demand.wantedOn(PICTURE), [10, 11, 12, 13, 14, 15, 16]);
+});
+
+test("two viewers far apart make a span that covers the ground between them", () => {
+  // Not so it is all made — so that a search for a gap considers all of it.
+  const demand = new SegmentDemand();
+  demand.state({ claimant: "one", address: PICTURE, from: 0, to: 5, statedAt: 1 });
+  demand.state({ claimant: "two", address: PICTURE, from: 900, to: 905, statedAt: 1 });
+  assert.deepEqual(demand.spanOn(PICTURE), { from: 0, to: 905 });
+});
+
+test("a viewer who leaves takes every window they stated", () => {
+  const demand = new SegmentDemand();
+  demand.state({ claimant: "one", address: PICTURE, from: 0, to: 5, statedAt: 1 });
+  demand.state({ claimant: "one", address: SOUND, from: 0, to: 5, statedAt: 1 });
+  demand.state({ claimant: "two", address: PICTURE, from: 0, to: 5, statedAt: 1 });
+  assert.equal(demand.forget("one"), 2);
+  assert.equal(demand.stats().claimants, 1);
+  assert.equal(demand.addresses().length, 1);
+});
+
+test("expiry is carried out here and decided elsewhere", () => {
+  // The register has no clock on purpose: the rule that says how stale is too
+  // stale lives with whoever measures it, and this stays exercisable with
+  // numbers alone.
+  const demand = new SegmentDemand();
+  demand.state({ claimant: "one", address: PICTURE, from: 0, to: 5, statedAt: 1000 });
+  demand.state({ claimant: "two", address: PICTURE, from: 0, to: 5, statedAt: 9000 });
+  const dropped = demand.forgetStatedBefore(5000);
+  assert.equal(dropped.length, 1);
+  assert.equal(dropped[0].claimant, "one");
+  assert.equal(demand.stats().windows, 1);
+});
+
+test("a window that is not a window is refused rather than stored", () => {
+  const demand = new SegmentDemand();
+  assert.equal(demand.state({ claimant: "one", address: PICTURE, from: 5, to: 1, statedAt: 1 }), null);
+  assert.equal(demand.state({ claimant: "", address: PICTURE, from: 0, to: 1, statedAt: 1 }), null);
+  assert.equal(demand.state({ claimant: "one", address: "", from: 0, to: 1, statedAt: 1 }), null);
+  assert.equal(demand.stats().windows, 0);
+});
+
+test("nothing wanted on an output answers null rather than an empty span", () => {
+  const demand = new SegmentDemand();
+  assert.equal(demand.spanOn(PICTURE), null);
+  assert.deepEqual(demand.wantedOn(PICTURE), []);
+});