@torrent-tv/proxy 2.89.7 → 2.89.9

package/test/fmp4-timestamps.test.js

@@ -1,140 +1,140 @@
-/**
- * Stamping a segment's position onto its fragments.
- *
- * A segment produced by the explicit-cut muxer holds SEVERAL fragments per
- * track — `frag_keyframe` opens one at every keyframe, while a cut point comes
- * only every few keyframes. Writing the segment's start into each of them made
- * them all claim the same decode time, and the player re-fetched the segment
- * forever. The positions inside a segment must therefore survive.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { stampSegmentStartTime } from "../services/encode/segment-formats/mp4-boxes.js";
-
-/**
- * @param {string} type
- * @param {Buffer} body
- * @returns {Buffer}
- */
-function box(type, body) {
-  const header = Buffer.alloc(8);
-  header.writeUInt32BE(8 + body.length, 0);
-  header.write(type, 4, "latin1");
-  return Buffer.concat([header, body]);
-}
-
-/**
- * One fragment: `moof > traf > (tfhd, tfdt)`, plus the payload it describes.
- *
- * @param {{ trackId: number, decodeTime: number, version?: 0 | 1 }} fragment
- * @returns {Buffer}
- */
-function makeFragment({ trackId, decodeTime, version = 1 }) {
-  const tfhdBody = Buffer.alloc(8);
-  tfhdBody.writeUInt32BE(trackId, 4);
-  const tfdtBody = Buffer.alloc(version === 1 ? 12 : 8);
-  tfdtBody[0] = version;
-  if (version === 1) {
-    tfdtBody.writeBigUInt64BE(BigInt(decodeTime), 4);
-  } else {
-    tfdtBody.writeUInt32BE(decodeTime, 4);
-  }
-  const traf = box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
-  return Buffer.concat([box("moof", traf), box("mdat", Buffer.alloc(16, 0x5a))]);
-}
-
-/**
- * Every `tfdt` in order, as `[trackId, decodeTime]`.
- *
- * @param {Buffer} segment
- * @returns {Array<[number, number]>}
- */
-function readDecodeTimes(segment) {
-  const found = [];
-  let offset = 0;
-  let trackId = 0;
-  while (offset + 8 <= segment.length) {
-    const size = segment.readUInt32BE(offset);
-    const type = segment.toString("latin1", offset + 4, offset + 8);
-    if (type === "tfhd") {
-      trackId = segment.readUInt32BE(offset + 12);
-    } else if (type === "tfdt") {
-      const version = segment[offset + 8];
-      found.push([
-        trackId,
-        version === 1 ? Number(segment.readBigUInt64BE(offset + 12)) : segment.readUInt32BE(offset + 12)
-      ]);
-    }
-    // Descend into the containers on the way to `tfdt`; skip anything else
-    // whole, so `mdat` is never walked into.
-    offset += type === "moof" || type === "traf" ? 8 : size;
-  }
-  return found;
-}
-
-test("fragments keep their distance from the start of the segment", () => {
-  // A 6 s segment holding three fragments at 0, 2 and 4 s of its own clock —
-  // the shape measured on the field host.
-  const timescale = 16_000;
-  const segment = Buffer.concat([
-    makeFragment({ trackId: 1, decodeTime: 0 }),
-    makeFragment({ trackId: 1, decodeTime: 2 * timescale }),
-    makeFragment({ trackId: 1, decodeTime: 4 * timescale })
-  ]);
-
-  const stamped = stampSegmentStartTime(segment, 6, new Map([[1, timescale]]));
-
-  assert.deepEqual(
-    readDecodeTimes(stamped).map(([, time]) => time / timescale),
-    [6, 8, 10],
-    "each fragment must land at the segment's start plus its own offset"
-  );
-});
-
-test("each track is shifted by its own base", () => {
-  const videoScale = 16_000;
-  const audioScale = 44_100;
-  // Audio does not start at zero: its frames do not align with the video's.
-  const segment = Buffer.concat([
-    makeFragment({ trackId: 1, decodeTime: 0 }),
-    makeFragment({ trackId: 2, decodeTime: 1024 }),
-    makeFragment({ trackId: 1, decodeTime: 2 * videoScale }),
-    makeFragment({ trackId: 2, decodeTime: 1024 + 2 * audioScale })
-  ]);
-
-  const stamped = stampSegmentStartTime(
-    segment,
-    6,
-    new Map([
-      [1, videoScale],
-      [2, audioScale]
-    ])
-  );
-
-  assert.deepEqual(readDecodeTimes(stamped), [
-    [1, 6 * videoScale],
-    [2, 6 * audioScale],
-    [1, 8 * videoScale],
-    [2, 8 * audioScale]
-  ]);
-});
-
-test("a single fragment is written outright, as before", () => {
-  const stamped = stampSegmentStartTime(
-    makeFragment({ trackId: 1, decodeTime: 1280 }),
-    12,
-    new Map([[1, 16_000]])
-  );
-  assert.deepEqual(readDecodeTimes(stamped), [[1, 12 * 16_000]]);
-});
-
-test("a 32-bit field too small for the position is left alone", () => {
-  const segment = makeFragment({ trackId: 1, decodeTime: 0, version: 0 });
-  const stamped = stampSegmentStartTime(segment, 1_000_000, new Map([[1, 90_000]]));
-  assert.deepEqual(
-    readDecodeTimes(stamped),
-    [[1, 0]],
-    "a wrapped value would send the player somewhere arbitrary; leaving it is the lesser harm"
-  );
-});
+/**
+ * Stamping a segment's position onto its fragments.
+ *
+ * A segment produced by the explicit-cut muxer holds SEVERAL fragments per
+ * track — `frag_keyframe` opens one at every keyframe, while a cut point comes
+ * only every few keyframes. Writing the segment's start into each of them made
+ * them all claim the same decode time, and the player re-fetched the segment
+ * forever. The positions inside a segment must therefore survive.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { stampSegmentStartTime } from "../services/encode/segment-formats/mp4-boxes.js";
+
+/**
+ * @param {string} type
+ * @param {Buffer} body
+ * @returns {Buffer}
+ */
+function box(type, body) {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(8 + body.length, 0);
+  header.write(type, 4, "latin1");
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * One fragment: `moof > traf > (tfhd, tfdt)`, plus the payload it describes.
+ *
+ * @param {{ trackId: number, decodeTime: number, version?: 0 | 1 }} fragment
+ * @returns {Buffer}
+ */
+function makeFragment({ trackId, decodeTime, version = 1 }) {
+  const tfhdBody = Buffer.alloc(8);
+  tfhdBody.writeUInt32BE(trackId, 4);
+  const tfdtBody = Buffer.alloc(version === 1 ? 12 : 8);
+  tfdtBody[0] = version;
+  if (version === 1) {
+    tfdtBody.writeBigUInt64BE(BigInt(decodeTime), 4);
+  } else {
+    tfdtBody.writeUInt32BE(decodeTime, 4);
+  }
+  const traf = box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
+  return Buffer.concat([box("moof", traf), box("mdat", Buffer.alloc(16, 0x5a))]);
+}
+
+/**
+ * Every `tfdt` in order, as `[trackId, decodeTime]`.
+ *
+ * @param {Buffer} segment
+ * @returns {Array<[number, number]>}
+ */
+function readDecodeTimes(segment) {
+  const found = [];
+  let offset = 0;
+  let trackId = 0;
+  while (offset + 8 <= segment.length) {
+    const size = segment.readUInt32BE(offset);
+    const type = segment.toString("latin1", offset + 4, offset + 8);
+    if (type === "tfhd") {
+      trackId = segment.readUInt32BE(offset + 12);
+    } else if (type === "tfdt") {
+      const version = segment[offset + 8];
+      found.push([
+        trackId,
+        version === 1 ? Number(segment.readBigUInt64BE(offset + 12)) : segment.readUInt32BE(offset + 12)
+      ]);
+    }
+    // Descend into the containers on the way to `tfdt`; skip anything else
+    // whole, so `mdat` is never walked into.
+    offset += type === "moof" || type === "traf" ? 8 : size;
+  }
+  return found;
+}
+
+test("fragments keep their distance from the start of the segment", () => {
+  // A 6 s segment holding three fragments at 0, 2 and 4 s of its own clock —
+  // the shape measured on the field host.
+  const timescale = 16_000;
+  const segment = Buffer.concat([
+    makeFragment({ trackId: 1, decodeTime: 0 }),
+    makeFragment({ trackId: 1, decodeTime: 2 * timescale }),
+    makeFragment({ trackId: 1, decodeTime: 4 * timescale })
+  ]);
+
+  const stamped = stampSegmentStartTime(segment, 6, new Map([[1, timescale]]));
+
+  assert.deepEqual(
+    readDecodeTimes(stamped).map(([, time]) => time / timescale),
+    [6, 8, 10],
+    "each fragment must land at the segment's start plus its own offset"
+  );
+});
+
+test("each track is shifted by its own base", () => {
+  const videoScale = 16_000;
+  const audioScale = 44_100;
+  // Audio does not start at zero: its frames do not align with the video's.
+  const segment = Buffer.concat([
+    makeFragment({ trackId: 1, decodeTime: 0 }),
+    makeFragment({ trackId: 2, decodeTime: 1024 }),
+    makeFragment({ trackId: 1, decodeTime: 2 * videoScale }),
+    makeFragment({ trackId: 2, decodeTime: 1024 + 2 * audioScale })
+  ]);
+
+  const stamped = stampSegmentStartTime(
+    segment,
+    6,
+    new Map([
+      [1, videoScale],
+      [2, audioScale]
+    ])
+  );
+
+  assert.deepEqual(readDecodeTimes(stamped), [
+    [1, 6 * videoScale],
+    [2, 6 * audioScale],
+    [1, 8 * videoScale],
+    [2, 8 * audioScale]
+  ]);
+});
+
+test("a single fragment is written outright, as before", () => {
+  const stamped = stampSegmentStartTime(
+    makeFragment({ trackId: 1, decodeTime: 1280 }),
+    12,
+    new Map([[1, 16_000]])
+  );
+  assert.deepEqual(readDecodeTimes(stamped), [[1, 12 * 16_000]]);
+});
+
+test("a 32-bit field too small for the position is left alone", () => {
+  const segment = makeFragment({ trackId: 1, decodeTime: 0, version: 0 });
+  const stamped = stampSegmentStartTime(segment, 1_000_000, new Map([[1, 90_000]]));
+  assert.deepEqual(
+    readDecodeTimes(stamped),
+    [[1, 0]],
+    "a wrapped value would send the player somewhere arbitrary; leaving it is the lesser harm"
+  );
+});

package/test/fmp4-track-completeness.test.js

@@ -1,41 +1,41 @@
-/**
- * @file A segment that is short of a track must not be served.
- *
- * A run that is terminated closes its current output file properly — trailing
- * index and all — but the file holds only what had been muxed by then, and
- * after a seek-restart that is routinely one track of two. Nothing about it
- * looks unfinished, so the readiness rule called it done and served it, and the
- * player could not complete the seek. Measured 2026-08-06: segment #133 carried
- * one `tfdt` where its neighbours carried two, every request for it was
- * answered in 98 ms, and the viewer sat on a spinner.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
-// Build a minimal init declaring two tracks, and fragments declaring one/two.
-function box(type, body) {
-  const b = Buffer.alloc(8 + body.length);
-  b.writeUInt32BE(8 + body.length, 0); b.write(type, 4, "latin1"); body.copy(b, 8);
-  return b;
-}
-function mdhd(timescale) { const b = Buffer.alloc(20); b.writeUInt32BE(timescale, 12); return box("mdhd", b); }
-function tkhd(id) { const b = Buffer.alloc(84); b.writeUInt32BE(id, 12); return box("tkhd", b); }
-function trak(id, ts) { return box("trak", Buffer.concat([tkhd(id), box("mdia", mdhd(ts))])); }
-const init = box("moov", Buffer.concat([trak(1, 16000), trak(2, 48000)]));
-function tfhd(id) { const b = Buffer.alloc(8); b.writeUInt32BE(id, 4); return box("tfhd", b); }
-function moof(ids) { return box("moof", Buffer.concat(ids.map((id) => box("traf", tfhd(id))))); }
-
-test("a segment with every track is accepted", () => {
-  assert.equal(fmp4Format.hasEveryTrack(moof([1, 2]), init), true);
-});
-test("a segment left short of a track by a killed run is refused", () => {
-  assert.equal(fmp4Format.hasEveryTrack(moof([1]), init), false,
-    "one track of two is what a terminated run leaves behind, and it looks complete");
-});
-test("an empty file is refused", () => {
-  assert.equal(fmp4Format.hasEveryTrack(Buffer.alloc(0), init), false);
-});
-test("without an init there is nothing to compare against, so it is allowed", () => {
-  assert.equal(fmp4Format.hasEveryTrack(moof([1]), null), true);
-});
+/**
+ * @file A segment that is short of a track must not be served.
+ *
+ * A run that is terminated closes its current output file properly — trailing
+ * index and all — but the file holds only what had been muxed by then, and
+ * after a seek-restart that is routinely one track of two. Nothing about it
+ * looks unfinished, so the readiness rule called it done and served it, and the
+ * player could not complete the seek. Measured 2026-08-06: segment #133 carried
+ * one `tfdt` where its neighbours carried two, every request for it was
+ * answered in 98 ms, and the viewer sat on a spinner.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
+// Build a minimal init declaring two tracks, and fragments declaring one/two.
+function box(type, body) {
+  const b = Buffer.alloc(8 + body.length);
+  b.writeUInt32BE(8 + body.length, 0); b.write(type, 4, "latin1"); body.copy(b, 8);
+  return b;
+}
+function mdhd(timescale) { const b = Buffer.alloc(20); b.writeUInt32BE(timescale, 12); return box("mdhd", b); }
+function tkhd(id) { const b = Buffer.alloc(84); b.writeUInt32BE(id, 12); return box("tkhd", b); }
+function trak(id, ts) { return box("trak", Buffer.concat([tkhd(id), box("mdia", mdhd(ts))])); }
+const init = box("moov", Buffer.concat([trak(1, 16000), trak(2, 48000)]));
+function tfhd(id) { const b = Buffer.alloc(8); b.writeUInt32BE(id, 4); return box("tfhd", b); }
+function moof(ids) { return box("moof", Buffer.concat(ids.map((id) => box("traf", tfhd(id))))); }
+
+test("a segment with every track is accepted", () => {
+  assert.equal(fmp4Format.hasEveryTrack(moof([1, 2]), init), true);
+});
+test("a segment left short of a track by a killed run is refused", () => {
+  assert.equal(fmp4Format.hasEveryTrack(moof([1]), init), false,
+    "one track of two is what a terminated run leaves behind, and it looks complete");
+});
+test("an empty file is refused", () => {
+  assert.equal(fmp4Format.hasEveryTrack(Buffer.alloc(0), init), false);
+});
+test("without an init there is nothing to compare against, so it is allowed", () => {
+  assert.equal(fmp4Format.hasEveryTrack(moof([1]), null), true);
+});

package/test/format-keyed-outputs.test.js

@@ -1,78 +1,78 @@
-/**
- * @file An output is named by the format it produces, and nothing may put
- * pieces of another format under that name.
- *
- * Two ways that could still happen once the name became the format: a
- * directory left by an earlier version, whose key named the box a viewer asked
- * for and so cannot say what format is inside; and a hardware encoder failing,
- * after which the proxy encodes with software while outputs named by the failed
- * encoder are still being watched.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { existsSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { managerWithOwnStore } from "./helpers/manager.js";
-import { outputSpec } from "./helpers/output-spec.js";
-import { ENCODE_EXIT } from "../services/encode/encode-exit.js";
-import { SourceFile } from "../services/media/SourceFile.js";
-
-test("a directory whose key names an asked-for box is not adopted, and one naming a format is", (t) => {
-  const { store, root, manager, cleanup } = managerWithOwnStore();
-  t.after(cleanup);
-  const oldKey = "torrent:abc:fmt=fmp4:grid=even@0:video-only:v=0/enc:1280x720:budget";
-  const newKey = outputSpec({ sourceKey: "torrent:abc", transcodeVideo: true, width: 1280, height: 720, audioSeparate: true }).toKey();
-  const oldDir = store.directoryFor(oldKey);
-  const newDir = store.directoryFor(newKey);
-  writeFileSync(path.join(oldDir, "segment-00000.mp4"), Buffer.alloc(10));
-  writeFileSync(path.join(newDir, "segment-00000.mp4"), Buffer.alloc(10));
-
-  const result = manager.lifecycle.adoptSegmentsLeftBehind();
-
-  assert.equal(result.adopted, 1);
-  assert.equal(result.dropped, 1);
-  assert.equal(existsSync(oldDir), false, "the old directory goes");
-  assert.equal(existsSync(newDir), true, "the named format stays");
-  assert.ok(root);
-});
-
-test("when a hardware encoder fails, the outputs it named are closed rather than continued by software", async (t) => {
-  const { manager, cleanup } = managerWithOwnStore({
-    videoEncoder: { kind: "vaapi", name: "h264_vaapi", inputArgs: [] }
-  });
-  t.after(async () => {
-    await manager.lifecycle.disposeAll();
-    cleanup();
-  });
-  manager.encodeRuns.planEncodersNow = () => {};
-  manager.encodeRuns.planEncodersSoon = () => {};
-  const file = new SourceFile({ sourceKey: "torrent:abc", fileIndex: 0, name: "film.mkv" });
-  const record = (id, encoder) => {
-    const spec = outputSpec({ sourceKey: "torrent:abc", transcodeVideo: true, width: 1280, height: 720, encoder });
-    const output = { id, spec, get outputKey() { return this.spec.toKey(); }, file };
-    manager.outputs.set(id, output);
-    return output;
-  };
-  const failing = record("aaaaaaaa00000001", "h264_vaapi");
-  const software = record("aaaaaaaa00000002", "libx264");
-  const run = { from: 0, to: -1, argsDescribed: "ffmpeg …" };
-  manager.encodeOrchestrator.adopt(failing.outputKey, run);
-
-  manager.encodeRuns.noteRunEnded(failing, run, {
-    address: failing.outputKey,
-    run,
-    ending: ENCODE_EXIT.FAILED,
-    from: 0,
-    to: -1,
-    livedMs: 30_000,
-    because: "vaapi failed",
-    lastError: "vaapi failed",
-    producedCount: 3
-  });
-  await new Promise((resolve) => setImmediate(resolve));
-
-  assert.equal(manager.encoders.current.kind, "software");
-  assert.equal(manager.outputs.has(failing.id), false, "an output of the failed encoder is closed");
-  assert.equal(manager.outputs.has(software.id), true, "an output of another encoder is untouched");
-});
+/**
+ * @file An output is named by the format it produces, and nothing may put
+ * pieces of another format under that name.
+ *
+ * Two ways that could still happen once the name became the format: a
+ * directory left by an earlier version, whose key named the box a viewer asked
+ * for and so cannot say what format is inside; and a hardware encoder failing,
+ * after which the proxy encodes with software while outputs named by the failed
+ * encoder are still being watched.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { managerWithOwnStore } from "./helpers/manager.js";
+import { outputSpec } from "./helpers/output-spec.js";
+import { ENCODE_EXIT } from "../services/encode/encode-exit.js";
+import { SourceFile } from "../services/media/SourceFile.js";
+
+test("a directory whose key names an asked-for box is not adopted, and one naming a format is", (t) => {
+  const { store, root, manager, cleanup } = managerWithOwnStore();
+  t.after(cleanup);
+  const oldKey = "torrent:abc:fmt=fmp4:grid=even@0:video-only:v=0/enc:1280x720:budget";
+  const newKey = outputSpec({ sourceKey: "torrent:abc", transcodeVideo: true, width: 1280, height: 720, audioSeparate: true }).toKey();
+  const oldDir = store.directoryFor(oldKey);
+  const newDir = store.directoryFor(newKey);
+  writeFileSync(path.join(oldDir, "segment-00000.mp4"), Buffer.alloc(10));
+  writeFileSync(path.join(newDir, "segment-00000.mp4"), Buffer.alloc(10));
+
+  const result = manager.lifecycle.adoptSegmentsLeftBehind();
+
+  assert.equal(result.adopted, 1);
+  assert.equal(result.dropped, 1);
+  assert.equal(existsSync(oldDir), false, "the old directory goes");
+  assert.equal(existsSync(newDir), true, "the named format stays");
+  assert.ok(root);
+});
+
+test("when a hardware encoder fails, the outputs it named are closed rather than continued by software", async (t) => {
+  const { manager, cleanup } = managerWithOwnStore({
+    videoEncoder: { kind: "vaapi", name: "h264_vaapi", inputArgs: [] }
+  });
+  t.after(async () => {
+    await manager.lifecycle.disposeAll();
+    cleanup();
+  });
+  manager.encodeRuns.planEncodersNow = () => {};
+  manager.encodeRuns.planEncodersSoon = () => {};
+  const file = new SourceFile({ sourceKey: "torrent:abc", fileIndex: 0, name: "film.mkv" });
+  const record = (id, encoder) => {
+    const spec = outputSpec({ sourceKey: "torrent:abc", transcodeVideo: true, width: 1280, height: 720, encoder });
+    const output = { id, spec, get outputKey() { return this.spec.toKey(); }, file };
+    manager.outputs.set(id, output);
+    return output;
+  };
+  const failing = record("aaaaaaaa00000001", "h264_vaapi");
+  const software = record("aaaaaaaa00000002", "libx264");
+  const run = { from: 0, to: -1, argsDescribed: "ffmpeg …" };
+  manager.encodeOrchestrator.adopt(failing.outputKey, run);
+
+  manager.encodeRuns.noteRunEnded(failing, run, {
+    address: failing.outputKey,
+    run,
+    ending: ENCODE_EXIT.FAILED,
+    from: 0,
+    to: -1,
+    livedMs: 30_000,
+    because: "vaapi failed",
+    lastError: "vaapi failed",
+    producedCount: 3
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.equal(manager.encoders.current.kind, "software");
+  assert.equal(manager.outputs.has(failing.id), false, "an output of the failed encoder is closed");
+  assert.equal(manager.outputs.has(software.id), true, "an output of another encoder is untouched");
+});

package/test/health-metrics.test.js

@@ -1,38 +1,36 @@
-/**
- * @file What a proxy says about itself, and what the pool scores it on.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import os from "node:os";
-
-import { collectHealthMetrics } from "../services/transport/health-collector.js";
-import { availableMemoryBytes } from "../services/storage/machine-memory.js";
-
-test("free memory is what could be given out, not what is idle this instant", () => {
-  const available = availableMemoryBytes();
-  assert.ok(Number.isFinite(available) && available > 0);
-
-  // On Linux this reads the kernel's own `MemAvailable`, and it is at least
-  // `os.freemem()` by construction: the kernel keeps free memory low on purpose
-  // and fills the rest with cache, which it hands back the moment anything
-  // asks. The old reading was `os.freemem()`, so a host with 4 GB of cache and
-  // 200 MB genuinely free reported itself nearly full while it had 4.2 GB to
-  // give — and that figure weighs 0.4 of every proxy's score.
-  if (os.platform() === "linux") {
-    assert.ok(
-      available >= os.freemem(),
-      `MemAvailable ${available} is below freemem ${os.freemem()}, which cannot be`
-    );
-  }
-});
-
-test("the health report is three bounded numbers", () => {
-  const metrics = collectHealthMetrics({ availableMemoryBytes });
-  assert.ok(metrics.cpuLoad >= 0);
-  assert.ok(metrics.memFree > 0 && metrics.memFree <= 1);
-  assert.ok(Number.isInteger(metrics.uptime) && metrics.uptime >= 0);
-  // Three decimals, so a value that has not really moved does not produce a
-  // different message on every poll.
-  assert.equal(metrics.memFree, Math.round(metrics.memFree * 1000) / 1000);
-});
+/**
+ * @file What a proxy says about itself, and what the pool scores it on.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+
+import { collectHealthMetrics } from "../services/transport/health-collector.js";
+import { availableMemory, availableMemoryBytes } from "../services/storage/machine-memory.js";
+
+test("free memory is what could be given out, not what is idle this instant", () => {
+  const available = availableMemory();
+  assert.ok(Number.isFinite(available.bytes) && available.bytes > 0);
+
+  // On Linux this is the kernel's own `MemAvailable`, not `os.freemem()`: the
+  // kernel keeps free memory low on purpose and fills the rest with cache, which
+  // it hands back the moment anything asks. The old reading was `os.freemem()`,
+  // so a host with 4 GB of cache and 200 MB genuinely free reported itself nearly
+  // full while it had 4.2 GB to give — and that figure weighs 0.4 of every
+  // proxy's score. Asked of the reading itself: comparing it with a second
+  // reading taken a moment later measures whatever else the machine was doing.
+  if (os.platform() === "linux") {
+    assert.equal(available.measured, true, "the kernel's own estimate was not read");
+  }
+});
+
+test("the health report is three bounded numbers", () => {
+  const metrics = collectHealthMetrics({ availableMemoryBytes });
+  assert.ok(metrics.cpuLoad >= 0);
+  assert.ok(metrics.memFree > 0 && metrics.memFree <= 1);
+  assert.ok(Number.isInteger(metrics.uptime) && metrics.uptime >= 0);
+  // Three decimals, so a value that has not really moved does not produce a
+  // different message on every poll.
+  assert.equal(metrics.memFree, Math.round(metrics.memFree * 1000) / 1000);
+});