@torrent-tv/proxy 2.55.12 → 2.55.14

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2.55.14
+
+- **Fix**: `utp-native` moves to 2.5.3-ttv.5, which carries ten defects found by reading the whole binding after the seventh crash of this family named its frame. Three callbacks read the connection pointer without checking it exists — and the socket carries none unless it was accepted or dialled, while its destructor announces itself regardless; the ttv.4 patch created one such path itself. The read callback copied at an accumulated offset without ever consulting the buffer length it maintains, so a peer sending more between two hand-offs wrote past the end — heap corruption does not fault where it happens, which is what six deaths inside libuv bookkeeping look like. A connection could be destroyed twice, deleting already-deleted napi references, and the socket pointer was never cleared. The callback macro checked none of the three napi results it then used. Plus IPv6, which the module never had at all, and the resolver that fed it addresses it could not use. Tests on the target: 77 checks, no failures — two of them were failing or hanging before.
+- **Chore**: `--sctp-debug` is removed. It set node-datachannel's log level to verbose and filtered for `usrsctp:` lines, which only exist in a binary built with `SCTP_DEBUG=ON` — a source rebuild of libdatachannel that is not done any more. A flag that cannot do anything in any image we ship is an untruthful interface; the delivery probes of 2.55.13 answer the question it was wanted for (a probe on an unordered, no-retransmit channel passes head-of-line blocking in another stream but not a closed receive window) without touching the native build.
+
+## 2.55.13
+
+- **New**: numbered delivery probes (`services/delivery-probe.js`). Every channel of a connection carries a numbered probe twice a second; the far end echoes back the highest number it saw on each, and the gaps are read into a verdict — `flowing`, `stream-stuck` (a retransmission held up in one stream), `association-stopped` (the window shut or transmission halted), `reverse-direction-gone`. The proxy's own counters could never separate those: libdatachannel's `bytesSent` counts bytes accepted into usrsctp, not bytes put on the wire. Logged as `[dc-probe]`, with the numbers that produced each verdict beside it.
+- **New**: the far end's own account of itself is logged as `[dc-far]` — tab visibility, event-loop lag, the longest the channel's message handler ran, the transport's received bytes and per-channel message counts. A page that has stopped draining the channel and a sender that has stopped transmitting look identical from here; this is the difference.
+- **New**: `--delivery-sink` serves `GET /api/delivery-sink?bytes=N`, a torrent-free stream of a repeating pattern, so gigabytes can be pushed through a data channel on demand. Off without the flag (404), and it exists because the delivery freeze takes hundreds of megabytes and the real transport to appear at all.
+
 ## 2.55.12
 
 - **Fix**: `--sctp-debug` now passes the required callback to `initLogger` (`node-datachannel` 0.32.x needs two args). The 2.55.10 single-arg call always threw `Function expected` and left verbose logging off.

package/bin/cli.js

@@ -80,6 +80,7 @@ program
   .option("--name <name>", "Display name")
   .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
   .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
+  .option("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
   .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
   .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
   .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
@@ -97,7 +98,6 @@ program
     DEFAULT_SEGMENT_FORMAT_ID
   )
   .option("--token <token>", "Registration token", "")
-  .option("--sctp-debug", "Enable verbose SCTP debug logging (SCTP_DEBUG build only)")
   .addHelpText("after", HELP_EXAMPLES);
 
 program.parse(process.argv);
@@ -283,24 +283,6 @@ async function shutdown(signal) {
 
 try {
   logToFile(options.logFile);
-  // Diagnostic: verbose SCTP logging. The binary must have been built with
-  // SCTP_DEBUG=ON (addon 0.48.0); this flag merely sets the log level.
-  if (options.sctpDebug) {
-    try {
-      const mod = await import("node-datachannel");
-      const target = mod.default ?? mod;
-      if (typeof target.initLogger === "function") {
-        target.initLogger("Verbose", (level, message) => {
-          if (typeof message === "string" && message.startsWith("usrsctp:")) {
-            logger.info(message);
-          }
-        });
-        logger.info("SCTP debug verbose logging enabled");
-      }
-    } catch (error) {
-      logger.warn(`Failed to enable SCTP debug: ${error?.message ?? error}`);
-    }
-  }
   if (transcodeAudio) {
     assertFfmpegAvailability();
   }
@@ -313,6 +295,7 @@ try {
     memoryBytes,
     segmentFormat: options.segmentFormat,
     stateDir: options.stateDir,
+    deliverySink: options.deliverySink === true,
     // Late-bound the same way `webRtcManager` is below: the torrent pool is
     // built inside `startProxyServer`, before `dataChannelHandler` — the
     // thing that actually owns a channel to push down — exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.55.12",
+  "version": "2.55.14",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -45,6 +45,6 @@
     "@biomejs/biome": "^2.5.7"
   },
   "overrides": {
-    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.4"
+    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.5"
   }
 }

package/routes/api/delivery-sink/get.js

@@ -0,0 +1,68 @@
+/**
+ * A stream of bytes with no torrent behind it, for measuring delivery alone.
+ *
+ * GET /api/delivery-sink?bytes=8388608
+ *
+ * The delivery freeze (roadmap item 11) takes hundreds of megabytes to appear
+ * and needs the real transport to appear at all, so reproducing it means
+ * pushing gigabytes through a data channel on demand. Doing that through a real
+ * file drags in the swarm, the encoder and the disk, none of which is under
+ * test and each of which has its own stalls; this route removes them and leaves
+ * the path the question is about: the same handler, the same chunk loop, the
+ * same backpressure, the same channel.
+ *
+ * The body is a repeating pattern rather than zeroes, so a receiver can verify
+ * it got the bytes it was promised in the order they were sent — a silent
+ * truncation would otherwise read as a successful transfer.
+ *
+ * Enabled only when the proxy was started with `--delivery-sink`; without the
+ * flag the route answers 404, so an ordinary install has no such endpoint.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ enabled: boolean }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiDeliverySinkGet(req, reply, { enabled } = {}) {
+  if (enabled !== true) {
+    return reply.code(404).send({ error: "Not found." });
+  }
+
+  const requested = Number((req.query ?? {}).bytes);
+  const total = Number.isFinite(requested)
+    ? Math.min(Math.max(Math.trunc(requested), 0), MAX_SINK_BYTES)
+    : DEFAULT_SINK_BYTES;
+
+  // One buffer, reused: allocating a fresh chunk per iteration would make this
+  // route measure the allocator as much as the transport.
+  const chunk = Buffer.alloc(CHUNK_BYTES);
+  for (let i = 0; i < CHUNK_BYTES; i += 1) {
+    chunk[i] = i % 251; // 251 is prime, so the pattern does not align to any power of two.
+  }
+
+  reply.header("content-type", "application/octet-stream");
+  reply.header("content-length", String(total));
+  reply.header("cache-control", "no-store");
+
+  let sent = 0;
+  const stream = new ReadableStream({
+    pull(controller) {
+      if (sent >= total) {
+        controller.close();
+        return;
+      }
+      const size = Math.min(CHUNK_BYTES, total - sent);
+      controller.enqueue(size === CHUNK_BYTES ? chunk : chunk.subarray(0, size));
+      sent += size;
+    }
+  });
+
+  return reply.send(stream);
+}
+
+/** Chunk size, matching what a body read hands the send loop for a real file. */
+const CHUNK_BYTES = 64 * 1024;
+/** Default when no size is asked for: about one segment of 1080p. */
+const DEFAULT_SINK_BYTES = 8 * 1024 * 1024;
+/** Ceiling, so one request cannot ask the proxy for an unbounded stream. */
+const MAX_SINK_BYTES = 64 * 1024 * 1024;

package/server.js

@@ -16,6 +16,7 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { handleHealthGet } from "./routes/health/get.js";
 import { handleHealthzGet } from "./routes/healthz/get.js";
+import { handleApiDeliverySinkGet } from "./routes/api/delivery-sink/get.js";
 import { handleApiSourcesPost } from "./routes/api/sources/post.js";
 import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
 import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
@@ -81,7 +82,8 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
  */
 export async function startProxyServer({
-  host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat, stateDir, onSubtitleCues
+  host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat, stateDir, onSubtitleCues,
+  deliverySink = false
 }) {
   const app = Fastify({
     // No practical body-size limit — the proxy server is localhost-only and
@@ -209,6 +211,10 @@ export async function startProxyServer({
 
   app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));
   app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply, { version }));
+  // Off unless --delivery-sink was given; see the route for why it exists.
+  app.get("/api/delivery-sink", async (req, reply) =>
+    handleApiDeliverySinkGet(req, reply, { enabled: deliverySink === true })
+  );
   app.post("/api/sources", async (req, reply) =>
     handleApiSourcesPost(req, reply, { sourceRegistry })
   );

package/services/data-channel-handler.js

@@ -12,10 +12,12 @@
  * ```
  * { type: "request",  requestId, method, path, query, headers, body }
  * { type: "ping",     id }
+ * { type: "probe-echo", seen: { <label>: seq }, report }
  * ```
  *
  * Proxy → Browser
  * ```
+ * { type: "probe",          seq, sentAt }                   (JSON string)
  * { type: "response-start", requestId, status, headers }   (JSON string)
  * { type: "response-error", requestId, error: string }     (JSON string)
  * { type: "pong",           id }                            (JSON string)
@@ -44,6 +46,7 @@
 /** @import { DataChannel } from 'node-datachannel' */
 
 import { deriveSourceKey } from "./torrent-source-key.js";
+import { createDeliveryProbe } from "./delivery-probe.js";
 
 /**
  * Configuration for the data channel handler.
@@ -417,6 +420,11 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
   const requestIdCache = new Map();
 
   const watchSendQueue = makeSendQueueWatcher({ log: (message) => log(message), getTransportSnapshot, witness });
+  // Numbered probes on every channel, and the browser's echo of what it saw.
+  // The proxy's own counters cannot say whether bytes it handed to usrsctp were
+  // ever put on the wire; the far end can, and it keeps answering throughout a
+  // freeze. See services/delivery-probe.js.
+  const deliveryProbe = createDeliveryProbe({ log: (message) => log(message) });
 
   /**
    * @param {string} message
@@ -440,6 +448,7 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
     const label = typeof channel.getLabel === "function" ? channel.getLabel() : "?";
     log(`[dc] Session ${tag}: channel open`);
     const stopWatchdog = watchSendQueue(sessionId, tag, label, channel);
+    deliveryProbe.attach(sessionId, tag, label, channel);
 
     // Partial chunked-request bodies in flight on THIS channel, keyed by
     // requestId. Each entry buffers frames until the done frame, then runs the
@@ -568,11 +577,35 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
 
       if (message.type === "ping") {
         send(channel, { type: "pong", id: message.id });
+        return;
+      }
+
+      // The far end's answer to the numbered probes, plus what it can see of
+      // its own receiving. It travels browser to proxy, the direction that goes
+      // on working through a freeze, so it arrives when nothing else does.
+      if (message.type === "probe-echo") {
+        deliveryProbe.noteEcho(sessionId, message);
+        if (message.report && typeof message.report === "object") {
+          const report = message.report;
+          const channels = report.channels && typeof report.channels === "object"
+            ? Object.entries(report.channels)
+                .map(([name, counters]) => `${name}=${counters?.messages ?? "?"}msg/${counters?.bytes ?? "?"}B`)
+                .join(" ")
+            : "";
+          log(
+            `[dc-far] ${tag} visibility=${report.visibility ?? "?"} ` +
+            `loopLag=${report.loopLagMs ?? "?"}ms handler=${report.handlerMaxMs ?? "?"}ms ` +
+            `transportIn=${report.transportBytesReceived ?? "?"} ${channels} ` +
+            `pending=${report.pending ?? "?"} at=${new Date().toISOString()}`
+          );
+        }
+        return;
       }
     });
 
     channel.onClosed(() => {
       stopWatchdog();
+      deliveryProbe.detach(sessionId, channel);
       for (const entry of partials.values()) {
         clearTimeout(entry.timer);
       }

package/services/delivery-probe.js

@@ -0,0 +1,255 @@
+/**
+ * @file Numbered delivery probes, and the verdict they make possible.
+ *
+ * The delivery freeze (roadmap item 11) looks identical from the proxy in two
+ * cases that need opposite fixes: usrsctp stopped transmitting, or the browser
+ * closed its receive window because the page stopped draining the channel. The
+ * proxy's own counters cannot separate them — libdatachannel's `bytesSent`
+ * counts bytes ACCEPTED into usrsctp, not bytes put on the wire — so the
+ * reading has to come from the far end.
+ *
+ * Two facts make that cheap. The reverse direction keeps working throughout the
+ * freeze (browser to proxy requests arrive and are answered for the whole
+ * episode, 88 min in the 2026-08-24 case), so the browser can always report.
+ * And SCTP orders per STREAM, so a probe on a channel opened UNORDERED and
+ * WITHOUT retransmission passes head-of-line blocking in another stream but
+ * neither a closed receive window nor a transmitter that stopped.
+ *
+ * So: number a probe every {@link PROBE_INTERVAL_MS} on every channel of the
+ * connection, have the browser echo back the highest number it has seen on
+ * each, and read the gaps:
+ *
+ *   every channel current                to flowing
+ *   ordered behind, unreliable current   to a retransmission stuck in a stream
+ *   both behind, echoes still arriving   to the association stopped transmitting
+ *   no echo at all                       to the reverse direction went too
+ *
+ * The verdict is computed from the gaps, not chosen, and every line prints the
+ * numbers that produced it.
+ */
+
+/**
+ * How often a probe is numbered and sent on every channel.
+ *
+ * Half a second, because the transport heartbeat is five and that was the whole
+ * resolution the 2026-08-24 episode had: the onset could be placed no closer
+ * than the five seconds between two lines. Sending is cheap - a probe is a few
+ * dozen bytes - and the interval is NOT the verdict: a healthy burst can hold a
+ * probe up behind queued data, so the verdict takes {@link MISSES_FOR_VERDICT}
+ * consecutive probes.
+ */
+export const PROBE_INTERVAL_MS = 500;
+
+/**
+ * How many probes may be outstanding on a channel before it counts as behind.
+ *
+ * A segment of 6-11 MB leaves in well under a second when the link is healthy,
+ * but it shares the association with the probe, so one or two probes can
+ * legitimately sit behind it. Four is two seconds - longer than any measured
+ * healthy burst, shorter than the five seconds the old heartbeat needed to say
+ * anything at all.
+ */
+export const MISSES_FOR_VERDICT = 4;
+
+/** The label the browser gives the unordered, non-retransmitting channel. */
+export const UNRELIABLE_LABEL = "proxy-fast";
+
+/** An echo older than this means the reverse direction has stopped too. */
+const ECHO_STALE_MS = 5_000;
+
+/** How often the probe state is written to the log while nothing changes. */
+const REPORT_INTERVAL_MS = 5_000;
+
+/**
+ * One connection's probe state.
+ *
+ * @typedef {Object} ProbeConnection
+ * @property {string} tag
+ * @property {Map<import('node-datachannel').DataChannel, string>} channels
+ * @property {number} seq        - Highest probe number sent.
+ * @property {number} sentAt     - When that probe was sent.
+ * @property {Map<string, number>} seen - Label to the highest number the browser reported.
+ * @property {number} echoAt     - When the last echo arrived (0 = never).
+ * @property {number} echoes     - How many echoes have arrived.
+ * @property {string} verdict    - Last verdict reported, so a change is logged at once.
+ * @property {number} reportedAt - When the state was last written to the log.
+ * @property {ReturnType<typeof setInterval> | null} timer
+ */
+
+/**
+ * Read the gaps and say what they mean.
+ *
+ * Exported so the rule is testable without a connection: the same numbers
+ * always produce the same word.
+ *
+ * @param {{ seq: number, seen: Map<string, number> | Record<string, number>, labels: string[], echoes: number, echoAgeMs: number | null }} state
+ * @returns {{ verdict: string, detail: string }}
+ */
+export function readProbeState(state) {
+  const seenOf = (label) =>
+    state.seen instanceof Map ? state.seen.get(label) : state.seen?.[label];
+  const parts = [];
+  let orderedBehind = false;
+  let unreliableBehind = false;
+  let unreliableKnown = false;
+  for (const label of state.labels) {
+    const seen = seenOf(label);
+    const gap = Number.isInteger(seen) ? state.seq - Number(seen) : null;
+    parts.push(`${label}=${seen ?? "?"}(gap ${gap ?? "?"})`);
+    const behind = gap === null || gap >= MISSES_FOR_VERDICT;
+    if (label === UNRELIABLE_LABEL) {
+      unreliableKnown = true;
+      unreliableBehind = behind;
+    } else if (behind) {
+      orderedBehind = true;
+    }
+  }
+  const detail =
+    `sent=${state.seq} ${parts.join(" ")} ` +
+    `echoAge=${state.echoAgeMs === null ? "never" : `${state.echoAgeMs}ms`}`;
+
+  if (state.echoes === 0) {
+    return { verdict: "no-echo-yet", detail };
+  }
+  if (state.echoAgeMs !== null && state.echoAgeMs > ECHO_STALE_MS) {
+    return { verdict: "reverse-direction-gone", detail };
+  }
+  if (!orderedBehind && !(unreliableKnown && unreliableBehind)) {
+    return { verdict: "flowing", detail };
+  }
+  if (orderedBehind && unreliableKnown && !unreliableBehind) {
+    return { verdict: "stream-stuck", detail };
+  }
+  if (orderedBehind) {
+    return {
+      verdict: unreliableKnown ? "association-stopped" : "ordered-behind-no-comparison",
+      detail
+    };
+  }
+  return { verdict: "unreliable-behind-only", detail };
+}
+
+/**
+ * Create the probe service. One instance serves every session.
+ *
+ * @param {Object} options
+ * @param {(message: string) => void} options.log
+ * @param {number} [options.intervalMs]
+ * @returns {{
+ *   attach: (sessionId: string, tag: string, label: string, channel: import('node-datachannel').DataChannel) => void,
+ *   detach: (sessionId: string, channel: import('node-datachannel').DataChannel) => void,
+ *   noteEcho: (sessionId: string, echo: object) => void,
+ *   dispose: () => void
+ * }}
+ */
+export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS }) {
+  /** @type {Map<string, ProbeConnection>} */
+  const connections = new Map();
+
+  /**
+   * Send this tick's probe on every channel of one connection, then report.
+   *
+   * @param {ProbeConnection} connection
+   * @returns {void}
+   */
+  function tick(connection) {
+    const now = Date.now();
+    connection.seq += 1;
+    connection.sentAt = now;
+    const message = JSON.stringify({ type: "probe", seq: connection.seq, sentAt: now });
+    for (const channel of connection.channels.keys()) {
+      try {
+        channel.sendMessage(message);
+      } catch {
+        // A channel closing between the check and the send is ordinary.
+      }
+    }
+
+    const { verdict, detail } = readProbeState({
+      seq: connection.seq,
+      seen: connection.seen,
+      labels: [...new Set(connection.channels.values())],
+      echoes: connection.echoes,
+      echoAgeMs: connection.echoAt === 0 ? null : now - connection.echoAt
+    });
+    if (verdict !== connection.verdict || now - connection.reportedAt >= REPORT_INTERVAL_MS) {
+      connection.verdict = verdict;
+      connection.reportedAt = now;
+      log(`[dc-probe] ${connection.tag} ${verdict} — ${detail} at=${new Date(now).toISOString()}`);
+    }
+  }
+
+  return {
+    attach(sessionId, tag, label, channel) {
+      let connection = connections.get(sessionId);
+      if (!connection) {
+        connection = {
+          tag,
+          channels: new Map(),
+          seq: 0,
+          sentAt: 0,
+          seen: new Map(),
+          echoAt: 0,
+          echoes: 0,
+          verdict: "",
+          reportedAt: 0,
+          timer: null
+        };
+        connections.set(sessionId, connection);
+      }
+      connection.channels.set(channel, label);
+      if (connection.timer === null) {
+        const held = connection;
+        connection.timer = setInterval(() => tick(held), intervalMs);
+        // The probe must never be the reason a process stays alive.
+        if (typeof connection.timer.unref === "function") {
+          connection.timer.unref();
+        }
+      }
+    },
+
+    detach(sessionId, channel) {
+      const connection = connections.get(sessionId);
+      if (!connection) {
+        return;
+      }
+      connection.channels.delete(channel);
+      if (connection.channels.size === 0) {
+        if (connection.timer !== null) {
+          clearInterval(connection.timer);
+          connection.timer = null;
+        }
+        if (connections.get(sessionId) === connection) {
+          connections.delete(sessionId);
+        }
+      }
+    },
+
+    noteEcho(sessionId, echo) {
+      const connection = connections.get(sessionId);
+      if (!connection || !echo || typeof echo !== "object") {
+        return;
+      }
+      const seen = echo.seen;
+      if (seen && typeof seen === "object") {
+        for (const [label, value] of Object.entries(seen)) {
+          if (Number.isInteger(value)) {
+            connection.seen.set(label, value);
+          }
+        }
+      }
+      connection.echoAt = Date.now();
+      connection.echoes += 1;
+    },
+
+    dispose() {
+      for (const connection of connections.values()) {
+        if (connection.timer !== null) {
+          clearInterval(connection.timer);
+          connection.timer = null;
+        }
+      }
+      connections.clear();
+    }
+  };
+}

package/test/delivery-probe.test.js

@@ -0,0 +1,78 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { readProbeState, MISSES_FOR_VERDICT, UNRELIABLE_LABEL } from "../services/delivery-probe.js";
+
+const ORDERED = ["proxy", "proxy-control"];
+const ALL = [...ORDERED, UNRELIABLE_LABEL];
+
+/**
+ * @param {Record<string, number>} seen
+ * @param {object} [overrides]
+ */
+function state(seen, overrides = {}) {
+  return {
+    seq: 100,
+    seen,
+    labels: ALL,
+    echoes: 5,
+    echoAgeMs: 400,
+    ...overrides
+  };
+}
+
+test("every channel current reads as flowing", () => {
+  const { verdict } = readProbeState(state({ proxy: 100, "proxy-control": 99, "proxy-fast": 100 }));
+  assert.equal(verdict, "flowing");
+});
+
+test("a lag shorter than the verdict window is still flowing", () => {
+  const behind = 100 - (MISSES_FOR_VERDICT - 1);
+  const { verdict } = readProbeState(
+    state({ proxy: behind, "proxy-control": behind, "proxy-fast": 100 })
+  );
+  assert.equal(verdict, "flowing");
+});
+
+test("ordered channels behind while the unordered one keeps up names a stuck stream", () => {
+  const { verdict, detail } = readProbeState(
+    state({ proxy: 40, "proxy-control": 41, "proxy-fast": 100 })
+  );
+  assert.equal(verdict, "stream-stuck");
+  // The numbers that produced the verdict must be in the line beside it.
+  assert.match(detail, /proxy=40\(gap 60\)/);
+});
+
+test("every channel behind names the association", () => {
+  const { verdict } = readProbeState(
+    state({ proxy: 40, "proxy-control": 41, "proxy-fast": 42 })
+  );
+  assert.equal(verdict, "association-stopped");
+});
+
+test("without the unordered channel the verdict says it cannot compare", () => {
+  const { verdict } = readProbeState(
+    state({ proxy: 40, "proxy-control": 41 }, { labels: ORDERED })
+  );
+  assert.equal(verdict, "ordered-behind-no-comparison");
+});
+
+test("a stale echo means the reverse direction went too", () => {
+  const { verdict } = readProbeState(
+    state({ proxy: 40, "proxy-control": 41, "proxy-fast": 42 }, { echoAgeMs: 30_000 })
+  );
+  assert.equal(verdict, "reverse-direction-gone");
+});
+
+test("before the first echo nothing is claimed", () => {
+  const { verdict } = readProbeState(state({}, { echoes: 0, echoAgeMs: null }));
+  assert.equal(verdict, "no-echo-yet");
+});
+
+test("a channel that has never reported counts as behind, not as unknown", () => {
+  const { verdict, detail } = readProbeState(
+    state({ "proxy-fast": 100 })
+  );
+  assert.equal(verdict, "stream-stuck");
+  assert.match(detail, /proxy=\?\(gap \?\)/);
+});