@torrent-tv/proxy 2.62.0 → 2.64.0

package/services/tracks/AudioTrack.js

@@ -0,0 +1,40 @@
+/**
+ * @file Audio track — extends ContainerTrack with audio-specific flags.
+ *
+ * Matroska RFC 9559 §5.1.4.1:
+ *  - FlagOriginal 0x55AE (default 0) — track is original language.
+ *  - FlagCommentary 0x55AF — commentary track.
+ *  - FlagVisualImpaired 0x55AC — audio description for visually impaired.
+ *  - FlagTextDescriptions 0x55AD, FlagHearingImpaired etc. may also appear
+ *    but the three above drive the audio menu (research/container-spec-conformance).
+ * MP4 ISO/IEC 14496-12: tkhd alternate_group groups alternate audio tracks.
+ */
+
+import { ContainerTrack } from "./ContainerTrack.js";
+
+export class AudioTrack extends ContainerTrack {
+  /**
+   * @param {object} params - See ContainerTrack plus:
+   * @param {boolean} params.isOriginal - FlagOriginal
+   * @param {boolean} params.isCommentary - FlagCommentary
+   * @param {boolean} params.isVisualImpaired - FlagVisualImpaired / descriptive audio
+   * @param {number | null} params.channels
+   * @param {number | null} params.samplingFrequency
+   */
+  constructor(params) {
+    super({ ...params, type: "audio" });
+    this.isOriginal = params.isOriginal === true;
+    this.isCommentary = params.isCommentary === true;
+    this.isVisualImpaired = params.isVisualImpaired === true;
+    this.channels = Number.isFinite(params.channels) ? params.channels : null;
+    this.samplingFrequency = Number.isFinite(params.samplingFrequency) ? params.samplingFrequency : null;
+  }
+
+  /** Human label helper — commentary and descriptive audio must not look like main track. */
+  audioRoleLabel() {
+    if (this.isCommentary) return "commentary";
+    if (this.isVisualImpaired) return "descriptive";
+    if (this.isOriginal) return "original";
+    return "";
+  }
+}

package/services/tracks/ContainerTrack.js

@@ -0,0 +1,72 @@
+/**
+ * @file Base container track — what the container declares about one track.
+ *
+ * Spec sources:
+ *  - Matroska RFC 9559 §5.1.4.1 TrackEntry: TrackNumber(0xD7), TrackType(0x83),
+ *    FlagEnabled(0xB9, default 1), FlagDefault(0x88, default 1),
+ *    Language(0x22B59C, default "eng"), LanguageBCP47(0x22B59D, MUST ignore
+ *    Language when present), Name(0x536E), CodecID(0x86), CodecPrivate(0x63A2).
+ *  - MP4 ISO/IEC 14496-12 §8.3.2 tkhd (track_ID, flags track_enabled 0x000001,
+ *    alternate_group), §8.4.2 mdhd (language, timescale), §8.4.5 hdlr
+ *    (handler_type), §8.4.6 elng (extended language).
+ *
+ * Only fields that exist for EVERY track type live here. Type-specific flags
+ * (FlagForced, FlagHearingImpaired, FlagVisualImpaired, FlagOriginal,
+ * FlagCommentary) belong to subclasses — RFC 9559 states FlagForced "Applies
+ * only to subtitles", so VideoTrack must not carry it.
+ */
+
+export class ContainerTrack {
+  /**
+   * @param {object} params
+   * @param {number} params.trackNumber - Matroska TrackNumber or MP4 track_ID.
+   * @param {number} params.declaredIndex - Position among ALL subtitle/audio/video tracks as container orders them; equals ffmpeg 0:s:N / 0:a:N for that type. Stable across image/text filtering.
+   * @param {string} params.type - "video" | "audio" | "subtitle" | "other"
+   * @param {string} params.codecId - Matroska CodecID or MP4 sample entry type (e.g. "S_TEXT/UTF8", "avc1", "mp4a").
+   * @param {string} params.language - Three-letter code or packed mdhd code; empty when absent. For Matroska, when LanguageBCP47 is present this is the BCP47 value ignored per MUST — caller stores both, but `language` here is the resolved one.
+   * @param {string} params.languageBcp47 - RFC 5646 tag from LanguageBCP47 / elng, or "".
+   * @param {string} params.name - Track Name / title, or "".
+   * @param {boolean} params.isEnabled - FlagEnabled / tkhd track_enabled. Default true per both specs. Matroska zero-length element means default, not disabled.
+   * @param {boolean} params.isDefault - FlagDefault / tkhd? For MP4, derived from handler default? For Matroska, after applying default 1.
+   * @param {boolean} params.declaresDefault - Whether FlagDefault was explicitly written (Matroska) or inferred. Needed because ffmpeg banner cannot distinguish "every track marked" from "no track marked".
+   * @param {string} [params.codecPrivateB64] - Base64 of CodecPrivate (ASS header etc.), or "".
+   * @param {number} [params.alternateGroup] - MP4 alternate_group (0 = no group).
+   */
+  constructor({
+    trackNumber,
+    declaredIndex,
+    type,
+    codecId,
+    language,
+    languageBcp47,
+    name,
+    isEnabled,
+    isDefault,
+    declaresDefault,
+    codecPrivateB64 = "",
+    alternateGroup = 0
+  }) {
+    this.trackNumber = trackNumber;
+    this.declaredIndex = declaredIndex;
+    this.type = type;
+    this.codecId = codecId ?? "";
+    this.language = language ?? "";
+    this.languageBcp47 = languageBcp47 ?? "";
+    this.name = name ?? "";
+    this.isEnabled = isEnabled !== false;
+    this.isDefault = isDefault === true;
+    this.declaresDefault = declaresDefault === true;
+    this.codecPrivateB64 = codecPrivateB64 ?? "";
+    this.alternateGroup = Number.isFinite(alternateGroup) ? alternateGroup : 0;
+  }
+
+  /** Whether this track should be offered in UI menus. Base rule: disabled tracks hidden but still counted for declaredIndex. */
+  isOfferable() {
+    return this.isEnabled;
+  }
+
+  /** RFC 5646 tag wins over three-letter code when present. */
+  resolvedLanguage() {
+    return this.languageBcp47 || this.language;
+  }
+}

package/services/tracks/ExternalSubtitleFile.js

@@ -0,0 +1,27 @@
+/**
+ * @file External subtitle file — not part of the media container, but shares TextSubtitleTrack API.
+ *
+ * A standalone .srt/.ass/.ssa/.vtt file beside the video in the same torrent.
+ * Has no container flags; language comes from filename suffix or franc detection.
+ */
+
+export class ExternalSubtitleFile {
+  /**
+   * @param {object} params
+   * @param {string} params.fileName
+   * @param {number} params.fileIndex - Torrent file index.
+   * @param {string} params.extension - ".srt" etc. lowercased.
+   * @param {string} params.language - Hint from filename or "".
+   */
+  constructor({ fileName, fileIndex, extension, language = "" }) {
+    this.fileName = fileName;
+    this.fileIndex = fileIndex;
+    this.extension = extension;
+    this.language = language;
+    this.type = "external-subtitle";
+  }
+
+  isTextBased() {
+    return true;
+  }
+}

package/services/tracks/ImageSubtitleTrack.js

@@ -0,0 +1,19 @@
+/**
+ * @file Image subtitle track — PGS / VobSub / subp / clcp. Not convertible to WebVTT.
+ *
+ * Matroska: S_HDMV/PGS, S_VOBSUB, S_IMAGE/BMP etc.
+ * MP4: stpp is TTML (XML, excluded from Text), subp (VobSub), clcp (closed captions)
+ * Kept in the model only to preserve declaredIndex alignment with ffmpeg 0:s:N.
+ */
+
+import { SubtitleTrack } from "./SubtitleTrack.js";
+
+export class ImageSubtitleTrack extends SubtitleTrack {
+  constructor(params) {
+    super(params);
+  }
+
+  isTextBased() {
+    return false;
+  }
+}

package/services/tracks/SubtitleTrack.js

@@ -0,0 +1,38 @@
+/**
+ * @file Subtitle track — extends ContainerTrack with subtitle-only flags.
+ *
+ * Matroska RFC 9559:
+ *  - FlagForced 0x55AA default 0, applies ONLY to subtitles.
+ *  - FlagHearingImpaired 0x55AB, FlagVisualImpaired 0x55AC (SDH etc.)
+ *  - FlagTextDescriptions 0x55AD also subtitle-related.
+ *  - FlagEnabled 0xB9 still handled in base (disabled tracks counted but not offered).
+ * MP4 ISO 14496-12 + Apple tx3g extension:
+ *  - handler sbtl/subt/text/wvtt vs subp/clcp (image)
+ *  - tx3g displayFlags forced bits 0x40000000 / 0x80000000 (unconfirmed primary source, carried as raw flags)
+ */
+
+import { ContainerTrack } from "./ContainerTrack.js";
+
+export class SubtitleTrack extends ContainerTrack {
+  /**
+   * @param {object} params - See ContainerTrack plus:
+   * @param {boolean} params.isForced - FlagForced (matroska) or tx3g forced display flag.
+   * @param {boolean} params.isHearingImpaired - FlagHearingImpaired
+   * @param {boolean} params.isVisualImpaired - FlagVisualImpaired
+   * @param {number[]} params.clusterPositions - Matroska: file offsets of clusters whose CuePoints name this track (for push). Empty when indexless.
+   * @param {Array<{offset:number,size:number,startSeconds:number,endSeconds:number}>} params.samples - MP4: per-cue byte ranges from sample tables.
+   */
+  constructor(params) {
+    super({ ...params, type: "subtitle" });
+    this.isForced = params.isForced === true;
+    this.isHearingImpaired = params.isHearingImpaired === true;
+    this.isVisualImpaired = params.isVisualImpaired === true;
+    this.clusterPositions = Array.isArray(params.clusterPositions) ? params.clusterPositions : [];
+    this.samples = Array.isArray(params.samples) ? params.samples : [];
+  }
+
+  /** Whether this track can be converted to WebVTT in current pipeline. Overridden by subclasses. */
+  isTextBased() {
+    return false;
+  }
+}

package/services/tracks/TextSubtitleTrack.js

@@ -0,0 +1,29 @@
+/**
+ * @file Text subtitle track — convertible to WebVTT.
+ *
+ * Matroska: S_TEXT/UTF8, S_TEXT/ASS, S_TEXT/SSA
+ * MP4: tx3g, text, wvtt (stpp/TTML is NOT text for this pipeline — excluded)
+ * External files: .srt .ass .ssa .vtt — modelled as TextSubtitleTrack with no container backing.
+ */
+
+import { SubtitleTrack } from "./SubtitleTrack.js";
+
+const TEXT_CODECS_MATROSKA = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA"]);
+const TEXT_FORMATS_MP4 = new Set(["tx3g", "text", "wvtt"]);
+
+export class TextSubtitleTrack extends SubtitleTrack {
+  constructor(params) {
+    super(params);
+    this.textCodec = params.codecId ?? "";
+  }
+
+  isTextBased() {
+    return true;
+  }
+
+  static isTextCodec(codecId) {
+    return TEXT_CODECS_MATROSKA.has(codecId) || TEXT_FORMATS_MP4.has(codecId);
+  }
+}
+
+export { TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 };

package/services/tracks/VideoTrack.js

@@ -0,0 +1,33 @@
+/**
+ * @file Video track — extends ContainerTrack with video-specific container fields.
+ *
+ * Matroska RFC 9559: TrackEntry/Video (PixelWidth/Height, DisplayWidth/Height)
+ * MP4 ISO/IEC 14496-12: tkhd width/height, mdhd timescale, stsd sample entry
+ *   (avc1/hev1/etc.), stss/stts for keyframes, colr for HDR.
+ * No FlagForced / FlagHearingImpaired — those are subtitle-only per spec.
+ */
+
+import { ContainerTrack } from "./ContainerTrack.js";
+
+export class VideoTrack extends ContainerTrack {
+  /**
+   * @param {object} params - See ContainerTrack plus:
+   * @param {number | null} params.width - Coded width (PixelWidth / tkhd width).
+   * @param {number | null} params.height - Coded height.
+   * @param {number | null} params.displayWidth
+   * @param {number | null} params.displayHeight
+   * @param {number | null} params.fps - From container when available (otherwise from ffmpeg banner elsewhere).
+   * @param {boolean} params.isHdr - From container colr / ffmpeg detection later.
+   * @param {number | null} params.bitDepth
+   */
+  constructor(params) {
+    super({ ...params, type: "video" });
+    this.width = Number.isFinite(params.width) ? params.width : null;
+    this.height = Number.isFinite(params.height) ? params.height : null;
+    this.displayWidth = Number.isFinite(params.displayWidth) ? params.displayWidth : null;
+    this.displayHeight = Number.isFinite(params.displayHeight) ? params.displayHeight : null;
+    this.fps = Number.isFinite(params.fps) ? params.fps : null;
+    this.isHdr = params.isHdr === true;
+    this.bitDepth = Number.isFinite(params.bitDepth) ? params.bitDepth : null;
+  }
+}

package/services/tracks/index.js

@@ -0,0 +1,7 @@
+export { ContainerTrack } from "./ContainerTrack.js";
+export { VideoTrack } from "./VideoTrack.js";
+export { AudioTrack } from "./AudioTrack.js";
+export { SubtitleTrack } from "./SubtitleTrack.js";
+export { TextSubtitleTrack, TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 } from "./TextSubtitleTrack.js";
+export { ImageSubtitleTrack } from "./ImageSubtitleTrack.js";
+export { ExternalSubtitleFile } from "./ExternalSubtitleFile.js";

package/test/delivery-probe.test.js

@@ -1,158 +1,213 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { allowedGap, readProbeState, PROBE_INTERVAL_MS, 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 = {}) {
-  const allowed = {};
-  for (const label of overrides.labels ?? ALL) {
-    allowed[label] = 3;
-  }
-  return {
-    seq: 100,
-    seen,
-    labels: ALL,
-    echoes: 5,
-    echoAgeMs: 400,
-    allowed,
-    ...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 - 3;
-  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 of 3\)/);
-});
-
-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 \? of 3\)/);
-});
-
-test("the allowance is the queue's own drain time, not a chosen number", () => {
-  // 8 MB queued at 8 MB/s is one second of draining; probes go twice a second,
-  // so two of them may legitimately be outstanding, plus the round trip.
-  assert.equal(
-    allowedGap({ queuedBytes: 8 * 1024 * 1024, bytesPerSecond: 8 * 1024 * 1024, rttMs: 0 }),
-    Math.ceil(1000 / PROBE_INTERVAL_MS)
-  );
-  // An empty queue still allows the one probe that is always in flight.
-  assert.equal(allowedGap({ queuedBytes: 0, bytesPerSecond: 8 * 1024 * 1024, rttMs: 0 }), 1);
-  // The round trip counts: the echo has to come back too.
-  assert.ok(
-    allowedGap({ queuedBytes: 0, bytesPerSecond: 1024, rttMs: 2000 }) >
-      allowedGap({ queuedBytes: 0, bytesPerSecond: 1024, rttMs: 0 })
-  );
-});
-
-test("with no rate measured nothing is claimed", () => {
-  assert.equal(allowedGap({ queuedBytes: 1024, bytesPerSecond: 0, rttMs: 10 }), null);
-  const { verdict } = readProbeState(
-    state({ proxy: 40, "proxy-control": 41, "proxy-fast": 42 }, { allowed: {} })
-  );
-  assert.equal(verdict, "no-rate-yet");
-});
-
-test("a burst big enough to explain the lag is not called a stopped association", () => {
-  // The 2026-08-26 false positive: all three channels at gap 7 while 150 Mbps
-  // crossed the association. 64 MB queued at 18 MB/s is three and a half
-  // seconds of draining, which is seven probe intervals.
-  const allowance = allowedGap({
-    queuedBytes: 64 * 1024 * 1024,
-    bytesPerSecond: 18 * 1024 * 1024,
-    rttMs: 16
-  });
-  assert.ok(allowance >= 7);
-  const allowed = Object.fromEntries(ALL.map((label) => [label, allowance]));
-  const { verdict } = readProbeState(
-    state({ proxy: 93, "proxy-control": 93, "proxy-fast": 93 }, { allowed })
-  );
-  assert.equal(verdict, "flowing");
-});
-
-test("the peer's own answering cadence counts toward the allowance", () => {
-  // Field case 2026-08-27: queues empty, 3.4 MB/s crossing, tab hidden so the
-  // browser echoed about once a second. Without the peer's cadence the
-  // allowance is one probe and every other line read `association-stopped`.
-  const withoutCadence = allowedGap({
-    queuedBytes: 0,
-    bytesPerSecond: 3.4 * 1024 * 1024,
-    rttMs: 9
-  });
-  assert.equal(withoutCadence, 1);
-  const withCadence = allowedGap({
-    queuedBytes: 0,
-    bytesPerSecond: 3.4 * 1024 * 1024,
-    rttMs: 9,
-    echoIntervalMs: 1000
-  });
-  assert.ok(withCadence >= 3, `a second of cadence must allow more than ${withCadence}`);
-  const allowed = Object.fromEntries(ALL.map((label) => [label, withCadence]));
-  const { verdict } = readProbeState(
-    state({ proxy: 98, "proxy-control": 98, "proxy-fast": 98 }, { allowed, echoAgeMs: 977 })
-  );
-  assert.equal(verdict, "flowing");
-});
-
-test("a stale echo is judged against the peer's cadence, not a fixed half second", () => {
-  // The same numbers with the cadence unknown must still be able to say the
-  // reverse direction is gone — the bound rises with the cadence, it does not
-  // disappear.
-  const { verdict } = readProbeState(
-    state({ proxy: 99, "proxy-control": 99, "proxy-fast": 99 }, { echoAgeMs: 60_000, echoStaleMs: 2000 })
-  );
-  assert.equal(verdict, "reverse-direction-gone");
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { allowedGap, readProbeState, PROBE_INTERVAL_MS, 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 = {}) {
+  const allowed = {};
+  for (const label of overrides.labels ?? ALL) {
+    allowed[label] = 3;
+  }
+  return {
+    seq: 100,
+    seen,
+    labels: ALL,
+    echoes: 5,
+    echoAgeMs: 400,
+    allowed,
+    ...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 - 3;
+  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 of 3\)/);
+});
+
+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 \? of 3\)/);
+});
+
+test("the allowance is the queue's own drain time, not a chosen number", () => {
+  // 8 MB queued at 8 MB/s is one second of draining; probes go twice a second,
+  // so two of them may legitimately be outstanding, plus the round trip.
+  assert.equal(
+    allowedGap({ queuedBytes: 8 * 1024 * 1024, bytesPerSecond: 8 * 1024 * 1024, rttMs: 0 }),
+    Math.ceil(1000 / PROBE_INTERVAL_MS)
+  );
+  // An empty queue still allows the one probe that is always in flight.
+  assert.equal(allowedGap({ queuedBytes: 0, bytesPerSecond: 8 * 1024 * 1024, rttMs: 0 }), 1);
+  // The round trip counts: the echo has to come back too.
+  assert.ok(
+    allowedGap({ queuedBytes: 0, bytesPerSecond: 1024, rttMs: 2000 }) >
+      allowedGap({ queuedBytes: 0, bytesPerSecond: 1024, rttMs: 0 })
+  );
+});
+
+test("with no rate measured nothing is claimed", () => {
+  assert.equal(allowedGap({ queuedBytes: 1024, bytesPerSecond: 0, rttMs: 10 }), null);
+  const { verdict } = readProbeState(
+    state({ proxy: 40, "proxy-control": 41, "proxy-fast": 42 }, { allowed: {} })
+  );
+  assert.equal(verdict, "no-rate-yet");
+});
+
+test("a burst big enough to explain the lag is not called a stopped association", () => {
+  // The 2026-08-26 false positive: all three channels at gap 7 while 150 Mbps
+  // crossed the association. 64 MB queued at 18 MB/s is three and a half
+  // seconds of draining, which is seven probe intervals.
+  const allowance = allowedGap({
+    queuedBytes: 64 * 1024 * 1024,
+    bytesPerSecond: 18 * 1024 * 1024,
+    rttMs: 16
+  });
+  assert.ok(allowance >= 7);
+  const allowed = Object.fromEntries(ALL.map((label) => [label, allowance]));
+  const { verdict } = readProbeState(
+    state({ proxy: 93, "proxy-control": 93, "proxy-fast": 93 }, { allowed })
+  );
+  assert.equal(verdict, "flowing");
+});
+
+test("the peer's own answering cadence counts toward the allowance", () => {
+  // Field case 2026-08-27: queues empty, 3.4 MB/s crossing, tab hidden so the
+  // browser echoed about once a second. Without the peer's cadence the
+  // allowance is one probe and every other line read `association-stopped`.
+  const withoutCadence = allowedGap({
+    queuedBytes: 0,
+    bytesPerSecond: 3.4 * 1024 * 1024,
+    rttMs: 9
+  });
+  assert.equal(withoutCadence, 1);
+  const withCadence = allowedGap({
+    queuedBytes: 0,
+    bytesPerSecond: 3.4 * 1024 * 1024,
+    rttMs: 9,
+    echoIntervalMs: 1000
+  });
+  assert.ok(withCadence >= 3, `a second of cadence must allow more than ${withCadence}`);
+  const allowed = Object.fromEntries(ALL.map((label) => [label, withCadence]));
+  const { verdict } = readProbeState(
+    state({ proxy: 98, "proxy-control": 98, "proxy-fast": 98 }, { allowed, echoAgeMs: 977 })
+  );
+  assert.equal(verdict, "flowing");
+});
+
+test("a stale echo is judged against the peer's cadence, not a fixed half second", () => {
+  // The same numbers with the cadence unknown must still be able to say the
+  // reverse direction is gone — the bound rises with the cadence, it does not
+  // disappear.
+  const { verdict } = readProbeState(
+    state({ proxy: 99, "proxy-control": 99, "proxy-fast": 99 }, { echoAgeMs: 60_000, echoStaleMs: 2000 })
+  );
+  assert.equal(verdict, "reverse-direction-gone");
+});
+
+test("bytes still arriving outrank the probe gaps — the cushion fill is not a wedge", () => {
+  // The field shape of 2026-08-28: every queue at 0 B, so the allowance is
+  // small, the probes are far behind because the browser is busy pulling two
+  // minutes of film, and the association is perfectly healthy. Before the peer's
+  // own byte counter was consulted this read as `association-stopped`, four
+  // times in the first two minutes of a session nobody was troubled by.
+  const state = {
+    seq: 88,
+    seen: { proxy: 78, "proxy-control": 78, "proxy-fast": 78 },
+    labels: ["proxy", "proxy-control", "proxy-fast"],
+    echoes: 40,
+    echoAgeMs: 1305,
+    allowed: { proxy: 9, "proxy-control": 9, "proxy-fast": 9 },
+    echoStaleMs: 6000,
+    peerBytesAdvancing: true
+  };
+  const reading = readProbeState(state);
+  assert.equal(reading.verdict, "flowing");
+  assert.match(reading.detail, /peerBytes=advancing/);
+});
+
+test("the same gaps with the peer's counter STILL are the wedge", () => {
+  // One field changes, and it is the one that says whether anything is
+  // arriving. This is the shape of a real freeze: probes behind, and the far
+  // end receiving nothing.
+  const reading = readProbeState({
+    seq: 88,
+    seen: { proxy: 78, "proxy-control": 78, "proxy-fast": 78 },
+    labels: ["proxy", "proxy-control", "proxy-fast"],
+    echoes: 40,
+    echoAgeMs: 1305,
+    allowed: { proxy: 9, "proxy-control": 9, "proxy-fast": 9 },
+    echoStaleMs: 6000,
+    peerBytesAdvancing: false
+  });
+  assert.equal(reading.verdict, "association-stopped");
+  assert.match(reading.detail, /peerBytes=still/);
+});
+
+test("a browser that does not report its bytes is judged as before", () => {
+  // The term says nothing rather than guessing, and the rule falls back.
+  const reading = readProbeState({
+    seq: 88,
+    seen: { proxy: 78, "proxy-control": 78, "proxy-fast": 78 },
+    labels: ["proxy", "proxy-control", "proxy-fast"],
+    echoes: 40,
+    echoAgeMs: 1305,
+    allowed: { proxy: 9, "proxy-control": 9, "proxy-fast": 9 },
+    echoStaleMs: 6000,
+    peerBytesAdvancing: null
+  });
+  assert.equal(reading.verdict, "association-stopped");
+  assert.doesNotMatch(reading.detail, /peerBytes=/);
+});