@torrent-tv/proxy 2.30.2 → 2.32.0

package/services/hls-session-manager.js

@@ -25,7 +25,8 @@ import {
   ENCODE_RUN_STATE,
   INITIAL_RUN_STATE,
   nextState,
-  processCanBeSignalled
+  processCanBeSignalled,
+  wireState
 } from "./encode-run-state.js";
 import { ENCODE_EXIT, classifyEncodeExit } from "./encode-exit.js";
 
@@ -1854,17 +1855,23 @@ export class HlsSessionManager {
       sourceMapKey,
       fileName: logName,
       dirPath: sessionDir,
-      state: "starting",
+      // The SESSION's own lifetime, and nothing else: it exists, or it has been
+      // disposed. It used to carry the encoder run's status as well, which is
+      // why one line in the spawn path read `state === "disposed" ? "disposed"
+      // : "starting"` — two lifetimes in one variable. The run's status lives
+      // in `runState`.
+      state: "live",
       startedAt: Date.now(),
       lastAccessedAt: Date.now(),
       ffmpeg: null,
       encodeRunGeneration: 0,
       // What the ENCODER RUN is doing, as one control state from the table in
-      // `encode-run-state.js`. Written at every event today and read by nothing
-      // yet: a refused pair in the log is the model disagreeing with reality,
-      // and that disagreement is the measurement this release exists to take.
-      // The fields it replaces — `state`, `progress.state`
-      // and the repeated liveness checks — keep their current writes meanwhile.
+      // `encode-run-state.js`. Every question about the run is now answered
+      // from here: whether a process can be signalled, whether anything is
+      // reading the input, what a missing segment is answered with, and what
+      // the browser is told. The three representations it replaced — a status
+      // string, a second status string on the wire, and a child-process handle
+      // consulted at ten sites — could disagree with each other, and did.
       runState: INITIAL_RUN_STATE,
       lastError: "",
       // Cold-start timing: entry timestamp + a once-guard so the first servable
@@ -2007,7 +2014,10 @@ export class HlsSessionManager {
       seekFailureTarget: -1,
       seekFailureCount: 0,
       progress: {
-        state: "starting",
+        // No `state` here. What the browser is told is `wireState(runState)`,
+        // computed where it is sent — a Moore output rather than a field
+        // maintained by hand at seven sites, which is how it came to be read
+        // together with `session.state` under an `||`.
         processedSeconds: 0,
         startPositionSeconds: 0,
         totalSeconds: hasDuration ? durationSeconds : null,
@@ -2099,7 +2109,7 @@ export class HlsSessionManager {
       await this.waitUntilReady(session);
       return session;
     } catch (error) {
-      if (session.state === "failed") {
+      if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
         await this.disposeSession(session.id);
         throw error;
       }
@@ -3253,7 +3263,7 @@ export class HlsSessionManager {
       if (
         !session ||
         session.state === "disposed" ||
-        session.state === "failed" ||
+        session.runState === ENCODE_RUN_STATE.ENDED_FAILED ||
         !session.transcodeVideo ||
         // Nothing is encoding, so there is no speed to judge. A variant the
         // viewer has switched away from is left in exactly this state, and its
@@ -3812,8 +3822,6 @@ export class HlsSessionManager {
     session.encodeStartIndex = safeIndex;
     session.pendingRestartIndex = -1;
     session.lastRestartAt = Date.now();
-    session.state = session.state === "disposed" ? "disposed" : "starting";
-    session.progress.state = "running";
     session.progress.processedSeconds = startSeconds;
     session.progress.startPositionSeconds = startSeconds;
     session.progress.updatedAt = Date.now();
@@ -3912,7 +3920,6 @@ export class HlsSessionManager {
         } else if (key === "speed") {
           session.progress.speed = value;
         } else if (key === "progress") {
-          session.progress.state = value === "end" ? "ready" : "running";
         }
         const metrics = computeProgressMetrics(
           session.progress.processedSeconds,
@@ -3948,9 +3955,7 @@ export class HlsSessionManager {
       if (!this.#isCurrentRun(session, ffmpeg)) {
         return;
       }
-      session.state = "failed";
       session.lastError = error instanceof Error ? error.message : String(error);
-      session.progress.state = "failed";
       session.progress.updatedAt = Date.now();
       this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_FAILED);
       logger.error(`ffmpeg ${session.id} process error: ${session.lastError}`);
@@ -3989,9 +3994,7 @@ export class HlsSessionManager {
         // segment nobody was making. So the claim is checked against the
         // playlist we published, and a run that stopped short is a FAILURE that
         // can be restarted, not a finished file.
-        session.state = "failed";
-        session.progress.state = "failed";
-        session.progress.updatedAt = Date.now();
+            session.progress.updatedAt = Date.now();
         session.lastError =
           `input ended after segment #${producedThrough} of ${expectedLast} — ` +
           "the source stopped delivering data";
@@ -4003,8 +4006,6 @@ export class HlsSessionManager {
         return;
       }
       if (outcome === ENCODE_EXIT.COMPLETE) {
-        session.state = "ready";
-        session.progress.state = "ready";
         session.progress.updatedAt = Date.now();
         this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_COMPLETE);
         logger.info(`transcode ${session.id} encode-run complete "${session.fileName}"`);
@@ -4066,11 +4067,9 @@ export class HlsSessionManager {
       // stays for what it was built for, a target that genuinely cannot be
       // encoded; it must not condemn a session whose data merely went away.
       if (outcome === ENCODE_EXIT.INPUT_LOST) {
-        session.state = "recovering";
         // On the wire it is simply "not ready yet" — a state the browser has
         // always known how to wait through. Only the proxy needs the
         // distinction between waiting for data and having given up.
-        session.progress.state = "starting";
         session.progress.updatedAt = Date.now();
         this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_INPUT_LOST);
         session.inputRetryCount = (session.inputRetryCount ?? 0) + 1;
@@ -4085,7 +4084,7 @@ export class HlsSessionManager {
         );
         session.inputRetryTimer = setTimeout(() => {
           session.inputRetryTimer = null;
-          if (session.state !== "recovering") {
+          if (session.runState !== ENCODE_RUN_STATE.RETRY_WAIT) {
             return;
           }
           this.#transitionRun(session, ENCODE_RUN_EVENT.RETRY_DUE);
@@ -4097,8 +4096,6 @@ export class HlsSessionManager {
         session.inputRetryTimer.unref?.();
         return;
       }
-      session.state = "failed";
-      session.progress.state = "failed";
       session.progress.updatedAt = Date.now();
       this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_FAILED);
       logger.error(
@@ -4579,10 +4576,9 @@ export class HlsSessionManager {
     // Individual segments are long-polled by the segment route as ffmpeg
     // produces them.
     if (session.useSyntheticPlaylist) {
-      if (session.state === "failed") {
+      if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
         throw new Error(session.lastError || "ffmpeg failed to start HLS session.");
       }
-      session.state = "ready";
       return;
     }
 
@@ -4590,15 +4586,14 @@ export class HlsSessionManager {
     const deadline = Date.now() + this.startupWaitMs;
 
     while (Date.now() < deadline) {
-      if (session.state === "failed") {
+      if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
         throw new Error(session.lastError || "ffmpeg failed to start HLS session.");
       }
       try {
         await access(playlistPath);
         const text = await readFile(playlistPath, "utf8");
         if (text.includes("#EXTM3U")) {
-          session.state = "ready";
-          return;
+            return;
         }
       } catch (_error) {
         // Playlist is not ready yet.
@@ -5114,7 +5109,14 @@ export class HlsSessionManager {
     const median = deviations.length > 0 ? deviations[Math.floor(deviations.length / 2)] : 0;
     const landed = check.landedOnAnotherKeyframe ?? 0;
     logger.info(
-      `keyframe-index ${session.containerFormat || "unknown"} "${session.fileName}": ` +
+      // The session id, because without it this line cannot be attributed. A
+      // family produces one summary per member — the picture and each
+      // soundtrack — and on 2026-08-17 the picture's was read as the sound's,
+      // from a neighbouring log line, and a roadmap item was written against
+      // the wrong half of the stream. The id is the only thing that says whose
+      // reading this is.
+      `keyframe-index ${session.id.slice(0, 8)} ${session.audioOnly === true ? "sound" : "picture"} ` +
+      `${session.containerFormat || "unknown"} "${session.fileName}": ` +
       `${check.disagreed} of ${check.checked} produced segments started away from the playlist, ` +
       `median ${median.toFixed(3)}s worst ${check.maxDeviationSec.toFixed(3)}s` +
       (check.firstDisagreementIndex >= 0 ? ` (first at #${check.firstDisagreementIndex})` : "") +
@@ -5374,7 +5376,7 @@ export class HlsSessionManager {
     if (
       !session ||
       session.state === "disposed" ||
-      session.state === "failed" ||
+      session.runState === ENCODE_RUN_STATE.ENDED_FAILED ||
       !session.ffmpeg ||
       session.runState === ENCODE_RUN_STATE.SUSPENDED
     ) {
@@ -6923,13 +6925,13 @@ export class HlsSessionManager {
     if (!session || !isSafeFileName(fileName, session.segmentFormat)) {
       return { kind: "not-found" };
     }
-    if (session.state === "recovering") {
+    if (session.runState === ENCODE_RUN_STATE.RETRY_WAIT) {
       // The data went away and is being fetched again. Holding the request is
       // the truthful answer: nothing is broken and there is nothing for the
       // viewer to retry.
       return { kind: "warming-up" };
     }
-    if (session.state === "failed") {
+    if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
       return {
         kind: "failed",
         message: session.lastError || "ffmpeg failed for this transcode session."
@@ -7496,7 +7498,11 @@ export class HlsSessionManager {
     session.lastAccessedAt = Date.now();
     const warmupTotalSeconds = this.startupWaitMs / 1000;
     const warmupElapsedSeconds = Math.max(0, (Date.now() - session.startedAt) / 1000);
-    const isWarmupPhase = session.state === "starting" || session.progress.state === "starting";
+    // One question, one answer. This used to read BOTH strings with `||`
+    // because neither could answer alone: `session.state` said "starting" from
+    // the first spawn until something else overwrote it, and `progress.state`
+    // said it again on its own schedule.
+    const isWarmupPhase = wireState(session.runState) === "starting";
     const warmupPercent = isWarmupPhase
       ? Math.max(0, Math.min(100, (warmupElapsedSeconds / warmupTotalSeconds) * 100))
       : null;
@@ -7514,7 +7520,7 @@ export class HlsSessionManager {
       // The id the caller asked about, not the variant it was answered from —
       // the browser tracks its sessions by the id it was given.
       sessionId: named.id,
-      state: session.progress.state,
+      state: wireState(session.runState),
       processedSeconds: session.progress.processedSeconds,
       startPositionSeconds: session.progress.startPositionSeconds ?? 0,
       totalSeconds: session.progress.totalSeconds,
@@ -7554,7 +7560,7 @@ export class HlsSessionManager {
       expectedSessionCreateMs: this.expectedSessionCreateMs(),
       expectedFirstSegmentMs: this.expectedFirstSegmentMs(),
       updatedAt: session.progress.updatedAt,
-      error: session.state === "failed" ? session.lastError : ""
+      error: session.runState === ENCODE_RUN_STATE.ENDED_FAILED ? session.lastError : ""
     };
   }
 

package/services/hwaccel.js

@@ -24,6 +24,7 @@ import { spawn } from "node:child_process";
 import { mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fitDecodeCost } from "./decode-cost-fit.js";
 import { fileURLToPath } from "node:url";
 import {
   parseFfmpegBitrateKbps,
@@ -670,45 +671,28 @@ export async function detectTonemapSupport({ ffmpegBin, logger }) {
   return supported;
 }
 
-/**
- * Solve a 3×3 linear system by Gaussian elimination with partial pivoting.
- *
- * @param {number[][]} rows - Three rows of [c0, c1, c2, rhs].
- * @returns {number[] | null} The three unknowns, or null when singular.
- */
-function solveLinear3(rows) {
-  const m = rows.map((row) => [...row]);
-  for (let col = 0; col < 3; col += 1) {
-    let pivot = col;
-    for (let row = col + 1; row < 3; row += 1) {
-      if (Math.abs(m[row][col]) > Math.abs(m[pivot][col])) {
-        pivot = row;
-      }
-    }
-    if (Math.abs(m[pivot][col]) < 1e-12) {
-      return null;
-    }
-    [m[col], m[pivot]] = [m[pivot], m[col]];
-    for (let row = 0; row < 3; row += 1) {
-      if (row === col) {
-        continue;
-      }
-      const factor = m[row][col] / m[col][col];
-      for (let k = col; k < 4; k += 1) {
-        m[row][k] -= factor * m[col][k];
-      }
-    }
-  }
-  return [m[0][3] / m[0][0], m[1][3] / m[1][1], m[2][3] / m[2][2]];
-}
 
-// The clips the decode cost is solved from. They ship with the package
+// The clips the decode cost is fitted from. They ship with the package
 // (`assets/calibration/`), cut from Netflix Open Content "Meridian" (CC-BY 4.0)
 // — real, grainy live action, because a generated `testsrc2` clip decodes 158 %
-// away from a real film where these are 11 % away (measured 2026-08-14). Two
-// share a pixel count and differ 11.7× in bitrate, the third has the same
-// bitrate class at fewer pixels: three points, three unknowns.
-const CALIBRATION_CLIPS = ["cal-1080-hi.mp4", "cal-1080-lo.mp4", "cal-720.mp4"];
+// away from a real film where these are 11 % away (measured 2026-08-14).
+//
+// Three sizes at two bitrates each, with the axes varied INDEPENDENTLY. The set
+// this replaced was three clips for three unknowns, two of them at the same
+// size: an exact system, which cannot fail visibly. On 2026-08-17 it returned
+// `0.007542 × Mpx/s + 0.000000 × Mbit/s + 0.0000 s/s` — the bitrate term and
+// the constant exactly zero — and the prediction on top of it was 1.8-2.2x
+// optimistic. Six points leave three spare, so the fit has a residual, and a
+// term the data does not determine can be refused instead of published as a
+// zero that looks measured. See `assets/calibration/NOTICE.md`.
+const CALIBRATION_CLIPS = [
+  "cal-h264-1080-hi.mp4",
+  "cal-h264-1080-lo.mp4",
+  "cal-h264-720-hi.mp4",
+  "cal-h264-720-lo.mp4",
+  "cal-h264-480-hi.mp4",
+  "cal-h264-480-lo.mp4"
+];
 const CALIBRATION_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "assets", "calibration");
 // How wide the measured window must be before the slope is trusted, and how
 // long to wait for it at most. A second of decoding is thousands of frames on a
@@ -770,8 +754,8 @@ function parseClipCharacteristics(stderr) {
 export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBRATION_DIR }) {
   const log = logger ?? { info: () => {}, warn: () => {} };
   const startedAllAt = Date.now();
-  /** @type {number[][]} */
-  const equations = [];
+  /** @type {Array<{ megapixelsPerSecond: number, megabitsPerSecond: number, costSecondsPerSecond: number }>} */
+  const samples = [];
   for (const clip of CALIBRATION_CLIPS) {
     const measured = await measureDecodeSlope(ffmpegBin, path.join(clipsDir, clip));
     if (!measured) {
@@ -779,21 +763,31 @@ export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBR
       return null;
     }
     const cost = 1 / measured.speed;
-    equations.push([measured.megapixelsPerSecond, measured.megabitsPerSecond, 1, cost]);
+    samples.push({
+      megapixelsPerSecond: measured.megapixelsPerSecond,
+      megabitsPerSecond: measured.megabitsPerSecond,
+      costSecondsPerSecond: cost
+    });
     log.info(
       `hwaccel: decode "${clip}" ${measured.megapixelsPerSecond.toFixed(1)} Mpx/s ` +
         `${measured.megabitsPerSecond.toFixed(2)} Mbit/s -> ${measured.speed.toFixed(1)}x ` +
         `(cost ${cost.toFixed(4)} s/s, over ${measured.windowSec.toFixed(1)}s of decoding)`
     );
   }
-  const fitted = fitDecodeCost(equations);
+  const fitted = fitDecodeCost(samples);
   if (!fitted) {
     log.warn("hwaccel: decode cost could not be fitted to these measurements; decode cost unknown");
     return null;
   }
   log.info(
     `hwaccel: decode cost = ${fitted.pixelTerm.toFixed(6)} × Mpx/s + ${fitted.bitrateTerm.toFixed(6)} × Mbit/s ` +
-      `+ ${fitted.constantTerm.toFixed(4)} s/s (${fitted.shape}, measured in ${((Date.now() - startedAllAt) / 1000).toFixed(1)}s)`
+      `+ ${fitted.constantTerm.toFixed(4)} s/s (${fitted.shape} from ${fitted.samples} clips, ` +
+      `typical disagreement ${fitted.residualRms.toFixed(4)} s/s` +
+      // Named rather than implied: a zero in the line above means "not
+      // measured" for a dropped term and "measured to be nothing" otherwise,
+      // and those are different claims.
+      (fitted.dropped.length > 0 ? `, ${fitted.dropped.join(" and ")} not determined by these clips` : "") +
+      `, measured in ${((Date.now() - startedAllAt) / 1000).toFixed(1)}s)`
   );
   return { pixelTerm: fitted.pixelTerm, bitrateTerm: fitted.bitrateTerm, constantTerm: fitted.constantTerm };
 }
@@ -911,65 +905,6 @@ function measureDecodeSlope(ffmpegBin, clipPath) {
   });
 }
 
-/**
- * Fit the three measurements, and say which shape the data supported.
- *
- * The three-term fit is exact — three points, three unknowns — and is used
- * whenever every term comes out non-negative. A negative term is not a host
- * being odd; it says the difference it was solved from is smaller than the
- * noise between runs, which is what a fast machine produces: measured on a
- * desktop, the 720p clip took LONGER per second than the low-bitrate 1080p one,
- * because process startup is a large share of a decode that takes a second.
- *
- * When that happens the bitrate term — the weak one, and the one solved from a
- * single difference — is dropped and the remaining two are fitted by least
- * squares over all three points. If even the pixel slope comes out non-positive
- * there is no measurable dependence on the source at all, and inventing one is
- * worse than having none: the caller then prices the encoder alone and refuses
- * nothing.
- *
- * @param {number[][]} equations - Rows of [Mpixel/s, Mbit/s, 1, cost].
- * @returns {{ pixelTerm: number, bitrateTerm: number, constantTerm: number, shape: string } | null}
- */
-function fitDecodeCost(equations) {
-  const exact = solveLinear3(equations);
-  if (exact && exact[0] > 0 && exact[1] >= 0 && exact[2] >= 0) {
-    return { pixelTerm: exact[0], bitrateTerm: exact[1], constantTerm: exact[2], shape: "pixels+bitrate+constant" };
-  }
-  const count = equations.length;
-  const meanPixels = equations.reduce((sum, row) => sum + row[0], 0) / count;
-  const meanCost = equations.reduce((sum, row) => sum + row[3], 0) / count;
-  let covariance = 0;
-  let variance = 0;
-  for (const row of equations) {
-    covariance += (row[0] - meanPixels) * (row[3] - meanCost);
-    variance += (row[0] - meanPixels) ** 2;
-  }
-  if (!(variance > 0)) {
-    return null;
-  }
-  const pixelTerm = covariance / variance;
-  const constantTerm = meanCost - pixelTerm * meanPixels;
-  if (pixelTerm > 0 && constantTerm >= 0) {
-    return { pixelTerm, bitrateTerm: 0, constantTerm, shape: "pixels+constant" };
-  }
-  // A negative constant is the line crossing below zero where no clip was
-  // measured — every clip is 22 Mpixel/s or more, and nothing here says what a
-  // tiny picture costs. Rather than carry a term that would price a small
-  // source as free work, fit through the origin: cost proportional to pixels,
-  // which is the relationship the measurements do support.
-  let weighted = 0;
-  let squares = 0;
-  for (const row of equations) {
-    weighted += row[0] * row[3];
-    squares += row[0] ** 2;
-  }
-  const throughOrigin = squares > 0 ? weighted / squares : 0;
-  if (!(throughOrigin > 0)) {
-    return null;
-  }
-  return { pixelTerm: throughOrigin, bitrateTerm: 0, constantTerm: 0, shape: "pixels only" };
-}
 
 /**
  * How many times realtime this host can DECODE a source of these

package/test/decode-cost-fit.test.js

@@ -0,0 +1,145 @@
+/**
+ * @file The decode-cost fit, and the case it exists to prevent.
+ *
+ * The failure being pinned is real and dated: on 2026-08-17 three clips for
+ * three unknowns returned `0.007542 × Mpx/s + 0.000000 × Mbit/s + 0.0000 s/s`,
+ * with the bitrate term and the constant exactly zero, and the prediction built
+ * on it was 1.8-2.2x optimistic. An exact system cannot notice that two of its
+ * points said the same thing; these tests hold the replacement to noticing.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { decodeCostOf, fitDecodeCost } from "../services/decode-cost-fit.js";
+
+const FPS = 24;
+
+/**
+ * A clip's measurement, priced by a known truth so a fit can be checked against
+ * the answer it should recover.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {number} megabitsPerSecond
+ * @param {{ pixel: number, bitrate: number, constant: number, noise?: number }} truth
+ * @returns {{ megapixelsPerSecond: number, megabitsPerSecond: number, costSecondsPerSecond: number }}
+ */
+function clip(width, height, megabitsPerSecond, truth) {
+  const megapixelsPerSecond = (width * height * FPS) / 1e6;
+  const cost =
+    truth.pixel * megapixelsPerSecond + truth.bitrate * megabitsPerSecond + truth.constant + (truth.noise ?? 0);
+  return { megapixelsPerSecond, megabitsPerSecond, costSecondsPerSecond: cost };
+}
+
+/** The set the clips were cut to: three sizes, two bitrates, varied independently. */
+const SIZES = [
+  [1920, 1080],
+  [1280, 720],
+  [854, 480]
+];
+const BITRATES = [9.5, 1.1];
+
+/**
+ * @param {{ pixel: number, bitrate: number, constant: number }} truth
+ * @param {number[]} [noise] - Per-clip disturbance, in order.
+ * @returns {ReturnType<typeof clip>[]}
+ */
+function wellConditionedSet(truth, noise = []) {
+  const samples = [];
+  let index = 0;
+  for (const [width, height] of SIZES) {
+    for (const bitrate of BITRATES) {
+      samples.push(clip(width, height, bitrate, { ...truth, noise: noise[index] ?? 0 }));
+      index += 1;
+    }
+  }
+  return samples;
+}
+
+test("a well-conditioned set recovers every term", () => {
+  const truth = { pixel: 0.0055, bitrate: 0.0099, constant: 0.057 };
+  const model = fitDecodeCost(wellConditionedSet(truth));
+
+  assert.ok(model, "six clips over three unknowns must produce a model");
+  assert.equal(model.shape, "pixels+bitrate+constant");
+  assert.deepEqual(model.dropped, []);
+  assert.ok(Math.abs(model.pixelTerm - truth.pixel) < 1e-6, `pixel term ${model.pixelTerm}`);
+  assert.ok(Math.abs(model.bitrateTerm - truth.bitrate) < 1e-6, `bitrate term ${model.bitrateTerm}`);
+  assert.ok(Math.abs(model.constantTerm - truth.constant) < 1e-6, `constant ${model.constantTerm}`);
+});
+
+test("three clips are refused outright — an exact system cannot see its own degeneracy", () => {
+  // Exactly the shape that shipped: two clips at the same pixel rate differing
+  // only in bitrate, and a third at another size.
+  const truth = { pixel: 0.0055, bitrate: 0.0099, constant: 0.057 };
+  const three = [clip(1920, 1080, 11.4, truth), clip(1920, 1080, 0.97, truth), clip(1280, 720, 2.25, truth)];
+
+  assert.equal(
+    fitDecodeCost(three),
+    null,
+    "with no residual there is nothing to notice a degeneracy with, so no model may be published"
+  );
+});
+
+test("a term the measurements do not determine is dropped, and said so", () => {
+  // A host whose decoding does not depend on bitrate at all: the term is not
+  // small, it is absent. What must NOT happen is publishing a zero as though it
+  // had been measured.
+  const truth = { pixel: 0.0055, bitrate: 0, constant: 0.057 };
+  // Deliberately NOT alternating with the bitrate column: an earlier version
+  // of this test put positive noise on every high-bitrate clip and negative on
+  // every low one, which IS a bitrate signal — the fit found it, correctly, and
+  // the test was wrong.
+  const noise = [0.004, 0.003, -0.004, 0.002, -0.003, -0.002];
+  const model = fitDecodeCost(wellConditionedSet(truth, noise));
+
+  assert.ok(model);
+  assert.ok(model.dropped.includes("bitrate"), `dropped: ${model.dropped.join(",") || "nothing"}`);
+  assert.equal(model.bitrateTerm, 0);
+  assert.ok(model.shape.includes("pixels"));
+});
+
+test("noise in the readings does not become a term", () => {
+  // Pure noise around a pixels-only truth, larger than any bitrate effect.
+  const truth = { pixel: 0.0055, bitrate: 0, constant: 0 };
+  const noise = [0.01, 0.009, -0.012, 0.011, -0.008, -0.01];
+  const model = fitDecodeCost(wellConditionedSet(truth, noise));
+
+  assert.ok(model);
+  assert.ok(model.pixelTerm > 0, "the one relationship every reading agrees on survives");
+  assert.ok(
+    model.dropped.length > 0,
+    "and the terms the noise could have supplied are reported as undetermined"
+  );
+});
+
+test("without a measurable dependence on the source there is no model", () => {
+  // Every clip costs the same regardless of size or bitrate: nothing here says
+  // what a bigger picture costs, and inventing it is worse than having none.
+  const flat = wellConditionedSet({ pixel: 0, bitrate: 0, constant: 0.3 });
+  assert.equal(fitDecodeCost(flat), null);
+  assert.equal(fitDecodeCost([]), null);
+  assert.equal(fitDecodeCost(null), null);
+});
+
+test("readings that are not measurements are left out", () => {
+  const truth = { pixel: 0.0055, bitrate: 0.0099, constant: 0.057 };
+  const samples = [
+    ...wellConditionedSet(truth),
+    { megapixelsPerSecond: Number.NaN, megabitsPerSecond: 5, costSecondsPerSecond: 1 },
+    { megapixelsPerSecond: 20, megabitsPerSecond: 5, costSecondsPerSecond: 0 }
+  ];
+  const model = fitDecodeCost(samples);
+  assert.ok(model);
+  assert.equal(model.samples, 6);
+});
+
+test("what a model prices a film at", () => {
+  const model = fitDecodeCost(wellConditionedSet({ pixel: 0.0055, bitrate: 0.0099, constant: 0.057 }));
+  // The field film: 1080p24 at about 8 Mbit/s.
+  const cost = decodeCostOf(model, { megapixelsPerSecond: 49.77, megabitsPerSecond: 8 });
+  assert.ok(cost > 0);
+  // Which is a decode speed of 1/cost — the figure the quality offer rests on.
+  assert.ok(1 / cost > 1 && 1 / cost < 10, `decodes at ${(1 / cost).toFixed(2)}x`);
+});