@torrent-tv/proxy 2.31.0 → 2.33.0

package/services/hls-session-manager.js

@@ -20,6 +20,7 @@ import { logger } from "../utils/logger.js";
 import { readKeyframeIndex } from "./container-index/index.js";
 import { readMachineState, readProcessCpuSeconds, readProxyCpuSeconds, readSystemCpu, shareOfMachine } from "./host-load.js";
 import { speedFromReadings } from "./encoder-readings.js";
+import { availableShareFrom, correctForAvailability } from "./available-share.js";
 import {
   ENCODE_RUN_EVENT,
   ENCODE_RUN_STATE,
@@ -1902,6 +1903,12 @@ export class HlsSessionManager {
       // software hosts, else the client target). 0 = keep source.
       encodeWidth,
       encodeHeight,
+      // What the offer predicted this height would do on this machine, so the
+      // field can say what the prediction was worth once the step runs. Null
+      // when the step was never judged — a copied stream needs no encoder and
+      // is never predicted.
+      predictedSpeedWhenOffered: this.lastPredictedByHeight?.get(encodeHeight) ?? null,
+      lastPredictionRatio: null,
       // The NAME of this rung, fixed at the height that was asked for. It is
       // deliberately not the height being encoded: a viewer who picked 480p on
       // a host that then starts them at 360p, or steps down to it later, goes
@@ -3217,13 +3224,25 @@ export class HlsSessionManager {
     const proxyShare = Number.isFinite(previous.proxyCpuSeconds)
       ? (sample.proxyCpuSeconds - previous.proxyCpuSeconds) / (share.elapsedSec * cores)
       : null;
+    // Kept for the quality offer, which predicts from a benchmark taken on a
+    // QUIET host: the same reading that is printed here says how much of the
+    // machine a new encoder could actually have. Only what nobody has been
+    // charged for is subtracted — see `available-share.js`.
+    this.hostAvailability = availableShareFrom({
+      systemBusy: share.systemShare,
+      encoderShare: share.processShare,
+      proxyShare
+    });
     logger.info(
       `host-load: ffmpeg=${asPercent(share.processShare)} proxy=${asPercent(proxyShare)} ` +
       `system=${asPercent(share.systemShare)} ` +
       `iowait=${asPercent(share.iowaitShare)} cpu=${machine.megahertz === null ? "n/a" : `${machine.megahertz}MHz`} ` +
       `temp=${machine.celsius === null ? "n/a" : `${machine.celsius}C`} ` +
       `encoders=${running} running` + (suspended > 0 ? ` +${suspended} suspended` : "") +
-      ` over=${share.elapsedSec.toFixed(1)}s`
+      ` over=${share.elapsedSec.toFixed(1)}s` +
+      // What the offer will multiply a prediction by, in the same line as the
+      // readings it comes from.
+      ` available=${asPercent(this.hostAvailability.share)}`
     );
   }
 
@@ -3391,6 +3410,10 @@ export class HlsSessionManager {
     // although nothing is producing that step any more. The next reading of the
     // new encode replaces it.
     session.lastAloneSpeed = null;
+    // And so is the prediction it was compared against: it described the step
+    // this session has just left.
+    session.predictedSpeedWhenOffered = this.lastPredictedByHeight?.get(rung.height) ?? null;
+    session.lastPredictionRatio = null;
     // Priced the same way the offer and the starting rung are. Choosing the
     // preset on the encoder alone treats decoding as free, which is how the
     // check and the encode came to disagree in the first place — and here it
@@ -5444,6 +5467,25 @@ export class HlsSessionManager {
     // 0.3x reads as 3.33 s of work per second of video, more than the machine
     // has — and every other quality step was refused on the download's account.
     session.lastAloneSpeed = speed;
+    // What the offer predicted for this very step, against what it then did
+    // with the machine to itself. The prediction is corrected for the share of
+    // the machine that was free at the time, so this ratio is the error that
+    // remains AFTER that correction — which is the only way to tell whether a
+    // stage of roadmap item 3 moved anything. Written when it changes by more
+    // than a tenth, so a steady step says it once rather than every five
+    // seconds.
+    if (Number.isFinite(session.predictedSpeedWhenOffered) && session.predictedSpeedWhenOffered > 0) {
+      const ratio = speed / session.predictedSpeedWhenOffered;
+      const lastSaid = session.lastPredictionRatio;
+      if (!Number.isFinite(lastSaid) || Math.abs(ratio - lastSaid) > 0.1) {
+        session.lastPredictionRatio = ratio;
+        logger.info(
+          `prediction ${session.id.slice(0, 8)} ${session.encodeHeight || "source"}p: ` +
+          `predicted ${session.predictedSpeedWhenOffered.toFixed(2)}x, measured ${speed.toFixed(2)}x ` +
+          `(ratio ${ratio.toFixed(2)}; 1.00 would mean the arithmetic describes this machine)`
+        );
+      }
+    }
     if (kind === "audio") {
       // What is left after the work that was already accounted for. `null` when
       // the subtraction leaves nothing positive, which means the reading says
@@ -5962,6 +6004,12 @@ export class HlsSessionManager {
     const kept = [];
     /** @type {string[]} */
     const dropped = [];
+    // What each height was predicted to do on THIS machine, kept so a session
+    // started at that height can be compared against it once it runs. The
+    // manager holds the last answer, because the offer is computed on the path
+    // that serves every request while a session is created elsewhere.
+    /** @type {Map<number, number | null>} */
+    const predictedByHeight = new Map();
     for (const height of heights) {
       // The height an encoder is ALREADY producing, and the source's own height
       // when the FAMILY serves it by copy — neither has to be predicted,
@@ -6004,7 +6052,7 @@ export class HlsSessionManager {
         0,
         concurrentCostSec - (runningCostByHeight?.get(height) ?? 0)
       );
-      const { speed, sustainable } = canSustainOutput({
+      const { speed } = canSustainOutput({
         benchmark,
         decodeModel: this.decodeCostModel,
         source,
@@ -6012,11 +6060,24 @@ export class HlsSessionManager {
         observedDecodeCostSec,
         concurrentCostSec: concurrentBesideThis
       });
-      if (sustainable) {
+      // The benchmark behind that figure was taken on a QUIET host — one
+      // ffmpeg and nothing else. The machine a step will actually run on is
+      // also running the kernel, the container and whatever else its owner
+      // does, and on the addon host that was measured at 99 % busy with a
+      // quarter of it unattributed. Only the unattributed part is charged
+      // here: our own encoders are already in `concurrentBesideThis` and the
+      // proxy's own work is already priced per megabyte moved.
+      const onThisMachine = correctForAvailability(speed, this.hostAvailability);
+      // Kept against the step's own session, so that when it runs the field
+      // says what the prediction was worth. Without this the only comparison
+      // available is between two figures written minutes apart in different
+      // lines of the log.
+      predictedByHeight.set(height, onThisMachine);
+      if (onThisMachine !== null && onThisMachine >= REALTIME_SPEED_MARGIN) {
         kept.push(height);
         continue;
       }
-      dropped.push(`${height}p=${speed === null ? "n/a" : `${speed.toFixed(2)}x`}`);
+      dropped.push(`${height}p=${onThisMachine === null ? "n/a" : `${onThisMachine.toFixed(2)}x`}`);
     }
     // Written when the ANSWER changes, not when the answer is recomputed. This
     // is asked on the path that serves every playlist, init and segment, and
@@ -6026,12 +6087,19 @@ export class HlsSessionManager {
     if (dropped.length > 0) {
       const line =
         `transcode: not offering ${dropped.join(" ")} — below realtime × ${REALTIME_SPEED_MARGIN} ` +
+        // Said with the figures, because a step refused on a busy machine and
+        // one refused on an idle machine are different facts about the host.
+        (this.hostAvailability?.known
+          ? `on a machine with ${Math.round(this.hostAvailability.share * 100)}% to spare `
+          : "") +
         `(offering ${kept.map((height) => `${height}p`).join(" ")})`;
       if (line !== this.#lastOfferLine) {
         this.#lastOfferLine = line;
         logger.info(line);
       }
+      this.lastPredictedByHeight = predictedByHeight;
     } else {
+      this.lastPredictedByHeight = predictedByHeight;
       this.#lastOfferLine = "";
     }
     return kept;

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/available-share.test.js

@@ -0,0 +1,76 @@
+/**
+ * @file What the machine can spare for a new encoder — and what must not be
+ * charged twice.
+ *
+ * The numbers are the addon host's own, measured 2026-08-17 while a 240p step
+ * ran at 1.01-1.12x against a prediction of 1.83x.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { availableShareFrom, correctForAvailability } from "../services/available-share.js";
+
+test("only the work nobody has been charged for is subtracted", () => {
+  // The field reading: the box is saturated, our encoder has more than half of
+  // it, and the proxy's own work a fifth.
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
+
+  assert.equal(availability.known, true);
+  // 0.99 − 0.76 = 0.23 belongs to the kernel, the container and whatever else
+  // the owner runs. Our own encoders are priced by the concurrency arithmetic
+  // and the proxy's work per megabyte moved; charging them here as well is the
+  // double counting that emptied the quality menu in 2.21.0.
+  assert.ok(Math.abs(availability.unattributed - 0.23) < 1e-9, `${availability.unattributed}`);
+  assert.ok(Math.abs(availability.share - 0.77) < 1e-9, `${availability.share}`);
+});
+
+test("a quiet machine is not corrected at all", () => {
+  const availability = availableShareFrom({ systemBusy: 0.05, encoderShare: 0.04, proxyShare: 0.01 });
+  assert.equal(availability.unattributed, 0);
+  assert.equal(availability.share, 1);
+  assert.equal(correctForAvailability(4, availability), 4);
+});
+
+test("a host that cannot say says so, and nothing is corrected", () => {
+  // Not every host has /proc. An uncorrected figure is honest; a figure
+  // corrected by an invented share is not.
+  const availability = availableShareFrom({ systemBusy: null, encoderShare: null, proxyShare: null });
+  assert.equal(availability.known, false);
+  assert.equal(availability.share, 1);
+  assert.equal(correctForAvailability(2.5, availability), 2.5, "an unknown machine leaves the prediction alone");
+  assert.equal(availableShareFrom().known, false);
+});
+
+test("readings that overlap by a rounding do not produce a negative machine", () => {
+  // The two samples are taken microseconds apart, so our own share can come out
+  // fractionally above the system total.
+  const availability = availableShareFrom({ systemBusy: 0.60, encoderShare: 0.58, proxyShare: 0.05 });
+  assert.equal(availability.unattributed, 0);
+  assert.equal(availability.share, 1);
+});
+
+test("a machine given over entirely to other work leaves nothing", () => {
+  const availability = availableShareFrom({ systemBusy: 1, encoderShare: 0, proxyShare: 0 });
+  assert.equal(availability.share, 0);
+  assert.equal(correctForAvailability(4, availability), 0, "a step cannot be offered on a machine with nothing left");
+});
+
+test("the correction is proportional, and only ever downwards", () => {
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
+  // The field case: a step predicted at 1.83x on a quiet box.
+  const corrected = correctForAvailability(1.83, availability);
+  assert.ok(Math.abs(corrected - 1.4091) < 0.001, `${corrected}`);
+  // And the honest note this test exists to record: 1.41x is still above the
+  // 1.01-1.12x that step actually ran at. This correction closes part of the
+  // gap, not all of it — which is why the per-step field comparison ships with
+  // it rather than after it.
+  assert.ok(corrected > 1.12, "the remaining difference is what the field check is for");
+});
+
+test("nothing is corrected without a prediction to correct", () => {
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.5, proxyShare: 0.2 });
+  assert.equal(correctForAvailability(0, availability), 0);
+  assert.equal(correctForAvailability(Number.NaN, availability), Number.NaN);
+  assert.equal(correctForAvailability(-1, availability), -1);
+});

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`);
+});