@torrent-tv/proxy 2.89.5 → 2.89.7

package/services/encode/EncodeOrchestrator.js

@@ -1,1192 +1,1192 @@
-/**
- * @file How many encoders run on this proxy, on which outputs, and over which
- * stretches.
- *
- * The application layer over `encode/`. It holds four things and owns none of
- * their rules:
- *
- * 1. what viewers want (`SegmentDemand`), stated once each and read as a union;
- * 2. what has been made and what is being made, one `CoverageMap` per output;
- * 3. the encoders that are running (`EncodeRun`), each over a stretch;
- * 4. a tally of how every run ended, which is what makes "abnormal endings do
- *    not happen" a number rather than an impression.
- *
- * The decision itself is `EncodePlan.planEncoders`, from numbers alone. This
- * carries it out, and everything it cannot know is injected: how many encoders
- * this machine can afford, how a run is built for a given stretch, and which
- * segments already exist.
- *
- * **No viewer reaches the decision.** A viewer states a window and is forgotten
- * as a name; what the plan sees is a union of windows. That is the rule the
- * layer exists for, stated by the user 2026-09-04: requests come from any
- * viewers in any number, encoders are managed to suit them, and viewers get the
- * result when it is ready.
- */
-
-import { CoverageMap } from "./CoverageMap.js";
-import { firstUnmetWant, planEncoders } from "./EncodePlan.js";
-import { endOfRun } from "./EncodeRun.js";
-import { ENCODE_EXIT } from "./encode-exit.js";
-import { affordableRuns } from "./run-budget.js";
-import { RunCosts } from "./run-costs.js";
-import { contentionPenalty } from "./contention.js";
-import { SegmentDemand } from "./SegmentDemand.js";
-import { runStateOf } from "./encode-run-state.js";
-
-/**
- * @typedef {Object} SegmentCoverage
- * @property {(address: string) => number[]} provenNumbers
- * @property {(address: string, index: number) => void} announce
- * @property {(address: string) => number} filesHeld
- * @property {(address: string, startedAt: number) => number} clearUpAfter
- */
-
-/**
- * How long nothing is placed on an output whose input has just gone, and the
- * ceiling that doubling reaches.
- *
- * Both are chosen, and are named here as chosen rather than dressed as
- * measurements: what they bound is not how long the data takes to come back —
- * that is the swarm's business and nobody here can know it — but how often it
- * is worth asking. They replace the same two figures, with the same values,
- * that lived in the session manager and governed only the dead run's own retry
- * while the plan placed fresh runs beside it every half second.
- */
-const INPUT_QUIET_BASE_MS = 2_000;
-const INPUT_QUIET_MAX_MS = 15_000;
-const START_FAST_FAIL_MS = 2_000;
-const MAX_FAILED_STARTS = 3;
-
-export class EncodeOrchestrator {
-  /** Derived priority maps. Discardable and rebuilt from viewer state. */
-  #demand = new SegmentDemand();
-  /** @type {(address: string) => string} */
-  #describeWaits = () => "";
-
-  /** Output address to what has been made of it. @type {Map<string, CoverageMap>} */
-  #coverage = new Map();
-
-  /** @type {SegmentCoverage | null} */
-  #segmentCoverage = null;
-
-  /** Output address to the runs on it. @type {Map<string, import("../encode/EncodeRun.js").EncodeRun[]>} */
-  #runs = new Map();
-
-  /** Last state after an output has no registered run. @type {Map<string, string>} */
-  #lastState = new Map();
-
-  /** Last encoder error per output. @type {Map<string, string>} */
-  #lastError = new Map();
-
-  /** Last progress snapshot per output after its run ends. @type {Map<string, object>} */
-  #lastProgress = new Map();
-
-  /** Consecutive fast failures at one position, per output. @type {Map<string, { at: number, count: number }>} */
-  #failedStarts = new Map();
-
-  /** How runs have ended, by cause. @type {Map<string, number>} */
-  #endings = new Map();
-
-  /**
-   * How many times in a row an output's run has died because its input was not
-   * there. Cleared only by a run that PRODUCED something, which is the only
-   * proof that the input can be read — see `#noteInputAvailability`.
-   *
-   * @type {Map<string, number>}
-   */
-  #inputLostAttempts = new Map();
-
-  /** Output address to the time before which nothing is placed on it. @type {Map<string, number>} */
-  #quietUntil = new Map();
-
-  /** The wake-up per output, so a quiet output is reconsidered. @type {Map<string, NodeJS.Timeout>} */
-  #quietTimers = new Map();
-
-  /** The last state said out loud, so an unchanged state is not repeated. */
-  #lastDescribed = "";
-
-  /** What a stop and a start have cost on this host. */
-  #costs = new RunCosts();
-
-  /**
-   * What starting and stopping an encoder was measured to cost on this host,
-   * before any viewer existed. Told once; real runs replace it as they end.
-   *
-   * @param {{ firstByteWaitSec: number, killCostSec: number } | null} measured
-   * @returns {void}
-   */
-  noteStartupCosts(measured) {
-    this.#costs.noteStartup(measured);
-  }
-
-  /** Derived segment demand for one output, copied from the discardable cache. */
-  wantedSegmentsOn(address) {
-    return [...this.#demand.mapOn(address)];
-  }
-
-  /** The last reason a budget was cut, so the same one is not said twice. */
-  #lastBudgetReason = new Map();
-
-  /** The last unmet want said out loud, so a stuck one is said once. */
-  #lastUnmet = new Map();
-
-  /** The last time the machine bound an output's encoders, so it is said once. */
-  #lastMachineBound = new Map();
-
-  /**
-   * @param {object} params
-   * @param {(address: string) => number} params.maxRunsFor - How many encoders
-   *   this machine can afford on one output. The same arithmetic that decides
-   *   the quality offer; measured per host, never chosen here.
-   * @param {(params: { address: string, from: number, to: number, because: string }) =>
-   *   import("../encode/EncodeRun.js").EncodeRun} params.makeRun - Build a run
-   *   for a stretch. What to read, what to map and how to cut belong to whoever
-   *   knows the source.
-   * @param {number} params.segmentSeconds
-   * @param {import("../encode/contention.js").ContentionPenalties | null}
-   *   [params.contentionPenalties] - How much slower one encoder runs beside
-   *   others, MEASURED on this host at startup and keyed by how many others
-   *   there are. Null until something has measured it, and then the penalty is
-   *   1 — a number invented here would be the same mistake as an invented
-   *   encoding speed.
-   * @param {{ info: (line: string) => void, warn: (line: string) => void }} params.logger
-   * @param {() => number} [params.now]
-   * @param {(address: string) => string} [params.describeWaits] - What the
-   *   viewers actually waited for on this output, by band, for the state line.
-   *   HANDED IN: what anybody waited for belongs to the priority layer, and
-   *   this one may be asked about encoders with no ledger, no clock and no
-   *   viewer anywhere. Absent, the line simply does not carry it.
-   * @param {SegmentCoverage | null} [params.segmentCoverage]
-   */
-  constructor({
-    maxRunsFor,
-    makeRun,
-    segmentSeconds,
-    contentionPenalties = null,
-    refetchSecPerFilmSecond = () => 0,
-    startingSpeedFor = () => 0,
-    segmentCoverage = null,
-    planSoon = null,
-    describeWaits = null,
-    admission = null,
-    logger,
-    now
-  }) {
-    // HOW MANY ENCODERS THE WHOLE MACHINE HOLDS, across outputs. `maxRunsFor`
-    // answers for one output as though it were alone; this is what refuses the
-    // encoder that would slow everybody below realtime. Absent in a check that
-    // is about one output, and then only the per-output limit binds.
-    this.admission = admission && typeof admission.placesFor === "function" ? admission : null;
-    this.#describeWaits = typeof describeWaits === "function" ? describeWaits : () => "";
-    // Only the segment facts and operations this planner needs cross the
-    // storage boundary; the concrete storage remains in the server assembly.
-    this.#segmentCoverage = segmentCoverage;
-    this.maxRunsFor = maxRunsFor;
-    // Seconds of swarm time per second of film: what re-encoding material that
-    // already exists costs the download, over and above the encoder's own time.
-    // Injected, because the film's byte rate and the swarm's are measured
-    // elsewhere and this class must not reach for them.
-    this.refetchSecPerFilmSecond = refetchSecPerFilmSecond;
-    // Measured per host: what a second encoder costs the first. Unmeasured is 1,
-    // and then only the budget bounds how many there are.
-    this.contentionPenalties = contentionPenalties instanceof Map ? contentionPenalties : null;
-    // WHAT THIS HOST ENCODES AT BEFORE ANY RUN HAS REPORTED. The startup
-    // benchmark measures it — a real pipeline over real clips, before a viewer
-    // exists — so the plan is never asked to compare arrivals with no speed to
-    // compute them from. Every run that then works refines it.
-    this.startingSpeedFor = startingSpeedFor;
-    this.makeRun = makeRun;
-    this.segmentSeconds = segmentSeconds;
-    this.logger = logger;
-    this.now = typeof now === "function" ? now : Date.now;
-    // Asked for, not commanded: this class decides, and something else owns the
-    // loop that calls it. Absent in a test, where the clock is the test's own.
-    this.planSoon = typeof planSoon === "function" ? planSoon : () => undefined;
-  }
-
-  /**
-   * The map of one output, made on first mention.
-   *
-   * @param {string} address
-   * @returns {CoverageMap}
-   */
-  coverageOf(address) {
-    let map = this.#coverage.get(address);
-    if (!map) {
-      map = new CoverageMap();
-      this.#coverage.set(address, map);
-    }
-    return map;
-  }
-
-  /**
-   * Put the map's picture of what is ready back in step with the disk.
-   *
-   * ONE AUTHORITY ON WHAT EXISTS, AND IT IS THE STORE. The map holds no memory
-   * of readiness between calls: it is handed the whole answer, replacing
-   * whatever it had, immediately before anything is decided from it. So a
-   * segment whose file was discarded with the run that had it open, dropped to
-   * make room, or reopened by a run restarting on it stops being ready in the
-   * same breath — without anything having to notice and say so.
-   *
-   * The map used to be filled from outside, by the session manager, with a
-   * method that only ever added. Nothing anywhere took a number back. Field
-   * 2026-09-07: the map claimed all 482 segments of a film while the directory
-   * held nothing, so every arrangement scored perfect, the only encoder was
-   * stopped as unnecessary and none was placed again — two sessions in a row
-   * with no picture at all.
-   *
-   * A store is optional here only in the sense that an authority which was not
-   * supplied cannot be consulted: without one the map keeps what it was told
-   * directly, which is how this class is exercised with plain numbers.
-   *
-   * @param {string} address
-   * @returns {CoverageMap}
-   */
-  #upToDateCoverage(address) {
-    const coverage = this.coverageOf(address);
-    if (this.#segmentCoverage) {
-      coverage.setReady(this.#segmentCoverage.provenNumbers(address));
-    }
-    return coverage;
-  }
-
-  /**
-   * Where a run started here must stop: the free stretch in front of it.
-   *
-   * Asked of the one map, brought up to date first. It used to be worked out by
-   * the session manager, which reached into this layer for the map and into the
-   * store for what was on the disk and put the two together itself — one fact
-   * with two owners and a third party carrying it between them, which is how the
-   * two came to disagree.
-   *
-   * @param {object} params
-   * @param {string} params.address
-   * @param {number} params.from - Where the run will start.
-   * @param {object | null} [params.exceptRun] - The run being replaced, whose
-   *   own claim is not somebody else's material.
-   * @param {number} [params.segmentCount] - The output's length, when known.
-   * @returns {number} The last number to work through, or `-1` for the end of
-   *   the film.
-   */
-  freeStretchEnd({ address, from, exceptRun = null, segmentCount = 0 }) {
-    if (!address) {
-      return -1;
-    }
-    if (segmentCount > 0) {
-      this.coverageOf(address).setSegmentCount(segmentCount);
-    }
-    const coverage = this.#upToDateCoverage(address);
-    const start = Math.max(0, from);
-    const free = coverage.freeRunFrom(start, exceptRun);
-    if (!Number.isFinite(free)) {
-      return -1;
-    }
-    const end = start + Math.max(1, free) - 1;
-    return segmentCount > 0 && end >= segmentCount - 1 ? -1 : end;
-  }
-
-  /**
-   * @param {string} address
-   * @returns {import("../encode/EncodeRun.js").EncodeRun[]}
-   */
-  runsOn(address) {
-    return this.#runs.get(address) ?? [];
-  }
-
-  /**
-   * The aggregate state of this output's current runs, or its last ending when
-   * none remain.
-   *
-   * @param {string} address
-   * @returns {string}
-   */
-  stateOf(address) {
-    const runs = this.runsOn(address);
-    return runs.length > 0 ? runStateOf(runs) : (this.#lastState.get(address) ?? runStateOf([]));
-  }
-
-  /** @param {string} address @returns {string} */
-  errorOf(address) {
-    return this.#lastError.get(address) ?? "";
-  }
-
-  /**
-   * Progress of the live run that covers a position, or the most recently
-   * updated run when no position is supplied.
-   *
-   * @param {string} address
-   * @param {number | null} [index]
-   * @returns {object | null}
-   */
-  progressOf(address, index = null) {
-    const live = this.runsOn(address).filter((run) => run.isAlive);
-    const covering = Number.isInteger(index)
-      ? live.filter((run) => run.from <= index && endOfRun(run) >= index)
-      : live;
-    const candidates = covering.length > 0 ? covering : live;
-    const run = [...candidates].sort(
-      (left, right) => (right.progress?.updatedAt ?? 0) - (left.progress?.updatedAt ?? 0)
-    )[0];
-    return run?.progress?.snapshot?.() ?? this.#lastProgress.get(address) ?? null;
-  }
-
-  /**
-   * Whether another start at this position is allowed.
-   *
-   * @param {string} address
-   * @param {number} from
-   * @returns {boolean}
-   */
-  mayStartAt(address, from) {
-    const failed = this.#failedStarts.get(address);
-    return failed?.at !== from || failed.count < MAX_FAILED_STARTS;
-  }
-
-  /**
-   * Record whether a failed run died before it performed sustained work.
-   *
-   * @param {string} address
-   * @param {number} from
-   * @param {number} livedMs
-   * @returns {{ at: number, count: number, blocked: boolean, limit: number, fastMs: number }}
-   */
-  noteStartFailure(address, from, livedMs) {
-    if (!(livedMs < START_FAST_FAIL_MS)) {
-      this.#failedStarts.delete(address);
-      return { at: -1, count: 0, blocked: false, limit: MAX_FAILED_STARTS, fastMs: START_FAST_FAIL_MS };
-    }
-    const previous = this.#failedStarts.get(address);
-    const next = {
-      at: from,
-      count: previous?.at === from ? previous.count + 1 : 1
-    };
-    this.#failedStarts.set(address, next);
-    return {
-      ...next,
-      blocked: next.count >= MAX_FAILED_STARTS,
-      limit: MAX_FAILED_STARTS,
-      fastMs: START_FAST_FAIL_MS
-    };
-  }
-
-  /**
-   * An output that no longer exists and has no run left on it.
-   *
-   * How its last run ended, what went wrong and which position kept failing are
-   * facts about THAT output. The name follows from the key, so the next output
-   * with the same parameters has the same address; kept, those facts would
-   * greet it as its own — a failed ending makes its first wait throw before any
-   * encoder is placed, and nothing would ever clear it.
-   *
-   * @param {string} address
-   */
-  forgetOutput(address) {
-    if (this.runsOn(address).length > 0) {
-      return;
-    }
-    this.#lastState.delete(address);
-    this.#lastError.delete(address);
-    this.#lastProgress.delete(address);
-    this.#failedStarts.delete(address);
-  }
-
-  /** @param {string} address @returns {{ at: number, count: number, blocked: boolean, limit: number }} */
-  startFailureOf(address) {
-    const failure = this.#failedStarts.get(address) ?? { at: -1, count: 0 };
-    return { ...failure, blocked: failure.count >= MAX_FAILED_STARTS, limit: MAX_FAILED_STARTS };
-  }
-
-  /**
-   * What the map says about one segment of one output, and about the map it
-   * sits in.
-   *
-   * Asked by whoever is holding a request and measuring the wait: a wait means
-   * one thing at the top rank and another at the bottom, and telling them apart
-   * needs both the segment's own rank and the highest rank stated, since a rank
-   * is a position in this map and not an absolute number.
-   *
-   * AND AN EMPTY MAP IS NOT AN ANSWER. A top rank of zero says the map has not
-   * been built yet — a session created a moment ago, before the first pass —
-   * and that is a different thing from "nobody is coming". Conflated, every
-   * request behind the run reads as absent for as long as a fresh session has
-   * no map.
-   *
-   * It exists because the one caller reached through this object into the store
-   * behind it. A reach like that is how a store becomes the surface: the day it
-   * changes, a caller two layers away breaks for a reason it cannot see.
-   *
-   * @param {string} address
-   * @param {number} index
-   * @returns {{ rank: number, topRank: number }}
-   */
-  rankAt(address, index) {
-    return this.#demand.rankOf(address, index);
-  }
-
-  /**
-   * How many encoder processes are running on this machine right now, over
-   * every output.
-   *
-   * ONE COUNT, and it is this class's because this class is what makes and
-   * unmakes runs: adopted the moment one exists and forgotten the moment one
-   * ends, both synchronously. The session manager answered the same question
-   * twice by walking its own registry — once per SESSION and once per RUN —
-   * which agreed only while a session held at most one run. It has held several
-   * since the plan was allowed to place them, and the per-session count is the
-   * wrong one of the two wherever they differ: what a second encoder costs was
-   * measured between ffmpeg PROCESSES, not between outputs.
-   *
-   * A SUSPENDED run is not counted. It is stopped where it stands and is using
-   * nothing; a cost measured beside it is a cost measured alone.
-   *
-   * @returns {number}
-   */
-  /**
-   * How many encoders are alive on each output, suspended ones included.
-   *
-   * What the machine-wide admission counts as holding a place. A suspended
-   * encoder is counted here, unlike in {@link runningCount}: that one answers
-   * what is competing for the processor this instant, this one what the
-   * machine is committed to — and a parked encoder resumes the moment the
-   * viewer catches up.
-   *
-   * @returns {Map<string, number>}
-   */
-  liveRunsByAddress() {
-    /** @type {Map<string, number>} */
-    const byAddress = new Map();
-    for (const [address, runs] of this.#runs) {
-      const alive = runs.filter((run) => run.isAlive).length;
-      if (alive > 0) {
-        byAddress.set(address, alive);
-      }
-    }
-    return byAddress;
-  }
-
-  runningCount() {
-    let running = 0;
-    for (const runs of this.#runs.values()) {
-      for (const run of runs) {
-        if (run.isAlive && !run.isSuspended) {
-          running += 1;
-        }
-      }
-    }
-    return running;
-  }
-
-  /**
-   * How long an output is, once its playlist is known.
-   *
-   * @param {string} address
-   * @param {number} segmentCount
-   */
-  setSegmentCount(address, segmentCount) {
-    this.coverageOf(address).setSegmentCount(segmentCount);
-  }
-
-  /**
-   * Segments that already exist — from a previous life of this process, or
-   * because somebody else made them. Told to the map, which is what stops an
-   * encoder being started to make them again.
-   *
-   * @param {string} address
-   * @param {Iterable<number>} indexes
-   */
-  noteAlreadyMade(address, indexes) {
-    for (const index of indexes) {
-      this.noteProduced(address, index);
-    }
-  }
-
-  /**
-   * A viewer states what it is waiting for. Replaces whatever it said before.
-   *
-   * @param {object} params
-   * @param {string} params.claimant
-   * @param {string} params.address
-   * @param {number} params.from
-   * @param {number} params.to
-   * @param {number} [params.priority] - Higher is sooner. One viewer states
-   *   several stretches at once — what must be ready before they set off, what
-   *   is reachable while they watch it, the rest of the track — and the filling
-   *   takes them in this order. Absent means one undifferentiated want, which
-   *   is what a caller that knows only a position states.
-   */
-  /**
-   * What is wanted of one output, in its own segment numbers.
-   *
-   * ONE MAP, ALREADY MERGED, AND WITH NOBODY'S NAME ON IT. It is built once per
-   * film by the layer that knows where the viewers are; this layer receives it
-   * converted into an output's own numbering and never asks who is in it.
-   *
-   * That replaced a window per viewer per band stated here and merged here,
-   * which was the same work done twice in two layers, with the viewer's name as
-   * the key of a claim — against the rule that the encoding and the viewer are
-   * not connected at all.
-   *
-   * An empty map says nobody is coming anywhere in this output, and the plan
-   * stops its encoders for it. Nothing has to be released when somebody leaves:
-   * the map that arrives next simply does not have them in it.
-   *
-   * @param {string} address
-   * @param {{ from: number, to: number, priority: number, withinSeconds: number }[]} zones
-   */
-  notePriorityMap(address, zones) {
-    this.#demand.state(address, zones);
-    // NOBODY IS COMING HERE, so what was remembered about this output's input
-    // is about nobody. Kept, those three entries would stay for the life of the
-    // process, and the wait they describe would greet whoever opens this output
-    // next — a viewer arriving is new information, and one attempt for them is
-    // right whatever the last one met.
-    if (!Array.isArray(zones) || zones.length === 0) {
-      this.#forgetInputState(address);
-    }
-  }
-
-  /**
-   * A segment has been finished, by whichever run made it.
-   *
-   * @param {string} address
-   * @param {number} index
-   */
-  noteProduced(address, index) {
-    // Nothing is told to the store: by the time this is called the piece is
-    // ALREADY under its served name, because the rename is what closing it
-    // means. A statement kept beside the disk would be a second owner of one
-    // fact, which removed the stale second owner from the coverage map.
-    this.coverageOf(address).markReady(index);
-    this.#segmentCoverage?.announce?.(address, index);
-    for (const run of this.runsOn(address)) {
-      run.noteProduced(index);
-    }
-  }
-
-  /**
-   * Decide and act, for every output anybody wants anything of and every output
-   * that still has an encoder on it.
-   *
-   * Safe to call as often as anything changes: the plan is a function of the
-   * state, so a pass that finds nothing to change does nothing.
-   */
-  reconcile() {
-    const addresses = new Set([...this.#demand.addresses(), ...this.#runs.keys()]);
-    for (const address of addresses) {
-      this.#reconcileOne(address);
-    }
-    // WHAT THIS CLASS BELIEVES, said by this class. `describe()` was written
-    // and called from nowhere, so on 2026-09-05 the question "why did the plan
-    // not see the gap the viewer was stopped at" had to be answered by
-    // inference from start and stop lines, and was not answered at all.
-    //
-    // Printed on CHANGE rather than on a timer: a quiet session says nothing, a
-    // session that is deciding something says what it decided, and there is no
-    // interval to choose.
-    const state = this.describe();
-    if (state !== this.#lastDescribed) {
-      this.#lastDescribed = state;
-      this.logger.info(state);
-    }
-  }
-
-  /**
-   * @param {string} address
-   */
-  #reconcileOne(address) {
-    // WHAT EXISTS IS ASKED OF THE DISK, HERE, EVERY TIME. The plan is arithmetic
-    // over what is made, what is being made and what is wanted, and the first of
-    // those is not this layer's to remember.
-    const coverage = this.#upToDateCoverage(address);
-    // A run that has ended and said nothing. One built here reports its own
-    // ending and is released by `noteEnded`; one ADOPTED from elsewhere — a
-    // session whose encoder stopped — has no such promise, and its claim would
-    // otherwise sit in the map for the life of the process, telling the plan
-    // that a stretch nobody is making is being made. Nothing would ever be
-    // started there again.
-    for (const run of this.runsOn(address)) {
-      if (!run.isAlive && !run.isStopping) {
-        this.noteEnded({
-          address,
-          run,
-          ending: ENCODE_EXIT.GONE,
-          because: "it is no longer running, and it did not say so"
-        });
-      }
-    }
-    // ITS INPUT WAS NOT THERE A MOMENT AGO, so nothing is placed yet. The sweep
-    // above still runs — a claim left by a dead run must be released whatever
-    // the reason — and only the placing waits. This is the one thing that makes
-    // the delay bind: it used to be timed against the dead run, which the plan
-    // does not consult, so a fresh run went to the same place as fast as ffmpeg
-    // could fail there.
-    //
-    // AND ONLY WHILE NOTHING IS PRODUCING THERE. A run still alive on this
-    // output is proof the input can be read, whatever a run beside it met, so
-    // the wait must not silence an output that is working.
-    if (this.#isQuiet(address) && this.runsOn(address).every((run) => !run.isAlive)) {
-      return;
-    }
-    // ONE MAP, NOT ONE WINDOW PER VIEWER PER ZONE.
-    //
-    // Two viewers a few seconds apart state stretches that overlap, and the plan
-    // puts one encoder on each stretch it is given — so unmerged windows buy an
-    // encoder per viewer for film they both want, which is the opposite of what
-    // sharing the output is for. Merged, the highest rank and the soonest time
-    // per number win and the stretches do not overlap, so one encoder serves
-    // everyone standing in front of it.
-    //
-    // Asked of the register, which is the thing that holds the windows. This
-    // used to reach into the layer that STATES them for the same arithmetic,
-    // which is the coupling the layer rule forbids; the arithmetic itself now
-    // lives where it belongs to nobody.
-    const windows = this.#demand.mapOn(address);
-    const live = this.runsOn(address).filter((run) => run.isAlive);
-    // Asked ONCE. It is arithmetic over measurements, but it also says out loud
-    // when the reason it cuts the budget changes, so asking it three times in
-    // one pass is three chances to say a thing that happened once.
-    const maxRuns = this.#withinMachine(address, live, this.#affordableOn(address, live));
-    // THE TERMS EVERY ARRIVAL IS COMPUTED FROM, named here so the line below can
-    // print them. A decision of this plan is `delay + (index - at) / rate +
-    // madeBetween * refetch` against a deadline, so without the rate and the two
-    // prices no recorded decision can be reproduced — which is what happened
-    // with the one-piece intervals of 2026-09-08: the rate was substituted six
-    // times from the speeds the session reported elsewhere and none of them gave
-    // the answer the plan had given.
-    const costs = this.#costs.seconds();
-    const refetchSecPerFilmSecond = this.refetchSecPerFilmSecond(address);
-    const speedX = this.#speedOn(address, live);
-    const actions = planEncoders({
-      coverage,
-      windows,
-      // The runs themselves. The plan is arithmetic and reads four numbers off
-      // each; what it hands back names the run by BEING it, so nothing has to
-      // invent a token to refer to one by.
-      runs: live,
-      maxRuns,
-      segmentSeconds: this.segmentSeconds,
-      // What a start and a kill cost, measured from this host's own runs rather
-      // than written into the code from one machine's reading. Zero until
-      // something has been measured, which is the same convention as the
-      // refetch price and is stated so the bias is known.
-      ...costs,
-      // What a second of film costs to fetch again, in seconds of swarm time.
-      // Answered by whoever measures the film's own byte rate and the swarm's;
-      // zero until they have, which makes driving through look cheaper than it
-      // is and is stated here so the bias is known.
-      refetchSecPerFilmSecond,
-      // How much slower one encoder runs beside others, read off this host's own
-      // startup measurement. A pure function over a measured table: beyond what
-      // was measured it holds the largest reading rather than continuing a curve
-      // nothing observed.
-      contentionPenaltyFor: (others) => contentionPenalty(others, this.contentionPenalties).penalty,
-      speedX
-    });
-
-    // A move is the plan taking a running encoder away from where it already
-    // stands, which is exactly the decision that was found wandering back and
-    // forth in the field on 2026-09-07 with no way to see why: the "because"
-    // line names the comparison in words, never the numbers it was decided
-    // from. Said here, once per reconcile, and only when a move actually
-    // 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.
-    //
-    // AND THE TERMS, for the same reason one step further: an interval says what
-    // was decided and the terms say why. `speed` is what every arrival is
-    // divided by, so a decision recorded without it can be re-read and not
-    // recomputed; `firstByte` and `kill` are what a start and a stop cost here;
-    // `refetch` is what a second of film costs to fetch again. A zero in the
-    // last three is a measurement nobody has taken, not a free operation, and it
-    // is printed so that reading it as free is a choice rather than an accident.
-    if (actions.some((action) => action.type !== "keep")) {
-      this.logger.info(
-        `encode-plan on ${address}: ` +
-        `${actions.map((action) => `${action.type} #${action.from ?? "?"}..#${action.to ?? "?"}`).join(", ")}` +
-        ` [speed=${speedX.toFixed(2)}x firstByte=${costs.firstByteWaitSec.toFixed(2)}s ` +
-        `kill=${costs.killCostSec.toFixed(2)}s refetch=${refetchSecPerFilmSecond.toFixed(3)}s/s ` +
-        `maxRuns=${maxRuns} live=${live.length}]`
-      );
-    }
-    if (actions.some((action) => action.type === "move")) {
-      this.logger.info(
-        `encode-plan move on ${address}: windows=${JSON.stringify(windows)} ` +
-        `maxRuns=${maxRuns} ` +
-        `live=${JSON.stringify(live.map((run) => ({ from: run.from, to: run.to, head: run.head, speedX: run.speedX })))}`
-      );
-    }
-    for (const action of actions) {
-      if (action.type === "stop") {
-        this.#stop(action.run, action.because);
-        continue;
-      }
-      if (action.type === "move") {
-        // A running encoder's position cannot be changed — it is fixed when the
-        // process starts — so a move is this one ending and another beginning
-        // where the material is missing. Both halves are recorded as what they
-        // are, which is why the ending of a moved run is not called normal.
-        this.#stop(action.run, action.because);
-        this.#start(address, action.from, action.to, action.because);
-        continue;
-      }
-      if (action.type === "start") {
-        this.#start(address, action.from, action.to, action.because);
-        continue;
-      }
-      // A run that stays keeps its claim current: the free stretch ahead of it
-      // may have shrunk since it was given one.
-      //
-      // THE CLAIM IS THE STRETCH IT WAS GIVEN, and there is one rule for that
-      // everywhere. It used to be narrowed here to what the run had already
-      // MADE whenever the run had no end, which meant a run claimed the single
-      // number it was writing and nothing beyond. The plan then read the road
-      // in front of a working encoder as free and started more encoders on it:
-      // three processes writing one directory with the same names, field
-      // 2026-09-06, and a piece of the film lost for good when the first of
-      // them was cleaned up after.
-      //
-      // The worry that narrowing was written for is real and is answered where
-      // it belongs — a viewer opening the same film further in must not find
-      // every number taken. That is the plan's business, and the plan can take
-      // road away from a run that has no end, because such a run carries no
-      // `-to` and simply stops when its head meets somebody else's claim.
-      coverage.claim(action.run, action.from, endOfRun({ from: action.from, to: action.to }));
-    }
-
-    // NOBODY IS MAKING WHAT SOMEBODY IS WAITING FOR. Said here, with the numbers
-    // the decision was taken from, because it is the one state in which a viewer
-    // waits for ever and every line above it reads as a healthy proxy.
-    //
-    // Field 2026-09-07, twice in one evening: the last word about an output was
-    // "the film is no worse off without it", and after it nothing — no run, no
-    // refusal, no answer to the browser's request for the header. The wait ended
-    // at the browser's own timeout with a message naming no cause, and the
-    // proxy's log named none either.
-    //
-    // SAID ONCE PER STATE, not once per pass. A stuck output is reconciled on
-    // every event that touches it, and a line repeated for as long as the state
-    // lasts is what buried the last one: 49 295 copies of `send queue stuck` in
-    // a 159 090-line file, 31 % of the log, all of one wedge.
-    const wanting = firstUnmetWant(coverage, windows);
-    const stillRunning = this.runsOn(address).filter((run) => run.isAlive);
-    if (wanting === null || stillRunning.length > 0) {
-      this.#lastUnmet.delete(address);
-    } else if (this.#lastUnmet.get(address) !== wanting) {
-      this.#lastUnmet.set(address, wanting);
-      const held = this.#segmentCoverage ? this.#segmentCoverage.filesHeld(address) : -1;
-      this.logger.warn(
-        `encode: #${wanting} of ${address} is wanted and NO ENCODER IS MAKING IT — ` +
-        `ready=${coverage.stats().ready} of ${coverage.segmentCount} ` +
-        `files=${held < 0 ? "?" : held} maxRuns=${maxRuns} ` +
-        `windows=${JSON.stringify(windows)}`
-      );
-    }
-  }
-
-  /**
-   * @param {string} address
-   * @param {number} from
-   * @param {number} to
-   * @param {string} because
-   */
-  #start(address, from, to, because) {
-    // The encoder is built here and now: whoever builds one waits for nothing,
-    // so it exists by the time this line returns. That is what makes the
-    // stretch held from this instant — this class knows what it is making
-    // because it has just made it, and no second encoder can be started for the
-    // same stretch on the next pass.
-    //
-    // It was not always so. The builder used to answer with nothing and start
-    // the encoder behind the answer, so the stretch stayed FREE for as long as
-    // that took, and every pass in between started another one: 684 starts in
-    // 482 seconds of field 2026-09-05, of which 973 answers said the encoder
-    // was not there yet — every start without exception.
-    //
-    // The run names itself: identity is a property of the thing, and two
-    // places minting names is how one stops being unique.
-    const run = this.makeRun({ address, from, to, because });
-    if (!run) {
-      // A refusal, not a wait: no session serves this output, or this position
-      // has failed to start too many times running.
-      this.logger.warn(`encode: no encoder could be made for #${from}..#${to} of ${address}`);
-      return;
-    }
-    const onThisOutput = this.#runs.get(address) ?? [];
-    onThisOutput.push(run);
-    this.#runs.set(address, onThisOutput);
-    // Nothing has to be un-proved when a run takes a stretch that has already
-    // been written. A piece is only ever NAMED as served once it is closed, and
-    // a run writing that number again writes under a working name until it
-    // closes its own — so the file standing there is a complete piece made by
-    // somebody, and serving it is right until the newer one replaces it whole.
-    // The claim comes after the run exists, and that is not a race: everything
-    // between is synchronous, and a process cannot say a word before the next
-    // tick. What it removes is the second act — building a run and starting it
-    // were two steps, and two owners each performed the second one.
-    this.coverageOf(address).claim(run, from, endOfRun({ from, to }));
-  }
-
-  /**
-   * The best figure this host has for one encoder on this output: the
-   * processing speed a run here has measured (`EncodeRun.speedX`), or what this
-   * output was last measured doing and the startup measurements predict
-   * (`startingSpeedFor`), which exists before any run has closed two pieces and
-   * after a restart. The run owns its speed; nothing here keeps a copy.
-   *
-   * It is the MACHINE's speed: input waits for the swarm are not in it. What
-   * the swarm delivers is the separate supply term
-   * (`refetchSecPerFilmSecond`).
-   *
-   * @param {string} address
-   * @param {{ speedX: number }[]} live
-   * @returns {number}
-   */
-  #speedOn(address, live) {
-    return Math.max(
-      live.reduce((best, run) => Math.max(best, run.speedX || 0), 0),
-      this.startingSpeedFor(address) || 0
-    );
-  }
-
-  /**
-   * How many encoders may run on this output, from every limit at once.
-   *
-   * The processor is one of them and is answered from outside, where the
-   * machine is measured. The other two are known here: what the swarm delivers,
-   * through the seconds of swarm time a second of film costs, and — once it is
-   * supplied — the memory the piece store may hold against what one encoder's
-   * reader keeps.
-   *
-   * Said out loud when it is not the processor that decided, because "why is
-   * there only one encoder" is otherwise a question no log can answer.
-   *
-   * @param {string} address
-   * @param {{ speedX: number }[]} live
-   * @returns {number}
-   */
-  #affordableOn(address, live) {
-    const byProcessor = Math.max(0, this.maxRunsFor(address));
-    const fastest = this.#speedOn(address, live);
-    const budget = affordableRuns({
-      byProcessor,
-      speedX: fastest,
-      refetchSecPerFilmSecond: this.refetchSecPerFilmSecond(address),
-      // How much slower one encoder runs beside others, read off this host's own
-      // startup measurement. A pure function over a measured table: beyond what
-      // was measured it holds the largest reading rather than continuing a curve
-      // nothing observed.
-      contentionPenaltyFor: (others) => contentionPenalty(others, this.contentionPenalties).penalty
-    });
-    if (budget.runs !== byProcessor && budget.because !== this.#lastBudgetReason.get(address)) {
-      this.#lastBudgetReason.set(address, budget.because);
-      this.logger.info(
-        `encode: ${budget.runs} encoder(s) on ${address.slice(0, 60)} — ${budget.because} ` +
-        `(the processor alone would allow ${byProcessor})`
-      );
-    }
-    return budget.runs;
-  }
-
-  /**
-   * The per-output limit, bounded by what the whole machine can still hold.
-   *
-   * The per-output answer is at least one whatever else is running; the
-   * machine's may be none, and that is the refusal: the output gets no encoder
-   * until one elsewhere ends. It is never below what already runs here, so a
-   * refusal stops a start and never takes an encoder away.
-   *
-   * Said out loud when the machine is what bound it, once per change.
-   *
-   * @param {string} address
-   * @param {object[]} live
-   * @param {number} perOutput
-   * @returns {number}
-   */
-  #withinMachine(address, live, perOutput) {
-    if (!this.admission) {
-      return perOutput;
-    }
-    const machine = this.admission.placesFor(address, live.length);
-    const runs = Math.min(perOutput, machine.runs);
-    const said = runs < perOutput ? `${runs}:${machine.because}` : "";
-    if (said !== (this.#lastMachineBound.get(address) ?? "")) {
-      if (said) {
-        this.logger.info(
-          `encode: ${runs} encoder(s) on ${address} — the whole machine holds no more ` +
-          `(${machine.because}; this output alone would be allowed ${perOutput})`
-        );
-        this.#lastMachineBound.set(address, said);
-      } else {
-        this.#lastMachineBound.delete(address);
-      }
-    }
-    return runs;
-  }
-
-  /**
-   * Take charge of a run this class did not start.
-   *
-   * The browser asks for a stream and a run begins for it, long before this
-   * class has an opinion. Left unknown, that run would be invisible to the plan
-   * — which would then start a second encoder over the same numbers, believing
-   * nothing was being made there. So whoever starts one hands it over, and from
-   * then on it is planned like any other.
-   *
-   * @param {string} address
-   * @param {{ id: string, from: number, to: number, head: number, speedX: number, isAlive: boolean, stop: (because: string) => void }} run
-   */
-  adopt(address, run) {
-    if (!run) {
-      return;
-    }
-    const onThisOutput = this.#runs.get(address) ?? [];
-    if (onThisOutput.includes(run)) {
-      return;
-    }
-    onThisOutput.push(run);
-    this.#runs.set(address, onThisOutput);
-    this.coverageOf(address).claim(run, run.from, endOfRun(run));
-  }
-
-  /**
-   * @param {object} run
-   * @param {string} because
-   */
-  #stop(run, because) {
-    run.stop(because);
-  }
-
-  /**
-   * A run has ended, however it ended. Its stretch goes back to the map — what
-   * it finished stays made — and the ending is counted.
-   *
-   * Wired by whoever builds the run, so that a run built outside this class is
-   * still accounted for.
-   *
-   * @param {import("../encode/EncodeRun.js").RunEnded} ended
-   */
-  noteEnded(ended) {
-    this.#lastState.set(ended.address, ended.run?.state ?? "IDLE");
-    if (ended.lastError) {
-      this.#lastError.set(ended.address, ended.lastError);
-    } else if (ended.because && ended.ending !== ENCODE_EXIT.COMPLETE) {
-      this.#lastError.set(ended.address, ended.because);
-    }
-    const progress = ended.run?.progress?.snapshot?.();
-    if (progress) {
-      this.#lastProgress.set(ended.address, progress);
-    }
-    this.#costs.note(ended);
-    // Exactly one ending is normal — the run reached the end of the stretch it
-    // was given and closed its last file. Every other leaves a piece open, and
-    // that piece is under this run's OWN working name, so clearing up after it
-    // is a name match: no stretch to search and no bytes to judge. Done for
-    // every ending, the normal one included, since a run that finished cleanly
-    // has nothing under a working name and the sweep then removes nothing.
-    this.#segmentCoverage?.clearUpAfter(ended.address, ended.from);
-    this.coverageOf(ended.address).release(ended.run);
-    const remaining = this.runsOn(ended.address).filter((run) => run !== ended.run);
-    if (remaining.length === 0) {
-      this.#runs.delete(ended.address);
-    } else {
-      this.#runs.set(ended.address, remaining);
-    }
-    this.#endings.set(ended.ending, (this.#endings.get(ended.ending) ?? 0) + 1);
-    this.#noteInputAvailability(ended);
-  }
-
-  /**
-   * Remember, per output, that its input was not there — and until when nothing
-   * is to be placed on it.
-   *
-   * **Why the plan has to hold this.** A run whose input has gone is not alive,
-   * so the plan sees the stretch it held as free and places another run there at
-   * once — and the next one dies the same way, because nothing about the state
-   * has changed. There WAS a delay for exactly this, doubling from 2 s to 15 s,
-   * and it governed only the dead run's own retry while the plan went on placing
-   * fresh ones beside it. The comment beside that timer predicted this in as
-   * many words and the code did not prevent it. Field 2026-09-12: 2432 ffmpeg
-   * starts in 23 minutes, one every 0.57 s, for 61 minutes, against a delay that
-   * had long since reached its 15 s cap.
-   *
-   * So the delay lives where the decision is taken. It is not a cure for the
-   * input being away — that is the store's claim being withdrawn and the piece
-   * being fetched again — it is what stops one absent input from costing a
-   * thousand processes and a quarter of a million log lines while it is away.
-   *
-   * @param {{ address: string, ending: string }} ended
-   * @returns {void}
-   */
-  #noteInputAvailability(ended) {
-    if (ended.ending !== ENCODE_EXIT.INPUT_LOST) {
-      // CLEARED ONLY BY PROOF THAT THE INPUT WAS THERE, which is a segment
-      // having come out of it. Any other ending was nearly the rule here and is
-      // wrong: at the moment of failure several runs end at once, and one of
-      // them ending `gone` or `stopped` without producing a thing says nothing
-      // about the input — it would have lifted the wait the one beside it had
-      // just set, which is the storm again with an extra step.
-      const produced =
-        ended.firstOutputMs !== null && ended.firstOutputMs !== undefined
-          ? true
-          : Number.isFinite(ended.reached) && Number.isFinite(ended.from) && ended.reached >= ended.from;
-      if (produced) {
-        this.#inputLostAttempts.delete(ended.address);
-        this.#quietUntil.delete(ended.address);
-      }
-      return;
-    }
-    const attempts = (this.#inputLostAttempts.get(ended.address) ?? 0) + 1;
-    this.#inputLostAttempts.set(ended.address, attempts);
-    const delayMs = Math.min(
-      INPUT_QUIET_MAX_MS,
-      INPUT_QUIET_BASE_MS * 2 ** Math.min(attempts - 1, 6)
-    );
-    this.#quietUntil.set(ended.address, this.now() + delayMs);
-    this.logger.info(
-      `encode-plan on ${ended.address}: its input was not there (attempt ${attempts}) — ` +
-      `placing nothing for ${Math.round(delayMs / 1000)}s`
-    );
-    // THE WAKE-UP, because a plan that refuses to act needs something to ask it
-    // again: nothing about the state changes while the data is away, so no event
-    // would arrive to reconsider it.
-    const timer = setTimeout(() => {
-      this.#quietTimers.delete(ended.address);
-      this.planSoon();
-    }, delayMs);
-    timer.unref?.();
-    const previous = this.#quietTimers.get(ended.address);
-    if (previous) {
-      clearTimeout(previous);
-    }
-    this.#quietTimers.set(ended.address, timer);
-  }
-
-  /**
-   * Whether this output is still waiting before anything may be placed on it.
-   *
-   * A boolean rather than the milliseconds left: the figure had one reader and
-   * that reader only asked whether it was above zero, so it was a number
-   * computed and thrown away. How long the wait is was said when it began.
-   *
-   * @param {string} address
-   * @returns {boolean}
-   */
-  #isQuiet(address) {
-    const until = this.#quietUntil.get(address);
-    if (!Number.isFinite(until)) {
-      return false;
-    }
-    if (until - this.now() <= 0) {
-      this.#quietUntil.delete(address);
-      return false;
-    }
-    return true;
-  }
-
-  /**
-   * Forget everything remembered about an output nobody is producing for.
-   *
-   * Three maps are keyed by address, and an output that goes away leaves an
-   * entry in each for the life of the process. Small, and exactly the shape of
-   * accumulation this layer was built to remove from the session.
-   *
-   * @param {string} address
-   * @returns {void}
-   */
-  #forgetInputState(address) {
-    this.#inputLostAttempts.delete(address);
-    this.#quietUntil.delete(address);
-    const timer = this.#quietTimers.get(address);
-    if (timer) {
-      clearTimeout(timer);
-      this.#quietTimers.delete(address);
-    }
-  }
-
-  /**
-   * How runs have ended over the life of this process, by cause.
-   *
-   * The abnormal classes are meant to stand at zero. Without the count,
-   * "we understand why it ended" is indistinguishable from "we noticed it once".
-   *
-   * @returns {Record<string, number>}
-   */
-  endings() {
-    /** @type {Record<string, number>} */
-    const tally = {};
-    for (const ending of Object.values(ENCODE_EXIT)) {
-      tally[ending] = this.#endings.get(ending) ?? 0;
-    }
-    return tally;
-  }
-
-  /**
-   * One line saying what this proxy is encoding and whether anybody is waiting.
-   *
-   * `waiting` is the point of it: a proxy with encoders running and a viewer
-   * still stopped at a segment nobody is making is the failure this layer was
-   * built to remove, and it is visible here rather than inferred from a log.
-   *
-   * @returns {string}
-   */
-  describe() {
-    const parts = [];
-    for (const address of new Set([...this.#demand.addresses(), ...this.#runs.keys()])) {
-      const coverage = this.coverageOf(address);
-      const stated = this.#demand.mapOn(address);
-      const windows = stated.map((zone) => ({ from: zone.from, to: zone.to }));
-      const waiting = firstUnmetWant(coverage, windows);
-      const runs = this.runsOn(address)
-        .map((run) => `#${run.head}..#${run.to}@${run.speedX.toFixed(1)}x`)
-        .join(" ");
-      // The zones as they were stated, with their order, so a plan that is
-      // working at the wrong end of the film is visible rather than inferred.
-      const zones = [...stated]
-        .sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.from - right.from)
-        .map((w) => `p${w.priority ?? 0}:#${w.from}..#${w.to}`)
-        .join(" ");
-      // THE WHOLE ADDRESS. Cut to sixty characters, every output of one film
-      // printed the same string — the picture, its quality steps and each
-      // soundtrack are told apart only by the tail — so three lines of this
-      // could not be matched to the three things they describe. Read on
-      // 2026-09-07 while accounting for a session that produced nothing, and
-      // the accounting had to be done by which line carried a run.
-      //
-      // And WHAT THE DISK HOLDS beside what is proven closed. They are two
-      // different statements: files with nothing proving them closed reads as a
-      // reporting fault, no files at all reads as an output yet to be made, and
-      // the difference decides where to look.
-      const held = this.#segmentCoverage ? this.#segmentCoverage.filesHeld(address) : -1;
-      // AND WHETHER THE MAP IS BEING SERVED IN ITS OWN ORDER. The zones say
-      // what matters most; this says what the viewer actually waited for, by
-      // band. Waits at `now` are the ones that cost a spinner, and until this
-      // existed there was no figure anywhere saying whether the urgent zone was
-      // served first — the map could have been read backwards and every line
-      // above would have looked the same.
-      const served = this.#describeWaits(address);
-      parts.push(
-        `${address} ready=${coverage.stats().ready}` +
-        `${held < 0 ? "" : ` of ${held} file(s) on disk`} ` +
-        `zones=[${zones}] runs=[${runs}] ` +
-        `waiting=${waiting === null ? "nobody" : `#${waiting}`}` +
-        `${served ? ` served[${served}]` : ""}`
-      );
-    }
-    const tally = this.endings();
-    const endings = Object.entries(tally)
-      .map(([cause, count]) => `${cause}=${count}`)
-      .join(" ");
-    return `encode: ${parts.length === 0 ? "nothing wanted" : parts.join(" | ")} :: endings ${endings}`;
-  }
-}
+/**
+ * @file How many encoders run on this proxy, on which outputs, and over which
+ * stretches.
+ *
+ * The application layer over `encode/`. It holds four things and owns none of
+ * their rules:
+ *
+ * 1. what viewers want (`SegmentDemand`), stated once each and read as a union;
+ * 2. what has been made and what is being made, one `CoverageMap` per output;
+ * 3. the encoders that are running (`EncodeRun`), each over a stretch;
+ * 4. a tally of how every run ended, which is what makes "abnormal endings do
+ *    not happen" a number rather than an impression.
+ *
+ * The decision itself is `EncodePlan.planEncoders`, from numbers alone. This
+ * carries it out, and everything it cannot know is injected: how many encoders
+ * this machine can afford, how a run is built for a given stretch, and which
+ * segments already exist.
+ *
+ * **No viewer reaches the decision.** A viewer states a window and is forgotten
+ * as a name; what the plan sees is a union of windows. That is the rule the
+ * layer exists for, stated by the user 2026-09-04: requests come from any
+ * viewers in any number, encoders are managed to suit them, and viewers get the
+ * result when it is ready.
+ */
+
+import { CoverageMap } from "./CoverageMap.js";
+import { firstUnmetWant, planEncoders } from "./EncodePlan.js";
+import { endOfRun } from "./EncodeRun.js";
+import { ENCODE_EXIT } from "./encode-exit.js";
+import { affordableRuns } from "./run-budget.js";
+import { RunCosts } from "./run-costs.js";
+import { contentionPenalty } from "./contention.js";
+import { SegmentDemand } from "./SegmentDemand.js";
+import { runStateOf } from "./encode-run-state.js";
+
+/**
+ * @typedef {Object} SegmentCoverage
+ * @property {(address: string) => number[]} provenNumbers
+ * @property {(address: string, index: number) => void} announce
+ * @property {(address: string) => number} filesHeld
+ * @property {(address: string, startedAt: number) => number} clearUpAfter
+ */
+
+/**
+ * How long nothing is placed on an output whose input has just gone, and the
+ * ceiling that doubling reaches.
+ *
+ * Both are chosen, and are named here as chosen rather than dressed as
+ * measurements: what they bound is not how long the data takes to come back —
+ * that is the swarm's business and nobody here can know it — but how often it
+ * is worth asking. They replace the same two figures, with the same values,
+ * that lived in the session manager and governed only the dead run's own retry
+ * while the plan placed fresh runs beside it every half second.
+ */
+const INPUT_QUIET_BASE_MS = 2_000;
+const INPUT_QUIET_MAX_MS = 15_000;
+const START_FAST_FAIL_MS = 2_000;
+const MAX_FAILED_STARTS = 3;
+
+export class EncodeOrchestrator {
+  /** Derived priority maps. Discardable and rebuilt from viewer state. */
+  #demand = new SegmentDemand();
+  /** @type {(address: string) => string} */
+  #describeWaits = () => "";
+
+  /** Output address to what has been made of it. @type {Map<string, CoverageMap>} */
+  #coverage = new Map();
+
+  /** @type {SegmentCoverage | null} */
+  #segmentCoverage = null;
+
+  /** Output address to the runs on it. @type {Map<string, import("../encode/EncodeRun.js").EncodeRun[]>} */
+  #runs = new Map();
+
+  /** Last state after an output has no registered run. @type {Map<string, string>} */
+  #lastState = new Map();
+
+  /** Last encoder error per output. @type {Map<string, string>} */
+  #lastError = new Map();
+
+  /** Last progress snapshot per output after its run ends. @type {Map<string, object>} */
+  #lastProgress = new Map();
+
+  /** Consecutive fast failures at one position, per output. @type {Map<string, { at: number, count: number }>} */
+  #failedStarts = new Map();
+
+  /** How runs have ended, by cause. @type {Map<string, number>} */
+  #endings = new Map();
+
+  /**
+   * How many times in a row an output's run has died because its input was not
+   * there. Cleared only by a run that PRODUCED something, which is the only
+   * proof that the input can be read — see `#noteInputAvailability`.
+   *
+   * @type {Map<string, number>}
+   */
+  #inputLostAttempts = new Map();
+
+  /** Output address to the time before which nothing is placed on it. @type {Map<string, number>} */
+  #quietUntil = new Map();
+
+  /** The wake-up per output, so a quiet output is reconsidered. @type {Map<string, NodeJS.Timeout>} */
+  #quietTimers = new Map();
+
+  /** The last state said out loud, so an unchanged state is not repeated. */
+  #lastDescribed = "";
+
+  /** What a stop and a start have cost on this host. */
+  #costs = new RunCosts();
+
+  /**
+   * What starting and stopping an encoder was measured to cost on this host,
+   * before any viewer existed. Told once; real runs replace it as they end.
+   *
+   * @param {{ firstByteWaitSec: number, killCostSec: number } | null} measured
+   * @returns {void}
+   */
+  noteStartupCosts(measured) {
+    this.#costs.noteStartup(measured);
+  }
+
+  /** Derived segment demand for one output, copied from the discardable cache. */
+  wantedSegmentsOn(address) {
+    return [...this.#demand.mapOn(address)];
+  }
+
+  /** The last reason a budget was cut, so the same one is not said twice. */
+  #lastBudgetReason = new Map();
+
+  /** The last unmet want said out loud, so a stuck one is said once. */
+  #lastUnmet = new Map();
+
+  /** The last time the machine bound an output's encoders, so it is said once. */
+  #lastMachineBound = new Map();
+
+  /**
+   * @param {object} params
+   * @param {(address: string) => number} params.maxRunsFor - How many encoders
+   *   this machine can afford on one output. The same arithmetic that decides
+   *   the quality offer; measured per host, never chosen here.
+   * @param {(params: { address: string, from: number, to: number, because: string }) =>
+   *   import("../encode/EncodeRun.js").EncodeRun} params.makeRun - Build a run
+   *   for a stretch. What to read, what to map and how to cut belong to whoever
+   *   knows the source.
+   * @param {number} params.segmentSeconds
+   * @param {import("../encode/contention.js").ContentionPenalties | null}
+   *   [params.contentionPenalties] - How much slower one encoder runs beside
+   *   others, MEASURED on this host at startup and keyed by how many others
+   *   there are. Null until something has measured it, and then the penalty is
+   *   1 — a number invented here would be the same mistake as an invented
+   *   encoding speed.
+   * @param {{ info: (line: string) => void, warn: (line: string) => void }} params.logger
+   * @param {() => number} [params.now]
+   * @param {(address: string) => string} [params.describeWaits] - What the
+   *   viewers actually waited for on this output, by band, for the state line.
+   *   HANDED IN: what anybody waited for belongs to the priority layer, and
+   *   this one may be asked about encoders with no ledger, no clock and no
+   *   viewer anywhere. Absent, the line simply does not carry it.
+   * @param {SegmentCoverage | null} [params.segmentCoverage]
+   */
+  constructor({
+    maxRunsFor,
+    makeRun,
+    segmentSeconds,
+    contentionPenalties = null,
+    refetchSecPerFilmSecond = () => 0,
+    startingSpeedFor = () => 0,
+    segmentCoverage = null,
+    planSoon = null,
+    describeWaits = null,
+    admission = null,
+    logger,
+    now
+  }) {
+    // HOW MANY ENCODERS THE WHOLE MACHINE HOLDS, across outputs. `maxRunsFor`
+    // answers for one output as though it were alone; this is what refuses the
+    // encoder that would slow everybody below realtime. Absent in a check that
+    // is about one output, and then only the per-output limit binds.
+    this.admission = admission && typeof admission.placesFor === "function" ? admission : null;
+    this.#describeWaits = typeof describeWaits === "function" ? describeWaits : () => "";
+    // Only the segment facts and operations this planner needs cross the
+    // storage boundary; the concrete storage remains in the server assembly.
+    this.#segmentCoverage = segmentCoverage;
+    this.maxRunsFor = maxRunsFor;
+    // Seconds of swarm time per second of film: what re-encoding material that
+    // already exists costs the download, over and above the encoder's own time.
+    // Injected, because the film's byte rate and the swarm's are measured
+    // elsewhere and this class must not reach for them.
+    this.refetchSecPerFilmSecond = refetchSecPerFilmSecond;
+    // Measured per host: what a second encoder costs the first. Unmeasured is 1,
+    // and then only the budget bounds how many there are.
+    this.contentionPenalties = contentionPenalties instanceof Map ? contentionPenalties : null;
+    // WHAT THIS HOST ENCODES AT BEFORE ANY RUN HAS REPORTED. The startup
+    // benchmark measures it — a real pipeline over real clips, before a viewer
+    // exists — so the plan is never asked to compare arrivals with no speed to
+    // compute them from. Every run that then works refines it.
+    this.startingSpeedFor = startingSpeedFor;
+    this.makeRun = makeRun;
+    this.segmentSeconds = segmentSeconds;
+    this.logger = logger;
+    this.now = typeof now === "function" ? now : Date.now;
+    // Asked for, not commanded: this class decides, and something else owns the
+    // loop that calls it. Absent in a test, where the clock is the test's own.
+    this.planSoon = typeof planSoon === "function" ? planSoon : () => undefined;
+  }
+
+  /**
+   * The map of one output, made on first mention.
+   *
+   * @param {string} address
+   * @returns {CoverageMap}
+   */
+  coverageOf(address) {
+    let map = this.#coverage.get(address);
+    if (!map) {
+      map = new CoverageMap();
+      this.#coverage.set(address, map);
+    }
+    return map;
+  }
+
+  /**
+   * Put the map's picture of what is ready back in step with the disk.
+   *
+   * ONE AUTHORITY ON WHAT EXISTS, AND IT IS THE STORE. The map holds no memory
+   * of readiness between calls: it is handed the whole answer, replacing
+   * whatever it had, immediately before anything is decided from it. So a
+   * segment whose file was discarded with the run that had it open, dropped to
+   * make room, or reopened by a run restarting on it stops being ready in the
+   * same breath — without anything having to notice and say so.
+   *
+   * The map used to be filled from outside, by the session manager, with a
+   * method that only ever added. Nothing anywhere took a number back. Field
+   * 2026-09-07: the map claimed all 482 segments of a film while the directory
+   * held nothing, so every arrangement scored perfect, the only encoder was
+   * stopped as unnecessary and none was placed again — two sessions in a row
+   * with no picture at all.
+   *
+   * A store is optional here only in the sense that an authority which was not
+   * supplied cannot be consulted: without one the map keeps what it was told
+   * directly, which is how this class is exercised with plain numbers.
+   *
+   * @param {string} address
+   * @returns {CoverageMap}
+   */
+  #upToDateCoverage(address) {
+    const coverage = this.coverageOf(address);
+    if (this.#segmentCoverage) {
+      coverage.setReady(this.#segmentCoverage.provenNumbers(address));
+    }
+    return coverage;
+  }
+
+  /**
+   * Where a run started here must stop: the free stretch in front of it.
+   *
+   * Asked of the one map, brought up to date first. It used to be worked out by
+   * the session manager, which reached into this layer for the map and into the
+   * store for what was on the disk and put the two together itself — one fact
+   * with two owners and a third party carrying it between them, which is how the
+   * two came to disagree.
+   *
+   * @param {object} params
+   * @param {string} params.address
+   * @param {number} params.from - Where the run will start.
+   * @param {object | null} [params.exceptRun] - The run being replaced, whose
+   *   own claim is not somebody else's material.
+   * @param {number} [params.segmentCount] - The output's length, when known.
+   * @returns {number} The last number to work through, or `-1` for the end of
+   *   the film.
+   */
+  freeStretchEnd({ address, from, exceptRun = null, segmentCount = 0 }) {
+    if (!address) {
+      return -1;
+    }
+    if (segmentCount > 0) {
+      this.coverageOf(address).setSegmentCount(segmentCount);
+    }
+    const coverage = this.#upToDateCoverage(address);
+    const start = Math.max(0, from);
+    const free = coverage.freeRunFrom(start, exceptRun);
+    if (!Number.isFinite(free)) {
+      return -1;
+    }
+    const end = start + Math.max(1, free) - 1;
+    return segmentCount > 0 && end >= segmentCount - 1 ? -1 : end;
+  }
+
+  /**
+   * @param {string} address
+   * @returns {import("../encode/EncodeRun.js").EncodeRun[]}
+   */
+  runsOn(address) {
+    return this.#runs.get(address) ?? [];
+  }
+
+  /**
+   * The aggregate state of this output's current runs, or its last ending when
+   * none remain.
+   *
+   * @param {string} address
+   * @returns {string}
+   */
+  stateOf(address) {
+    const runs = this.runsOn(address);
+    return runs.length > 0 ? runStateOf(runs) : (this.#lastState.get(address) ?? runStateOf([]));
+  }
+
+  /** @param {string} address @returns {string} */
+  errorOf(address) {
+    return this.#lastError.get(address) ?? "";
+  }
+
+  /**
+   * Progress of the live run that covers a position, or the most recently
+   * updated run when no position is supplied.
+   *
+   * @param {string} address
+   * @param {number | null} [index]
+   * @returns {object | null}
+   */
+  progressOf(address, index = null) {
+    const live = this.runsOn(address).filter((run) => run.isAlive);
+    const covering = Number.isInteger(index)
+      ? live.filter((run) => run.from <= index && endOfRun(run) >= index)
+      : live;
+    const candidates = covering.length > 0 ? covering : live;
+    const run = [...candidates].sort(
+      (left, right) => (right.progress?.updatedAt ?? 0) - (left.progress?.updatedAt ?? 0)
+    )[0];
+    return run?.progress?.snapshot?.() ?? this.#lastProgress.get(address) ?? null;
+  }
+
+  /**
+   * Whether another start at this position is allowed.
+   *
+   * @param {string} address
+   * @param {number} from
+   * @returns {boolean}
+   */
+  mayStartAt(address, from) {
+    const failed = this.#failedStarts.get(address);
+    return failed?.at !== from || failed.count < MAX_FAILED_STARTS;
+  }
+
+  /**
+   * Record whether a failed run died before it performed sustained work.
+   *
+   * @param {string} address
+   * @param {number} from
+   * @param {number} livedMs
+   * @returns {{ at: number, count: number, blocked: boolean, limit: number, fastMs: number }}
+   */
+  noteStartFailure(address, from, livedMs) {
+    if (!(livedMs < START_FAST_FAIL_MS)) {
+      this.#failedStarts.delete(address);
+      return { at: -1, count: 0, blocked: false, limit: MAX_FAILED_STARTS, fastMs: START_FAST_FAIL_MS };
+    }
+    const previous = this.#failedStarts.get(address);
+    const next = {
+      at: from,
+      count: previous?.at === from ? previous.count + 1 : 1
+    };
+    this.#failedStarts.set(address, next);
+    return {
+      ...next,
+      blocked: next.count >= MAX_FAILED_STARTS,
+      limit: MAX_FAILED_STARTS,
+      fastMs: START_FAST_FAIL_MS
+    };
+  }
+
+  /**
+   * An output that no longer exists and has no run left on it.
+   *
+   * How its last run ended, what went wrong and which position kept failing are
+   * facts about THAT output. The name follows from the key, so the next output
+   * with the same parameters has the same address; kept, those facts would
+   * greet it as its own — a failed ending makes its first wait throw before any
+   * encoder is placed, and nothing would ever clear it.
+   *
+   * @param {string} address
+   */
+  forgetOutput(address) {
+    if (this.runsOn(address).length > 0) {
+      return;
+    }
+    this.#lastState.delete(address);
+    this.#lastError.delete(address);
+    this.#lastProgress.delete(address);
+    this.#failedStarts.delete(address);
+  }
+
+  /** @param {string} address @returns {{ at: number, count: number, blocked: boolean, limit: number }} */
+  startFailureOf(address) {
+    const failure = this.#failedStarts.get(address) ?? { at: -1, count: 0 };
+    return { ...failure, blocked: failure.count >= MAX_FAILED_STARTS, limit: MAX_FAILED_STARTS };
+  }
+
+  /**
+   * What the map says about one segment of one output, and about the map it
+   * sits in.
+   *
+   * Asked by whoever is holding a request and measuring the wait: a wait means
+   * one thing at the top rank and another at the bottom, and telling them apart
+   * needs both the segment's own rank and the highest rank stated, since a rank
+   * is a position in this map and not an absolute number.
+   *
+   * AND AN EMPTY MAP IS NOT AN ANSWER. A top rank of zero says the map has not
+   * been built yet — a session created a moment ago, before the first pass —
+   * and that is a different thing from "nobody is coming". Conflated, every
+   * request behind the run reads as absent for as long as a fresh session has
+   * no map.
+   *
+   * It exists because the one caller reached through this object into the store
+   * behind it. A reach like that is how a store becomes the surface: the day it
+   * changes, a caller two layers away breaks for a reason it cannot see.
+   *
+   * @param {string} address
+   * @param {number} index
+   * @returns {{ rank: number, topRank: number }}
+   */
+  rankAt(address, index) {
+    return this.#demand.rankOf(address, index);
+  }
+
+  /**
+   * How many encoder processes are running on this machine right now, over
+   * every output.
+   *
+   * ONE COUNT, and it is this class's because this class is what makes and
+   * unmakes runs: adopted the moment one exists and forgotten the moment one
+   * ends, both synchronously. The session manager answered the same question
+   * twice by walking its own registry — once per SESSION and once per RUN —
+   * which agreed only while a session held at most one run. It has held several
+   * since the plan was allowed to place them, and the per-session count is the
+   * wrong one of the two wherever they differ: what a second encoder costs was
+   * measured between ffmpeg PROCESSES, not between outputs.
+   *
+   * A SUSPENDED run is not counted. It is stopped where it stands and is using
+   * nothing; a cost measured beside it is a cost measured alone.
+   *
+   * @returns {number}
+   */
+  /**
+   * How many encoders are alive on each output, suspended ones included.
+   *
+   * What the machine-wide admission counts as holding a place. A suspended
+   * encoder is counted here, unlike in {@link runningCount}: that one answers
+   * what is competing for the processor this instant, this one what the
+   * machine is committed to — and a parked encoder resumes the moment the
+   * viewer catches up.
+   *
+   * @returns {Map<string, number>}
+   */
+  liveRunsByAddress() {
+    /** @type {Map<string, number>} */
+    const byAddress = new Map();
+    for (const [address, runs] of this.#runs) {
+      const alive = runs.filter((run) => run.isAlive).length;
+      if (alive > 0) {
+        byAddress.set(address, alive);
+      }
+    }
+    return byAddress;
+  }
+
+  runningCount() {
+    let running = 0;
+    for (const runs of this.#runs.values()) {
+      for (const run of runs) {
+        if (run.isAlive && !run.isSuspended) {
+          running += 1;
+        }
+      }
+    }
+    return running;
+  }
+
+  /**
+   * How long an output is, once its playlist is known.
+   *
+   * @param {string} address
+   * @param {number} segmentCount
+   */
+  setSegmentCount(address, segmentCount) {
+    this.coverageOf(address).setSegmentCount(segmentCount);
+  }
+
+  /**
+   * Segments that already exist — from a previous life of this process, or
+   * because somebody else made them. Told to the map, which is what stops an
+   * encoder being started to make them again.
+   *
+   * @param {string} address
+   * @param {Iterable<number>} indexes
+   */
+  noteAlreadyMade(address, indexes) {
+    for (const index of indexes) {
+      this.noteProduced(address, index);
+    }
+  }
+
+  /**
+   * A viewer states what it is waiting for. Replaces whatever it said before.
+   *
+   * @param {object} params
+   * @param {string} params.claimant
+   * @param {string} params.address
+   * @param {number} params.from
+   * @param {number} params.to
+   * @param {number} [params.priority] - Higher is sooner. One viewer states
+   *   several stretches at once — what must be ready before they set off, what
+   *   is reachable while they watch it, the rest of the track — and the filling
+   *   takes them in this order. Absent means one undifferentiated want, which
+   *   is what a caller that knows only a position states.
+   */
+  /**
+   * What is wanted of one output, in its own segment numbers.
+   *
+   * ONE MAP, ALREADY MERGED, AND WITH NOBODY'S NAME ON IT. It is built once per
+   * film by the layer that knows where the viewers are; this layer receives it
+   * converted into an output's own numbering and never asks who is in it.
+   *
+   * That replaced a window per viewer per band stated here and merged here,
+   * which was the same work done twice in two layers, with the viewer's name as
+   * the key of a claim — against the rule that the encoding and the viewer are
+   * not connected at all.
+   *
+   * An empty map says nobody is coming anywhere in this output, and the plan
+   * stops its encoders for it. Nothing has to be released when somebody leaves:
+   * the map that arrives next simply does not have them in it.
+   *
+   * @param {string} address
+   * @param {{ from: number, to: number, priority: number, withinSeconds: number }[]} zones
+   */
+  notePriorityMap(address, zones) {
+    this.#demand.state(address, zones);
+    // NOBODY IS COMING HERE, so what was remembered about this output's input
+    // is about nobody. Kept, those three entries would stay for the life of the
+    // process, and the wait they describe would greet whoever opens this output
+    // next — a viewer arriving is new information, and one attempt for them is
+    // right whatever the last one met.
+    if (!Array.isArray(zones) || zones.length === 0) {
+      this.#forgetInputState(address);
+    }
+  }
+
+  /**
+   * A segment has been finished, by whichever run made it.
+   *
+   * @param {string} address
+   * @param {number} index
+   */
+  noteProduced(address, index) {
+    // Nothing is told to the store: by the time this is called the piece is
+    // ALREADY under its served name, because the rename is what closing it
+    // means. A statement kept beside the disk would be a second owner of one
+    // fact, which removed the stale second owner from the coverage map.
+    this.coverageOf(address).markReady(index);
+    this.#segmentCoverage?.announce?.(address, index);
+    for (const run of this.runsOn(address)) {
+      run.noteProduced(index);
+    }
+  }
+
+  /**
+   * Decide and act, for every output anybody wants anything of and every output
+   * that still has an encoder on it.
+   *
+   * Safe to call as often as anything changes: the plan is a function of the
+   * state, so a pass that finds nothing to change does nothing.
+   */
+  reconcile() {
+    const addresses = new Set([...this.#demand.addresses(), ...this.#runs.keys()]);
+    for (const address of addresses) {
+      this.#reconcileOne(address);
+    }
+    // WHAT THIS CLASS BELIEVES, said by this class. `describe()` was written
+    // and called from nowhere, so on 2026-09-05 the question "why did the plan
+    // not see the gap the viewer was stopped at" had to be answered by
+    // inference from start and stop lines, and was not answered at all.
+    //
+    // Printed on CHANGE rather than on a timer: a quiet session says nothing, a
+    // session that is deciding something says what it decided, and there is no
+    // interval to choose.
+    const state = this.describe();
+    if (state !== this.#lastDescribed) {
+      this.#lastDescribed = state;
+      this.logger.info(state);
+    }
+  }
+
+  /**
+   * @param {string} address
+   */
+  #reconcileOne(address) {
+    // WHAT EXISTS IS ASKED OF THE DISK, HERE, EVERY TIME. The plan is arithmetic
+    // over what is made, what is being made and what is wanted, and the first of
+    // those is not this layer's to remember.
+    const coverage = this.#upToDateCoverage(address);
+    // A run that has ended and said nothing. One built here reports its own
+    // ending and is released by `noteEnded`; one ADOPTED from elsewhere — a
+    // session whose encoder stopped — has no such promise, and its claim would
+    // otherwise sit in the map for the life of the process, telling the plan
+    // that a stretch nobody is making is being made. Nothing would ever be
+    // started there again.
+    for (const run of this.runsOn(address)) {
+      if (!run.isAlive && !run.isStopping) {
+        this.noteEnded({
+          address,
+          run,
+          ending: ENCODE_EXIT.GONE,
+          because: "it is no longer running, and it did not say so"
+        });
+      }
+    }
+    // ITS INPUT WAS NOT THERE A MOMENT AGO, so nothing is placed yet. The sweep
+    // above still runs — a claim left by a dead run must be released whatever
+    // the reason — and only the placing waits. This is the one thing that makes
+    // the delay bind: it used to be timed against the dead run, which the plan
+    // does not consult, so a fresh run went to the same place as fast as ffmpeg
+    // could fail there.
+    //
+    // AND ONLY WHILE NOTHING IS PRODUCING THERE. A run still alive on this
+    // output is proof the input can be read, whatever a run beside it met, so
+    // the wait must not silence an output that is working.
+    if (this.#isQuiet(address) && this.runsOn(address).every((run) => !run.isAlive)) {
+      return;
+    }
+    // ONE MAP, NOT ONE WINDOW PER VIEWER PER ZONE.
+    //
+    // Two viewers a few seconds apart state stretches that overlap, and the plan
+    // puts one encoder on each stretch it is given — so unmerged windows buy an
+    // encoder per viewer for film they both want, which is the opposite of what
+    // sharing the output is for. Merged, the highest rank and the soonest time
+    // per number win and the stretches do not overlap, so one encoder serves
+    // everyone standing in front of it.
+    //
+    // Asked of the register, which is the thing that holds the windows. This
+    // used to reach into the layer that STATES them for the same arithmetic,
+    // which is the coupling the layer rule forbids; the arithmetic itself now
+    // lives where it belongs to nobody.
+    const windows = this.#demand.mapOn(address);
+    const live = this.runsOn(address).filter((run) => run.isAlive);
+    // Asked ONCE. It is arithmetic over measurements, but it also says out loud
+    // when the reason it cuts the budget changes, so asking it three times in
+    // one pass is three chances to say a thing that happened once.
+    const maxRuns = this.#withinMachine(address, live, this.#affordableOn(address, live));
+    // THE TERMS EVERY ARRIVAL IS COMPUTED FROM, named here so the line below can
+    // print them. A decision of this plan is `delay + (index - at) / rate +
+    // madeBetween * refetch` against a deadline, so without the rate and the two
+    // prices no recorded decision can be reproduced — which is what happened
+    // with the one-piece intervals of 2026-09-08: the rate was substituted six
+    // times from the speeds the session reported elsewhere and none of them gave
+    // the answer the plan had given.
+    const costs = this.#costs.seconds();
+    const refetchSecPerFilmSecond = this.refetchSecPerFilmSecond(address);
+    const speedX = this.#speedOn(address, live);
+    const actions = planEncoders({
+      coverage,
+      windows,
+      // The runs themselves. The plan is arithmetic and reads four numbers off
+      // each; what it hands back names the run by BEING it, so nothing has to
+      // invent a token to refer to one by.
+      runs: live,
+      maxRuns,
+      segmentSeconds: this.segmentSeconds,
+      // What a start and a kill cost, measured from this host's own runs rather
+      // than written into the code from one machine's reading. Zero until
+      // something has been measured, which is the same convention as the
+      // refetch price and is stated so the bias is known.
+      ...costs,
+      // What a second of film costs to fetch again, in seconds of swarm time.
+      // Answered by whoever measures the film's own byte rate and the swarm's;
+      // zero until they have, which makes driving through look cheaper than it
+      // is and is stated here so the bias is known.
+      refetchSecPerFilmSecond,
+      // How much slower one encoder runs beside others, read off this host's own
+      // startup measurement. A pure function over a measured table: beyond what
+      // was measured it holds the largest reading rather than continuing a curve
+      // nothing observed.
+      contentionPenaltyFor: (others) => contentionPenalty(others, this.contentionPenalties).penalty,
+      speedX
+    });
+
+    // A move is the plan taking a running encoder away from where it already
+    // stands, which is exactly the decision that was found wandering back and
+    // forth in the field on 2026-09-07 with no way to see why: the "because"
+    // line names the comparison in words, never the numbers it was decided
+    // from. Said here, once per reconcile, and only when a move actually
+    // 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.
+    //
+    // AND THE TERMS, for the same reason one step further: an interval says what
+    // was decided and the terms say why. `speed` is what every arrival is
+    // divided by, so a decision recorded without it can be re-read and not
+    // recomputed; `firstByte` and `kill` are what a start and a stop cost here;
+    // `refetch` is what a second of film costs to fetch again. A zero in the
+    // last three is a measurement nobody has taken, not a free operation, and it
+    // is printed so that reading it as free is a choice rather than an accident.
+    if (actions.some((action) => action.type !== "keep")) {
+      this.logger.info(
+        `encode-plan on ${address}: ` +
+        `${actions.map((action) => `${action.type} #${action.from ?? "?"}..#${action.to ?? "?"}`).join(", ")}` +
+        ` [speed=${speedX.toFixed(2)}x firstByte=${costs.firstByteWaitSec.toFixed(2)}s ` +
+        `kill=${costs.killCostSec.toFixed(2)}s refetch=${refetchSecPerFilmSecond.toFixed(3)}s/s ` +
+        `maxRuns=${maxRuns} live=${live.length}]`
+      );
+    }
+    if (actions.some((action) => action.type === "move")) {
+      this.logger.info(
+        `encode-plan move on ${address}: windows=${JSON.stringify(windows)} ` +
+        `maxRuns=${maxRuns} ` +
+        `live=${JSON.stringify(live.map((run) => ({ from: run.from, to: run.to, head: run.head, speedX: run.speedX })))}`
+      );
+    }
+    for (const action of actions) {
+      if (action.type === "stop") {
+        this.#stop(action.run, action.because);
+        continue;
+      }
+      if (action.type === "move") {
+        // A running encoder's position cannot be changed — it is fixed when the
+        // process starts — so a move is this one ending and another beginning
+        // where the material is missing. Both halves are recorded as what they
+        // are, which is why the ending of a moved run is not called normal.
+        this.#stop(action.run, action.because);
+        this.#start(address, action.from, action.to, action.because);
+        continue;
+      }
+      if (action.type === "start") {
+        this.#start(address, action.from, action.to, action.because);
+        continue;
+      }
+      // A run that stays keeps its claim current: the free stretch ahead of it
+      // may have shrunk since it was given one.
+      //
+      // THE CLAIM IS THE STRETCH IT WAS GIVEN, and there is one rule for that
+      // everywhere. It used to be narrowed here to what the run had already
+      // MADE whenever the run had no end, which meant a run claimed the single
+      // number it was writing and nothing beyond. The plan then read the road
+      // in front of a working encoder as free and started more encoders on it:
+      // three processes writing one directory with the same names, field
+      // 2026-09-06, and a piece of the film lost for good when the first of
+      // them was cleaned up after.
+      //
+      // The worry that narrowing was written for is real and is answered where
+      // it belongs — a viewer opening the same film further in must not find
+      // every number taken. That is the plan's business, and the plan can take
+      // road away from a run that has no end, because such a run carries no
+      // `-to` and simply stops when its head meets somebody else's claim.
+      coverage.claim(action.run, action.from, endOfRun({ from: action.from, to: action.to }));
+    }
+
+    // NOBODY IS MAKING WHAT SOMEBODY IS WAITING FOR. Said here, with the numbers
+    // the decision was taken from, because it is the one state in which a viewer
+    // waits for ever and every line above it reads as a healthy proxy.
+    //
+    // Field 2026-09-07, twice in one evening: the last word about an output was
+    // "the film is no worse off without it", and after it nothing — no run, no
+    // refusal, no answer to the browser's request for the header. The wait ended
+    // at the browser's own timeout with a message naming no cause, and the
+    // proxy's log named none either.
+    //
+    // SAID ONCE PER STATE, not once per pass. A stuck output is reconciled on
+    // every event that touches it, and a line repeated for as long as the state
+    // lasts is what buried the last one: 49 295 copies of `send queue stuck` in
+    // a 159 090-line file, 31 % of the log, all of one wedge.
+    const wanting = firstUnmetWant(coverage, windows);
+    const stillRunning = this.runsOn(address).filter((run) => run.isAlive);
+    if (wanting === null || stillRunning.length > 0) {
+      this.#lastUnmet.delete(address);
+    } else if (this.#lastUnmet.get(address) !== wanting) {
+      this.#lastUnmet.set(address, wanting);
+      const held = this.#segmentCoverage ? this.#segmentCoverage.filesHeld(address) : -1;
+      this.logger.warn(
+        `encode: #${wanting} of ${address} is wanted and NO ENCODER IS MAKING IT — ` +
+        `ready=${coverage.stats().ready} of ${coverage.segmentCount} ` +
+        `files=${held < 0 ? "?" : held} maxRuns=${maxRuns} ` +
+        `windows=${JSON.stringify(windows)}`
+      );
+    }
+  }
+
+  /**
+   * @param {string} address
+   * @param {number} from
+   * @param {number} to
+   * @param {string} because
+   */
+  #start(address, from, to, because) {
+    // The encoder is built here and now: whoever builds one waits for nothing,
+    // so it exists by the time this line returns. That is what makes the
+    // stretch held from this instant — this class knows what it is making
+    // because it has just made it, and no second encoder can be started for the
+    // same stretch on the next pass.
+    //
+    // It was not always so. The builder used to answer with nothing and start
+    // the encoder behind the answer, so the stretch stayed FREE for as long as
+    // that took, and every pass in between started another one: 684 starts in
+    // 482 seconds of field 2026-09-05, of which 973 answers said the encoder
+    // was not there yet — every start without exception.
+    //
+    // The run names itself: identity is a property of the thing, and two
+    // places minting names is how one stops being unique.
+    const run = this.makeRun({ address, from, to, because });
+    if (!run) {
+      // A refusal, not a wait: no session serves this output, or this position
+      // has failed to start too many times running.
+      this.logger.warn(`encode: no encoder could be made for #${from}..#${to} of ${address}`);
+      return;
+    }
+    const onThisOutput = this.#runs.get(address) ?? [];
+    onThisOutput.push(run);
+    this.#runs.set(address, onThisOutput);
+    // Nothing has to be un-proved when a run takes a stretch that has already
+    // been written. A piece is only ever NAMED as served once it is closed, and
+    // a run writing that number again writes under a working name until it
+    // closes its own — so the file standing there is a complete piece made by
+    // somebody, and serving it is right until the newer one replaces it whole.
+    // The claim comes after the run exists, and that is not a race: everything
+    // between is synchronous, and a process cannot say a word before the next
+    // tick. What it removes is the second act — building a run and starting it
+    // were two steps, and two owners each performed the second one.
+    this.coverageOf(address).claim(run, from, endOfRun({ from, to }));
+  }
+
+  /**
+   * The best figure this host has for one encoder on this output: the
+   * processing speed a run here has measured (`EncodeRun.speedX`), or what this
+   * output was last measured doing and the startup measurements predict
+   * (`startingSpeedFor`), which exists before any run has closed two pieces and
+   * after a restart. The run owns its speed; nothing here keeps a copy.
+   *
+   * It is the MACHINE's speed: input waits for the swarm are not in it. What
+   * the swarm delivers is the separate supply term
+   * (`refetchSecPerFilmSecond`).
+   *
+   * @param {string} address
+   * @param {{ speedX: number }[]} live
+   * @returns {number}
+   */
+  #speedOn(address, live) {
+    return Math.max(
+      live.reduce((best, run) => Math.max(best, run.speedX || 0), 0),
+      this.startingSpeedFor(address) || 0
+    );
+  }
+
+  /**
+   * How many encoders may run on this output, from every limit at once.
+   *
+   * The processor is one of them and is answered from outside, where the
+   * machine is measured. The other two are known here: what the swarm delivers,
+   * through the seconds of swarm time a second of film costs, and — once it is
+   * supplied — the memory the piece store may hold against what one encoder's
+   * reader keeps.
+   *
+   * Said out loud when it is not the processor that decided, because "why is
+   * there only one encoder" is otherwise a question no log can answer.
+   *
+   * @param {string} address
+   * @param {{ speedX: number }[]} live
+   * @returns {number}
+   */
+  #affordableOn(address, live) {
+    const byProcessor = Math.max(0, this.maxRunsFor(address));
+    const fastest = this.#speedOn(address, live);
+    const budget = affordableRuns({
+      byProcessor,
+      speedX: fastest,
+      refetchSecPerFilmSecond: this.refetchSecPerFilmSecond(address),
+      // How much slower one encoder runs beside others, read off this host's own
+      // startup measurement. A pure function over a measured table: beyond what
+      // was measured it holds the largest reading rather than continuing a curve
+      // nothing observed.
+      contentionPenaltyFor: (others) => contentionPenalty(others, this.contentionPenalties).penalty
+    });
+    if (budget.runs !== byProcessor && budget.because !== this.#lastBudgetReason.get(address)) {
+      this.#lastBudgetReason.set(address, budget.because);
+      this.logger.info(
+        `encode: ${budget.runs} encoder(s) on ${address.slice(0, 60)} — ${budget.because} ` +
+        `(the processor alone would allow ${byProcessor})`
+      );
+    }
+    return budget.runs;
+  }
+
+  /**
+   * The per-output limit, bounded by what the whole machine can still hold.
+   *
+   * The per-output answer is at least one whatever else is running; the
+   * machine's may be none, and that is the refusal: the output gets no encoder
+   * until one elsewhere ends. It is never below what already runs here, so a
+   * refusal stops a start and never takes an encoder away.
+   *
+   * Said out loud when the machine is what bound it, once per change.
+   *
+   * @param {string} address
+   * @param {object[]} live
+   * @param {number} perOutput
+   * @returns {number}
+   */
+  #withinMachine(address, live, perOutput) {
+    if (!this.admission) {
+      return perOutput;
+    }
+    const machine = this.admission.placesFor(address, live.length);
+    const runs = Math.min(perOutput, machine.runs);
+    const said = runs < perOutput ? `${runs}:${machine.because}` : "";
+    if (said !== (this.#lastMachineBound.get(address) ?? "")) {
+      if (said) {
+        this.logger.info(
+          `encode: ${runs} encoder(s) on ${address} — the whole machine holds no more ` +
+          `(${machine.because}; this output alone would be allowed ${perOutput})`
+        );
+        this.#lastMachineBound.set(address, said);
+      } else {
+        this.#lastMachineBound.delete(address);
+      }
+    }
+    return runs;
+  }
+
+  /**
+   * Take charge of a run this class did not start.
+   *
+   * The browser asks for a stream and a run begins for it, long before this
+   * class has an opinion. Left unknown, that run would be invisible to the plan
+   * — which would then start a second encoder over the same numbers, believing
+   * nothing was being made there. So whoever starts one hands it over, and from
+   * then on it is planned like any other.
+   *
+   * @param {string} address
+   * @param {{ id: string, from: number, to: number, head: number, speedX: number, isAlive: boolean, stop: (because: string) => void }} run
+   */
+  adopt(address, run) {
+    if (!run) {
+      return;
+    }
+    const onThisOutput = this.#runs.get(address) ?? [];
+    if (onThisOutput.includes(run)) {
+      return;
+    }
+    onThisOutput.push(run);
+    this.#runs.set(address, onThisOutput);
+    this.coverageOf(address).claim(run, run.from, endOfRun(run));
+  }
+
+  /**
+   * @param {object} run
+   * @param {string} because
+   */
+  #stop(run, because) {
+    run.stop(because);
+  }
+
+  /**
+   * A run has ended, however it ended. Its stretch goes back to the map — what
+   * it finished stays made — and the ending is counted.
+   *
+   * Wired by whoever builds the run, so that a run built outside this class is
+   * still accounted for.
+   *
+   * @param {import("../encode/EncodeRun.js").RunEnded} ended
+   */
+  noteEnded(ended) {
+    this.#lastState.set(ended.address, ended.run?.state ?? "IDLE");
+    if (ended.lastError) {
+      this.#lastError.set(ended.address, ended.lastError);
+    } else if (ended.because && ended.ending !== ENCODE_EXIT.COMPLETE) {
+      this.#lastError.set(ended.address, ended.because);
+    }
+    const progress = ended.run?.progress?.snapshot?.();
+    if (progress) {
+      this.#lastProgress.set(ended.address, progress);
+    }
+    this.#costs.note(ended);
+    // Exactly one ending is normal — the run reached the end of the stretch it
+    // was given and closed its last file. Every other leaves a piece open, and
+    // that piece is under this run's OWN working name, so clearing up after it
+    // is a name match: no stretch to search and no bytes to judge. Done for
+    // every ending, the normal one included, since a run that finished cleanly
+    // has nothing under a working name and the sweep then removes nothing.
+    this.#segmentCoverage?.clearUpAfter(ended.address, ended.from);
+    this.coverageOf(ended.address).release(ended.run);
+    const remaining = this.runsOn(ended.address).filter((run) => run !== ended.run);
+    if (remaining.length === 0) {
+      this.#runs.delete(ended.address);
+    } else {
+      this.#runs.set(ended.address, remaining);
+    }
+    this.#endings.set(ended.ending, (this.#endings.get(ended.ending) ?? 0) + 1);
+    this.#noteInputAvailability(ended);
+  }
+
+  /**
+   * Remember, per output, that its input was not there — and until when nothing
+   * is to be placed on it.
+   *
+   * **Why the plan has to hold this.** A run whose input has gone is not alive,
+   * so the plan sees the stretch it held as free and places another run there at
+   * once — and the next one dies the same way, because nothing about the state
+   * has changed. There WAS a delay for exactly this, doubling from 2 s to 15 s,
+   * and it governed only the dead run's own retry while the plan went on placing
+   * fresh ones beside it. The comment beside that timer predicted this in as
+   * many words and the code did not prevent it. Field 2026-09-12: 2432 ffmpeg
+   * starts in 23 minutes, one every 0.57 s, for 61 minutes, against a delay that
+   * had long since reached its 15 s cap.
+   *
+   * So the delay lives where the decision is taken. It is not a cure for the
+   * input being away — that is the store's claim being withdrawn and the piece
+   * being fetched again — it is what stops one absent input from costing a
+   * thousand processes and a quarter of a million log lines while it is away.
+   *
+   * @param {{ address: string, ending: string }} ended
+   * @returns {void}
+   */
+  #noteInputAvailability(ended) {
+    if (ended.ending !== ENCODE_EXIT.INPUT_LOST) {
+      // CLEARED ONLY BY PROOF THAT THE INPUT WAS THERE, which is a segment
+      // having come out of it. Any other ending was nearly the rule here and is
+      // wrong: at the moment of failure several runs end at once, and one of
+      // them ending `gone` or `stopped` without producing a thing says nothing
+      // about the input — it would have lifted the wait the one beside it had
+      // just set, which is the storm again with an extra step.
+      const produced =
+        ended.firstOutputMs !== null && ended.firstOutputMs !== undefined
+          ? true
+          : Number.isFinite(ended.reached) && Number.isFinite(ended.from) && ended.reached >= ended.from;
+      if (produced) {
+        this.#inputLostAttempts.delete(ended.address);
+        this.#quietUntil.delete(ended.address);
+      }
+      return;
+    }
+    const attempts = (this.#inputLostAttempts.get(ended.address) ?? 0) + 1;
+    this.#inputLostAttempts.set(ended.address, attempts);
+    const delayMs = Math.min(
+      INPUT_QUIET_MAX_MS,
+      INPUT_QUIET_BASE_MS * 2 ** Math.min(attempts - 1, 6)
+    );
+    this.#quietUntil.set(ended.address, this.now() + delayMs);
+    this.logger.info(
+      `encode-plan on ${ended.address}: its input was not there (attempt ${attempts}) — ` +
+      `placing nothing for ${Math.round(delayMs / 1000)}s`
+    );
+    // THE WAKE-UP, because a plan that refuses to act needs something to ask it
+    // again: nothing about the state changes while the data is away, so no event
+    // would arrive to reconsider it.
+    const timer = setTimeout(() => {
+      this.#quietTimers.delete(ended.address);
+      this.planSoon();
+    }, delayMs);
+    timer.unref?.();
+    const previous = this.#quietTimers.get(ended.address);
+    if (previous) {
+      clearTimeout(previous);
+    }
+    this.#quietTimers.set(ended.address, timer);
+  }
+
+  /**
+   * Whether this output is still waiting before anything may be placed on it.
+   *
+   * A boolean rather than the milliseconds left: the figure had one reader and
+   * that reader only asked whether it was above zero, so it was a number
+   * computed and thrown away. How long the wait is was said when it began.
+   *
+   * @param {string} address
+   * @returns {boolean}
+   */
+  #isQuiet(address) {
+    const until = this.#quietUntil.get(address);
+    if (!Number.isFinite(until)) {
+      return false;
+    }
+    if (until - this.now() <= 0) {
+      this.#quietUntil.delete(address);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Forget everything remembered about an output nobody is producing for.
+   *
+   * Three maps are keyed by address, and an output that goes away leaves an
+   * entry in each for the life of the process. Small, and exactly the shape of
+   * accumulation this layer was built to remove from the session.
+   *
+   * @param {string} address
+   * @returns {void}
+   */
+  #forgetInputState(address) {
+    this.#inputLostAttempts.delete(address);
+    this.#quietUntil.delete(address);
+    const timer = this.#quietTimers.get(address);
+    if (timer) {
+      clearTimeout(timer);
+      this.#quietTimers.delete(address);
+    }
+  }
+
+  /**
+   * How runs have ended over the life of this process, by cause.
+   *
+   * The abnormal classes are meant to stand at zero. Without the count,
+   * "we understand why it ended" is indistinguishable from "we noticed it once".
+   *
+   * @returns {Record<string, number>}
+   */
+  endings() {
+    /** @type {Record<string, number>} */
+    const tally = {};
+    for (const ending of Object.values(ENCODE_EXIT)) {
+      tally[ending] = this.#endings.get(ending) ?? 0;
+    }
+    return tally;
+  }
+
+  /**
+   * One line saying what this proxy is encoding and whether anybody is waiting.
+   *
+   * `waiting` is the point of it: a proxy with encoders running and a viewer
+   * still stopped at a segment nobody is making is the failure this layer was
+   * built to remove, and it is visible here rather than inferred from a log.
+   *
+   * @returns {string}
+   */
+  describe() {
+    const parts = [];
+    for (const address of new Set([...this.#demand.addresses(), ...this.#runs.keys()])) {
+      const coverage = this.coverageOf(address);
+      const stated = this.#demand.mapOn(address);
+      const windows = stated.map((zone) => ({ from: zone.from, to: zone.to }));
+      const waiting = firstUnmetWant(coverage, windows);
+      const runs = this.runsOn(address)
+        .map((run) => `#${run.head}..#${run.to}@${run.speedX.toFixed(1)}x`)
+        .join(" ");
+      // The zones as they were stated, with their order, so a plan that is
+      // working at the wrong end of the film is visible rather than inferred.
+      const zones = [...stated]
+        .sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.from - right.from)
+        .map((w) => `p${w.priority ?? 0}:#${w.from}..#${w.to}`)
+        .join(" ");
+      // THE WHOLE ADDRESS. Cut to sixty characters, every output of one film
+      // printed the same string — the picture, its quality steps and each
+      // soundtrack are told apart only by the tail — so three lines of this
+      // could not be matched to the three things they describe. Read on
+      // 2026-09-07 while accounting for a session that produced nothing, and
+      // the accounting had to be done by which line carried a run.
+      //
+      // And WHAT THE DISK HOLDS beside what is proven closed. They are two
+      // different statements: files with nothing proving them closed reads as a
+      // reporting fault, no files at all reads as an output yet to be made, and
+      // the difference decides where to look.
+      const held = this.#segmentCoverage ? this.#segmentCoverage.filesHeld(address) : -1;
+      // AND WHETHER THE MAP IS BEING SERVED IN ITS OWN ORDER. The zones say
+      // what matters most; this says what the viewer actually waited for, by
+      // band. Waits at `now` are the ones that cost a spinner, and until this
+      // existed there was no figure anywhere saying whether the urgent zone was
+      // served first — the map could have been read backwards and every line
+      // above would have looked the same.
+      const served = this.#describeWaits(address);
+      parts.push(
+        `${address} ready=${coverage.stats().ready}` +
+        `${held < 0 ? "" : ` of ${held} file(s) on disk`} ` +
+        `zones=[${zones}] runs=[${runs}] ` +
+        `waiting=${waiting === null ? "nobody" : `#${waiting}`}` +
+        `${served ? ` served[${served}]` : ""}`
+      );
+    }
+    const tally = this.endings();
+    const endings = Object.entries(tally)
+      .map(([cause, count]) => `${cause}=${count}`)
+      .join(" ");
+    return `encode: ${parts.length === 0 ? "nothing wanted" : parts.join(" | ")} :: endings ${endings}`;
+  }
+}