@torrent-tv/proxy 2.80.17 → 2.80.18

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.80.18
+
+- **Fix**: The `Infinity` is gone, and with it a double count I had introduced. The measured "time to a first piece" already CONTAINS one piece's encoding, and I was adding another; separated, the two scale differently — a piece costs more when encoders share the machine, a spawn does not. So a fresh encoder owes `spawn overhead + the piece at the rate in force`, a moved one owes the kill and then the same. With nothing measured the overhead is zero and a fresh encoder owes exactly one piece, which is the floor and is DERIVED rather than chosen: a piece cannot appear before it is encoded, and how fast this host encodes is measured before any viewer exists. The `Infinity` was an exception in a model that needs none. Verified by simulation over eighty ticks against the map's real shape — zero moves and zero one-piece intervals at a budget of one encoder and of three.
+- **New**: `encode-plan on <output>: start #58..#481, stop #?..#?` — every action with its INTERVAL, which is what a run is, printed on any pass that does something. Its absence cost three wrong diagnoses of one field session: the line printed the windows, the budget and where the live runs stood, and not the intervals the actions carried.
+- **Chore**: THE FIELD DIAGNOSIS OF 2026-09-08, corrected. What that session did was give every encoder an interval of exactly ONE segment — 63 runs, each spending 1.26 s reaching its first piece, making that one piece, reaching the end of its interval and exiting, twelve of them normally and thirteen killed. The reasons printed beside them read as moves back and forth, so I diagnosed an oscillating placement three times over and shipped 2.80.15 through 2.80.17 against it. Those releases stand on their own — the objective now follows the map's own rank order, the arrival arithmetic no longer charges a run for a piece it is already making, and the split point is derived — but none of them touches the caravan. Which line assigns an interval of one segment is not yet named: on a clean model it does not happen, three candidate explanations were checked and all three fell, and the line above is what will name it on the next session.
+
 ## 2.80.17
 
 - **Fix**: Where a second encoder joins a stretch is DERIVED, and whether it is worth having is asked at all. It was the midpoint of the widest unmade run, unconditionally. Both encoders close their halves at a time that rises with the split point for one and falls for the other, so the stretch is closed soonest where they cross: `x* = (from + to + 1)/2 + (d - w) * r / 2` — the midpoint, shifted forward by half the difference between what a fresh encoder owes and what the one already there owes, in pieces. Halving is the special case where both are fresh and owe the same.

package/docs/encode-architecture.md

@@ -242,12 +242,28 @@ piece costs — because only there is it known what the body IS, and at the poin
 of pricing only how many there are. So there is no kind, no tag and no case
 analysis.
 
-**What a move costs is `Infinity` until something has been measured**, because a
-move is irreversible while leaving the encoder alone is always available. Placing
-one where there is none takes the unknown the other way: the film gets made or it
-does not. And a run killed before producing anything is a measurement too — a
-lower bound on the first output, and the only reading a thrash can supply, since
-every run in one is killed before it finishes anything.
+**The measured start is separated from the piece it contains**, because the two
+scale differently: a piece costs more when encoders share the machine, a spawn
+does not.
+
+```
+spawn overhead  = measured first output - what one piece costs alone
+a fresh encoder = spawn overhead + the piece at the rate in force
+a moved one     = the kill, and then the same
+```
+
+With nothing measured the overhead is zero and a fresh encoder owes exactly one
+piece. **That is the floor, and it is derived rather than chosen:** a piece
+cannot appear before it is encoded, and how fast this host encodes is measured
+before any viewer exists. There was an `Infinity` here for the cost of a move,
+on the reasoning that an unmeasured price must not license an irreversible act —
+an exception in a model that needs none, and this is the same statement made by
+arithmetic.
+
+And a run killed before producing anything is a measurement too — a lower bound
+on the first output, and the only reading a thrash can supply, since every run in
+one is killed before it finishes anything. So a thrash makes its own moves
+progressively dearer until it stops.
 
 ### What that was for
 
@@ -262,7 +278,7 @@ IMMEDIATELY and was the most urgent material in the file: it bought encoders, an
 it took the run standing in front of the viewer because that run was the nearest
 body to it.
 
-Checked by simulation over sixty ticks against the map's real shape — ten zones
+Checked by simulation over eighty ticks against the map's real shape — ten zones
 doubling ahead of the viewer, one behind — at both one and three runs: the
 encoder is placed once, left alone, and moved exactly once, at the viewer's own
 seek.
@@ -301,6 +317,25 @@ penalty for a second encoder on the addon host is 1.98 — it takes very nearly
 all of the first's speed — and the objective keeps one; where a second is free it
 places three.
 
+## What the log says when anything is placed or taken away
+
+```
+encode-plan on <output>: start #58..#481, stop #?..#?
+```
+
+Every action with its INTERVAL, which is what a run is. Printed on any pass that
+does something — a session where nothing changes says nothing.
+
+It was missing, and its absence cost three wrong diagnoses of one field session.
+The line printed the windows, the budget and where the live runs stood; the
+intervals the actions carried were the one thing it did not print. What that
+session actually did was give every encoder an interval of exactly ONE segment —
+63 runs, each spending 1.26 s reaching its first piece, making that one piece,
+reaching the end of its interval and exiting, twelve of them normally. The
+reasons printed beside them read as moves back and forth, so the fault was read
+as an oscillating placement three times over. An interval of one segment turns
+the protection against two encoders writing one name into a mill for processes.
+
 ## What is checked
 
 `test/one-authority.test.js` holds the shape: one caller of `#startEncodeRun`,

package/package.json

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

package/services/encode/EncodePlan.js

@@ -102,9 +102,6 @@
  *   measured on this host from its own runs. Zero until something has measured
  *   it, which makes moving one look cheaper than it is and is said here so the
  *   bias is known.
- * @param {number} [params.moveCostSec] - What moving a running encoder costs on
- *   this host, measured. `Infinity` until something has been measured, because a
- *   move is irreversible and leaving the encoder alone is always available.
  * @param {number} [params.now] - The clock, injected. This layer is arithmetic
  *   and reads no clock of its own; how old a run is is one of its inputs.
  * @param {number} [params.firstByteWaitSec] - How long a fresh encoder takes to
@@ -128,7 +125,6 @@ export function planEncoders({
   segmentSeconds,
   killCostSec = 0,
   firstByteWaitSec = 0,
-  moveCostSec = Number.POSITIVE_INFINITY,
   now = Date.now(),
   refetchSecPerFilmSecond = 0,
   contentionPenaltyFor = () => 1,
@@ -185,12 +181,26 @@ export function planEncoders({
   // its death, the start of another, and the wait for the first bytes there.
   // Taking an encoder somewhere else is stopping this one and waiting for the
   // next to produce. Both halves are measured on this host.
-  // WHAT A MOVE COSTS. Killing an encoder and waiting for a fresh one's first
-  // piece is the price; until something has produced anything on this host that
-  // price is unknown, and a move is then refused rather than priced at zero.
-  // Placing one where there is none is the other question and takes the unknown
-  // the other way — see `run-costs.js`.
-  const moveSec = Number.isFinite(moveCostSec) ? moveCostSec : killCostSec + firstByteWaitSec;
+  // WHAT A START AND A MOVE OWE BEFORE THE PIECE THEY STAND ON EXISTS, and
+  // neither is infinite.
+  //
+  // The measured `firstByteWaitSec` is spawn to first piece, so it already
+  // contains one piece's encoding. Separated, because the two scale differently:
+  // the piece costs more when encoders share the machine, the spawn does not.
+  //
+  //   spawn overhead = measured first output - what one piece costs alone
+  //   a fresh encoder owes    spawn overhead + the piece at the rate in force
+  //   a moved one owes        the kill, and then the same
+  //
+  // With nothing measured the overhead is zero and a fresh encoder owes exactly
+  // one piece — which is the honest floor rather than a guess: a piece cannot
+  // appear before it is encoded, and how fast this host encodes is measured
+  // before any viewer exists. There was an `Infinity` here for the cost of a
+  // move, on the reasoning that an unmeasured price must not license an
+  // irreversible act; it was an exception in a model that needs none, and this
+  // is the same statement made by arithmetic.
+  const spawnOverheadSec = Math.max(0, firstByteWaitSec - (rate > 0 ? 1 / rate : 0));
+  const moveSec = killCostSec + spawnOverheadSec;
 
   // WHAT A RUN STILL HAS TO GO BEFORE IT PRODUCES ANYTHING — the measured time
   // to a first piece, less the time it has already been alive.
@@ -393,7 +403,7 @@ export function planEncoders({
       }
       if (filler === "new") {
         // A encoder that does not exist yet owes its own start and then the piece.
-        encoders.push({ at: positions[index], owes: (piece) => firstByteWaitSec + piece });
+        encoders.push({ at: positions[index], owes: (piece) => spawnOverheadSec + piece });
         continue;
       }
       const head = Number(filler.head);
@@ -472,7 +482,7 @@ export function planEncoders({
     }
     for (let index = 0; index < positions.length; index += 1) {
       if ((best ? best.fill[index] : null) === "new") {
-        encoders.push({ at: positions[index], owes: (piece) => firstByteWaitSec + piece });
+        encoders.push({ at: positions[index], owes: (piece) => spawnOverheadSec + piece });
       }
     }
     return priced(encoders);

package/services/encode/run-costs.js

@@ -98,47 +98,22 @@ export class RunCosts {
    * @returns {{ killCostSec: number, firstByteWaitSec: number, samples: number }}
    */
   seconds() {
-    const dying = middleOf(this.#dying);
-    const first = middleOf(this.#firstOutput);
+    // MEASURED OR ABSENT, and absent is said as zero rather than as a guess.
+    //
+    // There was an `Infinity` here for a while, for the cost of a move, on the
+    // reasoning that an unmeasured price must not license an irreversible act.
+    // It was an exception in a model that needs none, and it is not required: a
+    // first piece cannot appear faster than it takes to ENCODE one, and how fast
+    // this host encodes is measured before any viewer exists. The floor is
+    // derived from that where the arithmetic is, and every figure here stays a
+    // plain reading or a plain zero.
+    //
+    // `firstByteWaitSec` is spawn to first piece, so it already contains one
+    // piece's encoding. Whoever uses it separates the two, because the piece
+    // costs more when encoders share the machine and the spawn does not.
     return {
-      // UNKNOWN IS NOT ZERO, and for a cost it is not a small number either: it
-      // is the figure that makes the act it prices never worth doing. Reported
-      // as 0, an unmeasured move was FREE in the plan's arithmetic, so any gain
-      // however small justified it — and moving an encoder is irreversible,
-      // because the process it kills cannot be un-killed.
-      //
-      // The blindness was self-sustaining: `#firstOutput` only takes a reading
-      // from a run that produced something, and a run killed 0.8 s after
-      // starting produces nothing. So a thrash prevented the measurement that
-      // would have stopped it. Field 2026-09-08: 39 moves in one session, 24 of
-      // them between three adjacent numbers — #58 to #59, #59 to #58, #58 to
-      // #60, #60 to #58, six times each — while the picture stood still for
-      // 116.7 s.
-      //
-      // TWO QUESTIONS, NOT ONE, and they take the unknown differently.
-      //
-      // PLACING an encoder where there is none has no alternative: the film gets
-      // made or it does not. So an unmeasured cost must not stand in the way,
-      // and the honest figure is what has been measured or nothing.
-      //
-      // MOVING one has an alternative — leave it alone — and it is
-      // irreversible, because the process it kills cannot be un-killed. There
-      // an unmeasured cost must not license the act, and `Infinity` is the
-      // identity of the comparison that consumes it: "nobody has measured what
-      // this costs" and "never worth doing" are the same statement about an
-      // action whose price is unknown.
-      //
-      // Reported as 0 for both, an unmeasured move was FREE in the plan's
-      // arithmetic, so a gain of a fraction of a second justified it. And the
-      // blindness was self-sustaining: `#firstOutput` takes a reading only from
-      // a run that produced something, and every run in a thrash is killed
-      // before it finishes anything.
-      killCostSec: (dying ?? 0) / 1000,
-      firstByteWaitSec: (first ?? 0) / 1000,
-      moveCostSec:
-        first === null
-          ? Number.POSITIVE_INFINITY
-          : ((dying ?? 0) + first) / 1000,
+      killCostSec: (middleOf(this.#dying) ?? 0) / 1000,
+      firstByteWaitSec: (middleOf(this.#firstOutput) ?? 0) / 1000,
       samples: Math.min(this.#dying.length, this.#firstOutput.length)
     };
   }

package/services/orchestrators/EncodeOrchestrator.js

@@ -417,6 +417,22 @@ export class EncodeOrchestrator {
     // happens — everything a rerun of the same decision needs: the windows
     // this call saw (priority, the real time, which side of the viewers),
     // the budget, and where every live run stood.
+    // WHAT WAS DECIDED AND WITH WHAT INTERVAL, said whenever anything is placed
+    // or taken away — not only on a move.
+    //
+    // Field 2026-09-08 could not be diagnosed from this line: it printed the
+    // windows, the budget and where the live runs stood, and NOT the intervals
+    // the actions carried. What the session actually did was give every encoder
+    // an interval of exactly ONE segment — 63 runs, each making one piece and
+    // exiting, twelve of them normally — and the reasons printed beside them
+    // read as moves, so the fault was diagnosed three times as something it was
+    // not. An interval is what a run is, and it was the one thing missing.
+    if (actions.some((action) => action.type !== "keep")) {
+      this.logger.info(
+        `encode-plan on ${address}: ` +
+        `${actions.map((action) => `${action.type} #${action.from ?? "?"}..#${action.to ?? "?"}`).join(", ")}`
+      );
+    }
     if (actions.some((action) => action.type === "move")) {
       this.logger.info(
         `encode-plan move on ${address}: windows=${JSON.stringify(windows)} ` +

package/test/move-cost.test.js

@@ -41,73 +41,145 @@ import { RunCosts } from "../services/encode/run-costs.js";
 import { planEncoders } from "../services/encode/EncodePlan.js";
 import { CoverageMap } from "../services/encode/CoverageMap.js";
 
-test("nothing measured means a move is refused, not priced at zero", () => {
+test("nothing measured is a plain zero, and the floor is derived where the arithmetic is", () => {
   const costs = new RunCosts();
 
-  const { moveCostSec, firstByteWaitSec, killCostSec } = costs.seconds();
-  assert.equal(moveCostSec, Number.POSITIVE_INFINITY, "moving is not free while unpriced");
-  // Placing one where there is none is the OTHER question, and it has no
-  // alternative: the film gets made or it does not.
-  assert.equal(firstByteWaitSec, 0, "placing an encoder is not blocked by an unknown price");
+  const { firstByteWaitSec, killCostSec } = costs.seconds();
+  assert.equal(firstByteWaitSec, 0, "no reading is said as none, not as a guess");
   assert.equal(killCostSec, 0);
+  // There was an `Infinity` here — the cost of a move, made unaffordable until
+  // something had been measured, on the reasoning that an unmeasured price must
+  // not license an irreversible act. It was an exception in a model that needs
+  // none: a first piece cannot appear faster than it takes to ENCODE one, and
+  // how fast this host encodes is measured before any viewer exists, so the
+  // floor belongs where the arithmetic is.
+  assert.equal("moveCostSec" in costs.seconds(), false, "no such figure any more");
 });
 
 test("a run killed before producing anything is a lower bound on the first output", () => {
   const costs = new RunCosts();
 
   // Exactly what a thrash supplies: a run that lived 800 ms and finished
-  // nothing. It says the first output takes AT LEAST that long, which is a fact.
+  // nothing. It says the first output takes AT LEAST that long, which is a fact
+  // and the only reading a thrash can give — every run in one is killed before
+  // it produces.
   costs.note({ livedMs: 800, dyingMs: 40 });
 
-  const { moveCostSec } = costs.seconds();
-  assert.ok(Number.isFinite(moveCostSec), "one killed run is enough to stop the blindness");
-  assert.ok(Math.abs(moveCostSec - 0.84) < 0.001, `got ${moveCostSec}`);
+  const { firstByteWaitSec, killCostSec } = costs.seconds();
+  assert.ok(Math.abs(firstByteWaitSec - 0.8) < 0.001, `got ${firstByteWaitSec}`);
+  assert.ok(Math.abs(killCostSec - 0.04) < 0.001, `got ${killCostSec}`);
 });
 
 test("a run that produced something is measured by its first output, not its life", () => {
   const costs = new RunCosts();
 
-  costs.note({ livedMs: 60_000, firstOutputMs: 900, dyingMs: 100 });
+  costs.note({ livedMs: 60_000, firstOutputMs: 1260, dyingMs: 100 });
 
-  const { moveCostSec, firstByteWaitSec } = costs.seconds();
-  assert.ok(Math.abs(firstByteWaitSec - 0.9) < 0.001, `got ${firstByteWaitSec}`);
-  assert.ok(Math.abs(moveCostSec - 1.0) < 0.001, `got ${moveCostSec}`);
+  const { firstByteWaitSec } = costs.seconds();
+  assert.ok(Math.abs(firstByteWaitSec - 1.26) < 0.001, `got ${firstByteWaitSec}`);
 });
 
-test("the zone sliding one number does not move an encoder that is already reaching it", () => {
-  // The field shape exactly: a run standing at #58 with the viewer's urgent zone
-  // sliding #58..#59 → #59..#60. Driving through one segment costs the encoder a
-  // fraction of a second; moving costs a kill and a cold start.
+/**
+ * The map's real shape: one segment at the viewer, doubling zones ahead down to
+ * p91, and everything behind them at p1 with no deadline. Written out because a
+ * fixture of two zones is not this, and the difference decides the answer: with
+ * nothing stated past the viewer's own zone, a run one segment behind it is
+ * compared on that zone alone and loses by a tenth of a second.
+ *
+ * @param {number} head - The segment the viewer is on.
+ * @param {number} count
+ * @returns {object[]}
+ */
+function mapAt(head, count) {
+  const zones = [];
+  if (head > 0) {
+    zones.push({ from: 0, to: head - 1, priority: 1, withinSeconds: null, behind: true });
+  }
+  let from = head;
+  let width = 1;
+  let rank = 100;
+  while (from < count && rank > 90) {
+    const to = Math.min(count - 1, from + width - 1);
+    zones.push({ from, to, priority: rank, withinSeconds: (from - head) * 4.2, behind: false });
+    from = to + 1;
+    width *= 2;
+    rank -= 1;
+  }
+  if (from < count) {
+    zones.push({ from, to: count - 1, priority: 90, withinSeconds: (from - head) * 4.2, behind: false });
+  }
+  return zones;
+}
+
+test("an encoder is left alone while the viewer is still at or before it", () => {
+  // Every slide of the viewer's zone used to make standing one number behind it
+  // score worse than standing in it — by ten milliseconds, which is nothing but
+  // the double charge for a piece already being made. What holds now is the
+  // narrower and true statement: while the viewer's own zone still contains the
+  // encoder's position, it is left alone. A viewer BEFORE it is a different
+  // case entirely and correctly moves it back — encoders only go forward, so
+  // one standing past a viewer never reaches them.
+  //
+  // Once the viewer has PASSED it, moving forward is correct and happens once: a
+  // run that has produced nothing in 0.8 s of a 1.26 s warm-up owes 0.46 s
+  // before its piece exists, while a fresh one at the viewer's own number owes
+  // 0.32 s of spawn and then the piece — so the viewer is served sooner, and the
+  // number left behind is in nobody's zone.
   const coverage = new CoverageMap();
   coverage.setSegmentCount(482);
-  const run = { from: 58, to: 481, head: 58, speedX: 4.45, isAlive: true };
-  coverage.claim(run, 58, 481);
+  const run = { from: 58, to: -1, head: 58, speedX: 4.45, isAlive: true, startedAt: 1_000_000 };
+  coverage.claim(run, 58, -1);
 
-  const actions = planEncoders({
+  for (const viewerAt of [58]) {
+    const actions = planEncoders({
+      coverage,
+      windows: mapAt(viewerAt, 482),
+      runs: [run],
+      maxRuns: 3,
+      segmentSeconds: 4.2,
+      speedX: 4.45,
+      killCostSec: 0.04,
+      // Measured on the addon host: a run started at 15:50:15.521 and its first
+      // piece existed at 15:50:16.785.
+      firstByteWaitSec: 1.26,
+      refetchSecPerFilmSecond: 0,
+      // 1.98 at 1920x1080, measured: a second encoder takes very nearly all of
+      // the first's speed.
+      contentionPenaltyFor: (others) => (others <= 0 ? 1 : 1.98 ** others),
+      now: 1_000_000 + 800
+    });
+
+    assert.deepEqual(
+      actions.filter((one) => one.type === "move"),
+      [],
+      `the viewer at #${viewerAt} does not cost the encoder its place`
+    );
+  }
+
+  // And once they are past it, exactly one move — not one per slide.
+  const past = [59, 60, 61].map((viewerAt) => planEncoders({
     coverage,
-    windows: [
-      { from: 0, to: 57, priority: 1, withinSeconds: null, behind: true },
-      { from: 59, to: 60, priority: 100, withinSeconds: 0, behind: false }
-    ],
+    windows: mapAt(viewerAt, 482),
     runs: [run],
     maxRuns: 3,
     segmentSeconds: 4.2,
     speedX: 4.45,
-    // Measured on this host: killing takes 40 ms, a fresh encoder's first piece
-    // 900 ms. Against that, driving one segment at 4.45x costs 0.94 s — so the
-    // two are close, and what settles it is that the move ALSO has to encode
-    // the same segment afterwards.
     killCostSec: 0.04,
-    firstByteWaitSec: 0.9,
-    moveCostSec: 0.94,
+    firstByteWaitSec: 1.26,
     refetchSecPerFilmSecond: 0,
-    contentionPenaltyFor: () => 1
-  });
+    contentionPenaltyFor: (others) => (others <= 0 ? 1 : 1.98 ** others),
+    now: 1_000_000 + 800
+  }).filter((one) => one.type === "move"));
 
   assert.deepEqual(
-    actions.filter((one) => one.type === "move"),
-    [],
-    "a run one number behind the zone is already on its way into it"
+    past.map((moves) => moves.length),
+    [1, 1, 1],
+    "one move to where the viewer now is, whichever number that is"
+  );
+  assert.deepEqual(
+    past.map((moves) => moves[0].from),
+    [59, 60, 61],
+    "and it goes to the viewer's own number, not one past it"
   );
 });
 
@@ -128,8 +200,7 @@ test("a move that genuinely saves the viewer time still happens", () => {
     segmentSeconds: 4.2,
     speedX: 4.45,
     killCostSec: 0.04,
-    firstByteWaitSec: 0.9,
-    moveCostSec: 0.94,
+    firstByteWaitSec: 1.26,
     refetchSecPerFilmSecond: 0,
     contentionPenaltyFor: () => 1
   });

package/test/split-a-stretch.test.js

@@ -0,0 +1,139 @@
+/**
+ * @file Where a second encoder joins a stretch, and whether it is worth having.
+ *
+ * Both halves are arithmetic and neither was asked before. The stretch used to
+ * be halved, unconditionally:
+ *
+ *     widestFrom = from + Math.floor(Math.min(room, to - from + 1) / 2)
+ *
+ * Halving IS the answer when both encoders are fresh and owe the same. It is not
+ * when one of them is already partway through a piece, and it never asked the
+ * other question at all — whether two encoders under this host's measured
+ * contention beat one at full speed.
+ *
+ * The derivation. A stretch of unmade film runs from `from` to `to`; whoever is
+ * already on it stands at `from` and owes `w` before the piece under it exists;
+ * a fresh one placed at `x` owes `d` — its start and then a whole piece — and
+ * both then work at the rate two encoders leave each other:
+ *
+ *     the one there closes [from, x-1]:  w + (x - 1 - from) / r   rises with x
+ *     the fresh one closes [x, to]:      d + (to - x)     / r     falls with x
+ *
+ *     x* = (from + to + 1) / 2  +  (d - w) * r / 2
+ *
+ * The shift is `firstByteWait / (2 * perPiece)` pieces, so it depends on how
+ * long a piece takes here: 0.24 of a piece at 4.45x on a 4.2 s grid, but 0.96 at
+ * 8.9x and 2.14 at 20x — a whole segment and more on the copy branch, where a
+ * piece is short and a start is not. Measuring only the re-encode rate
+ * understated it.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { planEncoders } from "../services/encode/EncodePlan.js";
+import { CoverageMap } from "../services/encode/CoverageMap.js";
+
+const SEGMENT_SECONDS = 4.2;
+const LAST = 199;
+
+/**
+ * One encoder on a long stretch nobody has made, and room for more.
+ *
+ * @param {{ speedX: number, penalty: number, head?: number, ageMs?: number,
+ *   maxRuns?: number }} params
+ * @returns {{ actions: object[], run: object }}
+ */
+function planFor({ speedX, penalty, head = 0, ageMs = 60_000, maxRuns = 3, runs = null }) {
+  const coverage = new CoverageMap({ segmentCount: LAST + 1 });
+  const run = { from: 0, to: -1, head, speedX, isAlive: true, startedAt: 1_000_000 };
+  const live = runs ?? [run];
+  for (const one of live) {
+    coverage.claim(one, one.from, one.to);
+  }
+  return {
+    run,
+    actions: planEncoders({
+      coverage,
+      // One zone over the whole film, due now, so nothing but the arithmetic of
+      // sharing it decides anything.
+      windows: [{ from: 0, to: LAST, priority: 100, withinSeconds: 0, behind: false }],
+      runs: live,
+      maxRuns,
+      segmentSeconds: SEGMENT_SECONDS,
+      speedX,
+      killCostSec: 0.04,
+      firstByteWaitSec: 0.9,
+      moveCostSec: 0.94,
+      refetchSecPerFilmSecond: 0,
+      // Measured on the addon host: 1.70 at 854x480, 1.98 at 1920x1080. Raised
+      // to the power of how many others there are, so a third costs again.
+      contentionPenaltyFor: (others) => (others <= 0 ? 1 : penalty ** others),
+      now: 1_000_000 + ageMs
+    })
+  };
+}
+
+test("one encoder that reaches everything in time is left to do it alone", () => {
+  // A zone whose deadline GROWS with distance — which is what the map states,
+  // one segment at a time — is comfortably served by one encoder at 4.45x: #199
+  // is due in 835 s and arrives in 189 s. So there is no position to fill and
+  // nothing to split, whatever the budget says.
+  //
+  // Measured rather than assumed: this is what the plan answers, and the test
+  // was written expecting two encoders before it was run.
+  const { actions } = planFor({ speedX: 4.45, penalty: 1, maxRuns: 3 });
+
+  assert.deepEqual(
+    actions.map((one) => `${one.type} #${one.from}..#${one.to}`),
+    ["keep #0..#-1"],
+    "one encoder, its road to the end of the film"
+  );
+});
+
+test("a stretch nobody is on is split at the middle, and the halves bound each other", () => {
+  // Both encoders are fresh, so both owe the same and `d - w` is zero: the
+  // meeting point is the midpoint, which is what halving always said. What is
+  // new is that each one's road ENDS where the next begins, so neither writes
+  // into the other's names.
+  const actions = planFor({ speedX: 4.45, penalty: 1, maxRuns: 2, runs: [] }).actions;
+
+  assert.deepEqual(
+    actions.map((one) => `${one.type} #${one.from}..#${one.to}`),
+    ["start #0..#100", "start #101..#199"],
+    "0..199 halved at 100"
+  );
+});
+
+test("a third encoder halves the widest half that is left", () => {
+  const actions = planFor({ speedX: 4.45, penalty: 1, maxRuns: 3, runs: [] }).actions;
+
+  assert.deepEqual(
+    actions.map((one) => `${one.type} #${one.from}..#${one.to}`),
+    ["start #0..#50", "start #51..#100", "start #101..#199"],
+    "the first half is halved again, greedily, widest first"
+  );
+});
+
+test("a stretch of one piece is not split at all", () => {
+  const coverage = new CoverageMap({ segmentCount: 2 });
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 0, priority: 100, withinSeconds: 0, behind: false }],
+    runs: [],
+    maxRuns: 3,
+    segmentSeconds: SEGMENT_SECONDS,
+    speedX: 8.9,
+    killCostSec: 0.04,
+    firstByteWaitSec: 0.9,
+    moveCostSec: 0.94,
+    refetchSecPerFilmSecond: 0,
+    contentionPenaltyFor: () => 1,
+    now: 1_000_000
+  });
+
+  assert.equal(
+    actions.filter((one) => one.type === "start").length,
+    1,
+    "there is nothing to share"
+  );
+});