@torrent-tv/proxy 2.89.17 → 2.89.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (300) hide show
  1. package/README.md +14 -3
  2. package/package.json +10 -2
  3. package/server.js +0 -11
  4. package/utils/client-log-file.js +147 -42
  5. package/.claude/commands/opsx/apply.md +0 -155
  6. package/.claude/commands/opsx/archive.md +0 -160
  7. package/.claude/commands/opsx/explore.md +0 -174
  8. package/.claude/commands/opsx/propose.md +0 -109
  9. package/.claude/commands/opsx/sync.md +0 -143
  10. package/.claude/skills/openspec-apply-change/SKILL.md +0 -159
  11. package/.claude/skills/openspec-archive-change/SKILL.md +0 -117
  12. package/.claude/skills/openspec-explore/SKILL.md +0 -289
  13. package/.claude/skills/openspec-propose/SKILL.md +0 -113
  14. package/.claude/skills/openspec-sync-specs/SKILL.md +0 -147
  15. package/.dockerignore +0 -5
  16. package/AGENTS.md +0 -363
  17. package/CHANGELOG.md +0 -2377
  18. package/Dockerfile +0 -30
  19. package/biome.json +0 -412
  20. package/corpus.tmp.json +0 -1
  21. package/docs/browser-proxy-contract.md +0 -155
  22. package/docs/container-architecture.md +0 -273
  23. package/docs/download-architecture.md +0 -261
  24. package/docs/encode-architecture.md +0 -765
  25. package/docs/encode-run-state.md +0 -96
  26. package/docs/logs.md +0 -151
  27. package/docs/playback-start-forecast.md +0 -113
  28. package/docs/socks5-egress-research.md +0 -114
  29. package/docs/storage-architecture.md +0 -273
  30. package/knip.json +0 -14
  31. package/main2.cpuprofile +0 -1
  32. package/openspec/changes/adaptive-bitrate/.openspec.yaml +0 -0
  33. package/openspec/changes/adaptive-bitrate/design.md +0 -92
  34. package/openspec/changes/adaptive-bitrate/proposal.md +0 -56
  35. package/openspec/changes/adaptive-bitrate/specs/adaptive-bitrate/spec.md +0 -51
  36. package/openspec/changes/adaptive-bitrate/tasks.md +0 -40
  37. package/openspec/changes/binary-distribution/.openspec.yaml +0 -2
  38. package/openspec/changes/binary-distribution/proposal.md +0 -53
  39. package/openspec/changes/chunked-request-bodies/design.md +0 -81
  40. package/openspec/changes/chunked-request-bodies/proposal.md +0 -53
  41. package/openspec/changes/chunked-request-bodies/specs/chunked-request-bodies/spec.md +0 -30
  42. package/openspec/changes/chunked-request-bodies/tasks.md +0 -40
  43. package/openspec/changes/cold-start/design.md +0 -98
  44. package/openspec/changes/cold-start/proposal.md +0 -62
  45. package/openspec/changes/cold-start/specs/cold-start/spec.md +0 -47
  46. package/openspec/changes/cold-start/tasks.md +0 -48
  47. package/openspec/changes/disk-cap/.openspec.yaml +0 -2
  48. package/openspec/changes/disk-cap/proposal.md +0 -37
  49. package/openspec/changes/disk-cap/specs/disk-cap/spec.md +0 -25
  50. package/openspec/changes/disk-cap/tasks.md +0 -19
  51. package/openspec/changes/proxy-observability/.openspec.yaml +0 -2
  52. package/openspec/changes/proxy-observability/design.md +0 -38
  53. package/openspec/changes/proxy-observability/proposal.md +0 -49
  54. package/openspec/changes/proxy-observability/specs/observability/spec.md +0 -33
  55. package/openspec/changes/proxy-observability/tasks.md +0 -21
  56. package/openspec/changes/seek-debounce/.openspec.yaml +0 -0
  57. package/openspec/changes/seek-debounce/design.md +0 -118
  58. package/openspec/changes/seek-debounce/proposal.md +0 -59
  59. package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md +0 -41
  60. package/openspec/changes/seek-debounce/tasks.md +0 -33
  61. package/openspec/changes/subtitle-language/.openspec.yaml +0 -2
  62. package/openspec/changes/subtitle-language/proposal.md +0 -50
  63. package/openspec/changes/subtitle-language/specs/subtitle-language/spec.md +0 -34
  64. package/openspec/changes/subtitle-language/tasks.md +0 -26
  65. package/openspec/changes/track-selection/.openspec.yaml +0 -2
  66. package/openspec/changes/track-selection/design.md +0 -47
  67. package/openspec/changes/track-selection/proposal.md +0 -45
  68. package/openspec/changes/track-selection/specs/track-selection/spec.md +0 -41
  69. package/openspec/changes/track-selection/tasks.md +0 -20
  70. package/openspec/changes/transcode-quality/.openspec.yaml +0 -2
  71. package/openspec/changes/transcode-quality/proposal.md +0 -51
  72. package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md +0 -139
  73. package/openspec/changes/transcode-quality/tasks.md +0 -63
  74. package/openspec/config.yaml +0 -38
  75. package/public/.well-known/appspecific/com.chrome.devtools.json +0 -1
  76. package/research/delivery-wedge-stand-ladder-2026-09-13.md +0 -329
  77. package/research/double-spawn-2026-09-10.md +0 -171
  78. package/research/handover-2026-09-13.md +0 -209
  79. package/research/handover-reader-claims-removal-2026-09-12.md +0 -166
  80. package/research/piece-withdrawn-but-still-claimed-2026-09-12.md +0 -175
  81. package/research/preset-benchmark-size-scaling-2026-08-22.md +0 -55
  82. package/research/priority-map-is-the-truth-2026-09-12.md +0 -225
  83. package/research/valgrind-replica-2026-08-27/logs.tar.gz +0 -0
  84. package/scripts/build-audio-samples.mjs +0 -31
  85. package/scripts/render-run-graph.js +0 -173
  86. package/test/asset-paths.test.js +0 -28
  87. package/test/audio-buffer-continuity.test.js +0 -77
  88. package/test/audio-calibration.test.js +0 -23
  89. package/test/audio-inventory.test.js +0 -212
  90. package/test/audio-track-bitrate.test.js +0 -40
  91. package/test/audio-warm-recorded.test.js +0 -63
  92. package/test/auto-quality-step.test.js +0 -762
  93. package/test/available-share.test.js +0 -76
  94. package/test/background-fill.test.js +0 -190
  95. package/test/client-log-file.test.js +0 -126
  96. package/test/client-logs-route.test.js +0 -34
  97. package/test/coalesce.test.js +0 -39
  98. package/test/completed-files.test.js +0 -115
  99. package/test/concurrent-cost.test.js +0 -148
  100. package/test/container-media-info.test.js +0 -228
  101. package/test/contention.test.js +0 -76
  102. package/test/core-dumps.test.js +0 -57
  103. package/test/coverage-follows-the-disk.test.js +0 -233
  104. package/test/coverage-map.test.js +0 -195
  105. package/test/cue-push-carries-what-the-walk-found.test.js +0 -58
  106. package/test/cut-times-timeline.test.js +0 -65
  107. package/test/cuts-follow-published-grid.test.js +0 -109
  108. package/test/data-channel-frame.test.js +0 -63
  109. package/test/data-channel-viewer-lifecycle.test.js +0 -193
  110. package/test/dead-torrent-handle.test.js +0 -52
  111. package/test/declared-rates.test.js +0 -116
  112. package/test/declared-tracks.test.js +0 -43
  113. package/test/decode-cost-fit.test.js +0 -202
  114. package/test/decode-cost.test.js +0 -475
  115. package/test/delivery-probe-field.test.js +0 -173
  116. package/test/delivery-probe.test.js +0 -382
  117. package/test/demand-register.test.js +0 -206
  118. package/test/dht-bootstrap.test.js +0 -72
  119. package/test/drain-threat.test.js +0 -65
  120. package/test/duplicate-add.test.js +0 -48
  121. package/test/encode-admission.test.js +0 -170
  122. package/test/encode-cost.test.js +0 -275
  123. package/test/encode-exit.test.js +0 -111
  124. package/test/encode-orchestrator.test.js +0 -426
  125. package/test/encode-plan-viewers.test.js +0 -725
  126. package/test/encode-plan.test.js +0 -545
  127. package/test/encode-run-state.test.js +0 -314
  128. package/test/encode-run.test.js +0 -248
  129. package/test/encode-slope.test.js +0 -46
  130. package/test/encoded-output.test.js +0 -39
  131. package/test/encoder-kinds.test.js +0 -122
  132. package/test/encoder-readings.test.js +0 -68
  133. package/test/episode-naming.test.js +0 -131
  134. package/test/every-claimant-is-told-its-share.test.js +0 -152
  135. package/test/failed-encoder-still-serves-what-exists.test.js +0 -354
  136. package/test/failed-start-breaker.test.js +0 -202
  137. package/test/fastest-wires.test.js +0 -143
  138. package/test/ffmpeg-stream-counts.test.js +0 -101
  139. package/test/file-edges.test.js +0 -191
  140. package/test/files-in-use.test.js +0 -34
  141. package/test/fixtures/audio-frame-boundary.json +0 -1
  142. package/test/fixtures/refused-audio-20261002.json +0 -10
  143. package/test/fmp4-presentation-clock.test.js +0 -148
  144. package/test/fmp4-self-contained.test.js +0 -80
  145. package/test/fmp4-timestamps.test.js +0 -140
  146. package/test/fmp4-track-completeness.test.js +0 -41
  147. package/test/format-keyed-outputs.test.js +0 -78
  148. package/test/health-metrics.test.js +0 -36
  149. package/test/held-read-ownership.test.js +0 -77
  150. package/test/held-request-width.test.js +0 -157
  151. package/test/helpers/encode-run.js +0 -248
  152. package/test/helpers/held-file.js +0 -77
  153. package/test/helpers/manager.js +0 -62
  154. package/test/helpers/matroska-file.js +0 -296
  155. package/test/helpers/output-spec.js +0 -63
  156. package/test/host-load.test.js +0 -68
  157. package/test/index-accuracy-is-about-the-file.test.js +0 -128
  158. package/test/init-compat.test.js +0 -219
  159. package/test/input-lost-quiets-the-plan.test.js +0 -261
  160. package/test/input-unavailable.test.js +0 -48
  161. package/test/installation-id.test.js +0 -39
  162. package/test/keeping-period.test.js +0 -83
  163. package/test/keyframe-index-accuracy.test.js +0 -188
  164. package/test/keyframe-table-budget.test.js +0 -123
  165. package/test/keyframes-belong-to-the-file.test.js +0 -249
  166. package/test/learned-median.test.js +0 -37
  167. package/test/letting-go-asks-who-is-watching.test.js +0 -191
  168. package/test/limit-row-by-area.test.js +0 -60
  169. package/test/link-budget.test.js +0 -111
  170. package/test/link-probe.test.js +0 -56
  171. package/test/local-encoding-data.test.js +0 -273
  172. package/test/logger-repeats.test.js +0 -134
  173. package/test/look-ahead-coverage.test.js +0 -56
  174. package/test/manager-surface.test.js +0 -291
  175. package/test/matroska-blocks.test.js +0 -0
  176. package/test/matroska-cluster-discovery.test.js +0 -323
  177. package/test/matroska-cues-track.test.js +0 -192
  178. package/test/media-time.test.js +0 -62
  179. package/test/memory-budget.test.js +0 -390
  180. package/test/move-cost.test.js +0 -216
  181. package/test/mp4-composition-times.test.js +0 -0
  182. package/test/mp4-subtitles.test.js +0 -173
  183. package/test/one-authority.test.js +0 -285
  184. package/test/one-budget.test.js +0 -149
  185. package/test/one-output-one-session.test.js +0 -273
  186. package/test/one-resource-divided.test.js +0 -185
  187. package/test/one-serving-output-per-height.test.js +0 -458
  188. package/test/orchestrator-wired.test.js +0 -207
  189. package/test/output-catalog.test.js +0 -39
  190. package/test/output-shape.test.js +0 -21
  191. package/test/output-spec.test.js +0 -251
  192. package/test/output-speed.test.js +0 -92
  193. package/test/outputs-being-prepared.test.js +0 -40
  194. package/test/packet-witness-ring.test.js +0 -236
  195. package/test/packet-witness.test.js +0 -148
  196. package/test/piece-completeness.test.js +0 -78
  197. package/test/piece-disk-store.test.js +0 -401
  198. package/test/piece-from-whole-file.test.js +0 -129
  199. package/test/piece-lru.test.js +0 -319
  200. package/test/piece-reader.test.js +0 -162
  201. package/test/piece-selection-offset.test.js +0 -85
  202. package/test/piece-store-eviction.test.js +0 -595
  203. package/test/piece-store-never-refuses.test.js +0 -153
  204. package/test/piece-store-reservations.test.js +0 -403
  205. package/test/piece-store-slow-disk.test.js +0 -159
  206. package/test/piece-tail.test.js +0 -97
  207. package/test/plan-host-timings.test.js +0 -68
  208. package/test/plan-is-steady.test.js +0 -225
  209. package/test/playback-readiness.test.js +0 -518
  210. package/test/playback-start-regressions.test.js +0 -101
  211. package/test/priority-map-download.test.js +0 -174
  212. package/test/priority-map-emptied.test.js +0 -204
  213. package/test/priority-map-per-output.test.js +0 -215
  214. package/test/priority-map.test.js +0 -163
  215. package/test/probe-wedge-certainty.test.js +0 -60
  216. package/test/produced-copy-choice.test.js +0 -213
  217. package/test/published-timeline.test.js +0 -83
  218. package/test/quality-offer.test.js +0 -160
  219. package/test/quality-variants.test.js +0 -1274
  220. package/test/rate-control-in-the-output.test.js +0 -181
  221. package/test/read-survives-withdrawal.test.js +0 -164
  222. package/test/read-window.test.js +0 -365
  223. package/test/reads-not-yet-arrived.test.js +0 -218
  224. package/test/resume-warm.test.js +0 -39
  225. package/test/run-graph-drift.test.js +0 -37
  226. package/test/run-inputs.test.js +0 -80
  227. package/test/run-intervals.test.js +0 -100
  228. package/test/run-position-follows-published-grid.test.js +0 -89
  229. package/test/run-progress.test.js +0 -64
  230. package/test/same-height-switch.test.js +0 -663
  231. package/test/seek-frees-the-viewers-requests.test.js +0 -217
  232. package/test/seek-landing.test.js +0 -109
  233. package/test/seek-target-not-superseded.test.js +0 -195
  234. package/test/segment-closed-on-both-branches.test.js +0 -114
  235. package/test/segment-cut-times.test.js +0 -63
  236. package/test/segment-demand.test.js +0 -80
  237. package/test/segment-hold-supersede.test.js +0 -91
  238. package/test/segment-judged-by-its-own-header.test.js +0 -222
  239. package/test/segment-serve-wiring.test.js +0 -481
  240. package/test/segment-store-eviction.test.js +0 -247
  241. package/test/segment-store.test.js +0 -352
  242. package/test/segment-true-start.test.js +0 -86
  243. package/test/segments-are-shared.test.js +0 -176
  244. package/test/send-chunk-bytes.test.js +0 -86
  245. package/test/serving-existing-output.test.js +0 -111
  246. package/test/serving-output.test.js +0 -102
  247. package/test/shared-piece-store.test.js +0 -310
  248. package/test/sidecar-naming.test.js +0 -142
  249. package/test/soundtrack-rate-bound.test.js +0 -289
  250. package/test/source-file.test.js +0 -133
  251. package/test/source-files-route.test.js +0 -113
  252. package/test/source-registry.test.js +0 -18
  253. package/test/split-a-stretch.test.js +0 -139
  254. package/test/stale-request-after-seek.test.js +0 -158
  255. package/test/startup-readings.test.js +0 -124
  256. package/test/stream-route.test.js +0 -237
  257. package/test/subtitle-cue-framing.test.js +0 -200
  258. package/test/subtitle-cue-source.test.js +0 -102
  259. package/test/subtitle-cue-walk.test.js +0 -385
  260. package/test/subtitle-cursor.test.js +0 -63
  261. package/test/subtitle-defaults.test.js +0 -118
  262. package/test/subtitle-language.test.js +0 -252
  263. package/test/subtitle-metadata.test.js +0 -15
  264. package/test/subtitle-plan-waits.test.js +0 -125
  265. package/test/subtitle-track-numbering.test.js +0 -391
  266. package/test/supply-margin.test.js +0 -190
  267. package/test/swarm-follows-readers.test.js +0 -174
  268. package/test/swarm-reach.test.js +0 -130
  269. package/test/swarm-selection.test.js +0 -220
  270. package/test/tail-duplication.test.js +0 -167
  271. package/test/the-channel-has-both-ends.test.js +0 -91
  272. package/test/the-torrent-thread-serves-bytes.test.js +0 -107
  273. package/test/thread-pool.test.js +0 -53
  274. package/test/timeline.test.js +0 -84
  275. package/test/torrent-contents.test.js +0 -235
  276. package/test/torrent-cost.test.js +0 -71
  277. package/test/torrent-files.test.js +0 -221
  278. package/test/torrent-naming.test.js +0 -255
  279. package/test/tracks-begin-together.test.js +0 -209
  280. package/test/tunnel-renewal.test.js +0 -167
  281. package/test/two-viewers-one-picture.test.js +0 -508
  282. package/test/upload-hurry.test.js +0 -186
  283. package/test/usrsctp-state.test.js +0 -131
  284. package/test/video-facts.test.js +0 -102
  285. package/test/viewer-assignments.test.js +0 -143
  286. package/test/viewer-outputs.test.js +0 -285
  287. package/test/viewer-presence.test.js +0 -116
  288. package/test/viewer-requests-admission.test.js +0 -92
  289. package/test/viewer-starts-on-map.test.js +0 -27
  290. package/test/viewer-states.test.js +0 -192
  291. package/test/viewer-subtitle-subscription.test.js +0 -96
  292. package/test/viewer.test.js +0 -139
  293. package/test/viewing-generations.test.js +0 -390
  294. package/test/visible-rung.test.js +0 -37
  295. package/test/wait-ledger.test.js +0 -100
  296. package/test/webrtc-shim.test.js +0 -149
  297. package/test/wedge-certainty.test.js +0 -131
  298. package/test/whole-file-held-read.test.js +0 -30
  299. package/test/withdraw-piece-claim.test.js +0 -212
  300. package/test/worker-channel.test.js +0 -158
@@ -1,188 +0,0 @@
1
- /**
2
- * @file How well a container's keyframe index describes its own file.
3
- *
4
- * The cut times of a copied video ARE its index — ffmpeg can only cut where a
5
- * keyframe already is — and an index can be wrong: measured 2026-08-06, one
6
- * claimed a keyframe at 157.99 s where the real ones were 153.82 and 164.247.
7
- * Whether a re-encoded rung can be cut on that same grid and spliced into the
8
- * copy depends entirely on how often that happens, so it is counted.
9
- *
10
- * No scan is involved and no undownloaded byte is touched: each produced piece
11
- * states where it truly begins, and it is already read whole in order to be
12
- * stamped. Only boundaries that were actually produced are counted — the parts
13
- * somebody watched.
14
- *
15
- * Counted ON THE FILE'S OWN TABLE, because that is whose fact it is: the same
16
- * finding for every quality step of the film and for every later session of it.
17
- */
18
-
19
- import test from "node:test";
20
- import assert from "node:assert/strict";
21
- import { SourceFile } from "../services/media/SourceFile.js";
22
- import { Timeline } from "../services/encode/output/Timeline.js";
23
- import { KeyframeTable } from "../services/media/container/KeyframeTable.js";
24
- import { outputSpec } from "./helpers/output-spec.js";
25
-
26
- const TOLERANCE = 0.25;
27
-
28
- /**
29
- * A table naming keyframes every four seconds, which is what the grid of a
30
- * copied picture is built from.
31
- *
32
- * @returns {KeyframeTable}
33
- */
34
- function fourSecondKeyframes() {
35
- return new KeyframeTable().learn({
36
- times: [0, 4, 8, 12, 16, 20],
37
- format: "matroska"
38
- });
39
- }
40
-
41
- test("an index that describes its file exactly is reported as such", () => {
42
- const table = fourSecondKeyframes();
43
-
44
- for (let index = 0; index < 4; index += 1) {
45
- table.witness({ index, trueStart: index * 4, deviationSec: 0, toleranceSec: TOLERANCE });
46
- }
47
-
48
- assert.equal(table.evidence.checked, 4);
49
- assert.equal(table.evidence.disagreed, 0, "nothing disagreed — which is a finding, not silence");
50
- assert.equal(table.evidence.maxDeviationSec, 0);
51
- });
52
-
53
- test("a boundary the index placed wrongly is counted, with how far out it was", () => {
54
- const table = fourSecondKeyframes();
55
-
56
- table.witness({ index: 0, trueStart: 0, deviationSec: 0, toleranceSec: TOLERANCE });
57
- // The measured shape: the playlist said 157.99 s, the file cut at 153.82 s.
58
- table.witness({ index: 2, trueStart: 3.83, deviationSec: 4.17, toleranceSec: TOLERANCE });
59
- table.witness({ index: 3, trueStart: 12.01, deviationSec: 0.01, toleranceSec: TOLERANCE });
60
-
61
- assert.equal(table.evidence.checked, 3);
62
- assert.equal(table.evidence.disagreed, 1);
63
- assert.equal(table.evidence.firstDisagreementIndex, 2);
64
- assert.equal(
65
- table.evidence.maxDeviationSec,
66
- 4.17,
67
- "the size of the error is what decides whether a rung can be cut on this grid"
68
- );
69
- });
70
-
71
- test("a deviation within tolerance is not a disagreement, but still shows in the worst case", () => {
72
- const table = fourSecondKeyframes();
73
-
74
- table.witness({ index: 0, trueStart: 0.2, deviationSec: 0.2, toleranceSec: TOLERANCE });
75
-
76
- assert.equal(
77
- table.evidence.disagreed,
78
- 0,
79
- "rounding in a container's timestamps is not the index being wrong"
80
- );
81
- assert.equal(
82
- table.evidence.maxDeviationSec,
83
- 0.2,
84
- "and it is still worth knowing how close to the line it ran"
85
- );
86
- });
87
-
88
- test("a piece that began at ANOTHER time the table names is told apart from one that began nowhere", () => {
89
- // The discriminator, and it decides which of two opposite faults this is. A
90
- // piece that began at another keyframe of the same list was not mis-described
91
- // by the table: the grid was built over a gap in it. One that began where the
92
- // table names nothing is the table describing times the file does not have.
93
- // The table answers it itself, because it is the only thing that holds the
94
- // list — asked of the caller, it was one more fact travelling by hand.
95
- const table = fourSecondKeyframes();
96
-
97
- table.witness({ index: 1, trueStart: 8, deviationSec: 4, toleranceSec: TOLERANCE });
98
- table.witness({ index: 2, trueStart: 9.7, deviationSec: 1.7, toleranceSec: TOLERANCE });
99
-
100
- assert.equal(table.evidence.disagreed, 2);
101
- assert.equal(table.evidence.landedOnAnotherKeyframe, 1);
102
- });
103
-
104
- test("a table that has read nothing claims no evidence about itself", () => {
105
- // It cannot be wrong about a file it has not described. `readable` is false,
106
- // every picture of the file is re-encoded, and no copy can witness anything.
107
- const table = new KeyframeTable().learn({ times: null, format: "mpegts" });
108
-
109
- assert.equal(table.evidence, null);
110
- assert.equal(table.names(4), false);
111
- });
112
-
113
- test("a segment requested again is not new evidence", () => {
114
- const table = fourSecondKeyframes();
115
-
116
- for (let repeat = 0; repeat < 3; repeat += 1) {
117
- table.witness({ index: 1, trueStart: 4.9, deviationSec: 0.9, toleranceSec: TOLERANCE });
118
- }
119
-
120
- assert.equal(table.evidence.checked, 1, "a repeat request is the same boundary, counted once");
121
- assert.equal(table.evidence.disagreed, 1);
122
- });
123
-
124
- test("a boundary the index got wrong is replaced by the time the file really has", async (t) => {
125
- const { wireOutputs } = await import("../services/server/wire-outputs.js");
126
- const manager = wireOutputs({
127
- enabled: true,
128
- ffmpegBin: "ffmpeg",
129
- localBindHost: "127.0.0.1",
130
- localPort: 9090
131
- });
132
- t.after(() => manager.lifecycle.disposeAll());
133
- // ONE table for the film, held by both. It used to be a copy each, kept in
134
- // step by writing the correction into every member — which is what the shared
135
- // table replaces, and what drifted in the field.
136
- const boundaries = [0, 10, 20, 30, 40];
137
- const base = {
138
- id: "aaaaaaaa11112222",
139
- spec: outputSpec({ transcodeVideo: false }),
140
- fileName: "film.mkv",
141
- state: "ready",
142
- timeline: new Timeline({ boundaries: boundaries, cutGrid: "uniform" }),
143
- file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "film.mkv" }),
144
- segmentFormat: { segmentFileName: (index) => `segment-${index}.mp4` }
145
- };
146
- const rung = {
147
- id: "bbbbbbbb11112222",
148
- spec: outputSpec({ transcodeVideo: true, height: 540 }),
149
- fileName: "film.mkv",
150
- state: "ready",
151
- timeline: new Timeline({ boundaries: boundaries, cutGrid: "uniform" }),
152
- // A step of the picture: the same file, and made as a step.
153
- file: base.file,
154
- variantHeight: 540,
155
- isStep: true
156
- };
157
- manager.outputs.set(base.id, base);
158
- manager.outputs.set(rung.id, rung);
159
- manager.outputs.markStep(rung);
160
-
161
- // The copy produced segment #2, and it really begins at 17.4 s — the index
162
- // said 20. This is the shape reproduced from the field on 2026-08-12.
163
- manager.outputTimes.correctBoundaryFromSegment(base, 2, 17.4);
164
-
165
- assert.equal(
166
- base.timeline.boundaries[2],
167
- 17.4,
168
- "the grid must describe the file, not the index — a rung forced onto 20 s would not join the copy"
169
- );
170
- assert.equal(
171
- rung.timeline.boundaries[2],
172
- 17.4,
173
- "the family shares one grid — the same array, so there is nothing to keep in step"
174
- );
175
- assert.deepEqual(
176
- base.timeline.boundaries,
177
- [0, 10, 17.4, 30, 40],
178
- "only the boundary that was shown to be wrong moves"
179
- );
180
-
181
- // A reading that cannot be a boundary is not evidence about one. It comes
182
- // from a run that started somewhere else, and applying it would leave the
183
- // table describing nothing.
184
- manager.outputTimes.correctBoundaryFromSegment(base, 2, 35);
185
- manager.outputTimes.correctBoundaryFromSegment(base, 2, 5);
186
- manager.outputTimes.correctBoundaryFromSegment(base, 0, 3);
187
- assert.deepEqual(base.timeline.boundaries, [0, 10, 17.4, 30, 40], "out-of-order readings are refused");
188
- });
@@ -1,123 +0,0 @@
1
- /**
2
- * @file How long anybody waits for the file's keyframe table.
3
- *
4
- * With the table a picture is copied; without it the whole picture is
5
- * re-encoded, which on a weak host is the difference between almost free and
6
- * more than the machine has. Until 2.76.1 there was no bound on that wait at
7
- * all, and the file comes off a torrent — so the bytes the table lives in may
8
- * still be arriving, and a session could sit there for as long as they took.
9
- *
10
- * Measured on the addon host 2026-09-04 over fifteen torrents
11
- * (`research/keyframe-table-read-2026-09-04.md`): every read whose bytes were
12
- * there finished within 8.8 s, while reads on swarms of one to four peers were
13
- * still waiting at 60-121 s. The bound sits between those two, and what it must
14
- * do is pinned here.
15
- */
16
-
17
- import test from "node:test";
18
- import assert from "node:assert/strict";
19
- import { KeyframeTables } from "../services/media/KeyframeTables.js";
20
- import { BytesUnavailable } from "../services/media/container/unavailable.js";
21
-
22
- const QUIET = { info: () => {}, warn: () => {} };
23
-
24
- /**
25
- * @param {number} budgetMs
26
- * @param {(params: object) => Promise<object | null>} readTable
27
- * @returns {KeyframeTables}
28
- */
29
- function tables(budgetMs, readTable) {
30
- return new KeyframeTables({ readTable, budgetMs, logger: QUIET });
31
- }
32
-
33
- const FILE = { sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" };
34
-
35
- test("a table that arrives inside the budget is the answer", async () => {
36
- const keyframes = tables(1_000, async () => ({ times: [0, 4, 8], tolerance: 0, format: "matroska" }));
37
-
38
- const { table, arrived } = await keyframes.within(FILE);
39
-
40
- assert.deepEqual(table.times, [0, 4, 8]);
41
- assert.equal(arrived, true, "the file has answered, so the picture may be copied");
42
- assert.equal(table.readable, true);
43
- });
44
-
45
- test("a table that has not arrived gives up on copying rather than on the session", async () => {
46
- // The bytes it needs are still coming off the swarm. On the field host this
47
- // is a torrent with one peer: the read was still waiting after two minutes.
48
- const keyframes = tables(60, () => new Promise(() => {}));
49
-
50
- const startedAt = Date.now();
51
- const { table, arrived } = await keyframes.within(FILE);
52
- const waited = Date.now() - startedAt;
53
-
54
- assert.equal(table.readable, false, "no table, so this session cannot copy the picture");
55
- assert.equal(
56
- table.answered,
57
- false,
58
- "and the file has NOT answered — an absence recorded as an answer would make a passing " +
59
- "shortage of bytes look like a property of the bytes"
60
- );
61
- assert.equal(arrived, false);
62
- assert.ok(waited < 2_000, `the wait ended at the bound, not at the read (${waited}ms)`);
63
- });
64
-
65
- test("the read goes on after the budget, so the next session of the file gets the copy", async () => {
66
- let reads = 0;
67
- let answerLate = null;
68
- const keyframes = tables(40, () => {
69
- reads += 1;
70
- return new Promise((resolve) => {
71
- answerLate = resolve;
72
- });
73
- });
74
-
75
- const first = await keyframes.within(FILE);
76
- assert.equal(first.arrived, false);
77
-
78
- answerLate({ times: [0, 5, 10], tolerance: 0, format: "matroska" });
79
- // Every microtask this resolution queues, and not a chosen ten milliseconds.
80
- // `setImmediate` runs after the whole microtask queue of this turn, so the
81
- // answer has been taken in by the time it fires — where the ten milliseconds
82
- // were a guess about how long that takes on whatever machine is running.
83
- // Asking the reader again instead would have counted as another read, which
84
- // is the very thing the last assertion here is about.
85
- await new Promise((resolve) => { setImmediate(resolve); });
86
-
87
- const second = await keyframes.within(FILE);
88
- assert.deepEqual(second.table.times, [0, 5, 10], "the late answer was kept, not thrown away");
89
- assert.equal(second.arrived, true);
90
- assert.equal(reads, 1, "and it was not read a second time");
91
- });
92
-
93
- test("a read that fails is not turned into a bounded wait's silence", async () => {
94
- const keyframes = tables(1_000, async () => {
95
- throw new Error("the head is not downloaded");
96
- });
97
-
98
- await assert.rejects(
99
- () => keyframes.read(FILE),
100
- /the head is not downloaded/,
101
- "a read that threw is a different thing from a read that is still running"
102
- );
103
- });
104
-
105
- test("bytes not downloaded yet are a table that has not arrived, and the next arrival reads again", async () => {
106
- let calls = 0;
107
- const keyframes = tables(1_000, async () => {
108
- calls += 1;
109
- if (calls === 1) {
110
- throw new BytesUnavailable(100, 199, 0);
111
- }
112
- return { times: [0, 4], tolerance: 0, format: "matroska" };
113
- });
114
-
115
- const { table, arrived } = await keyframes.within(FILE);
116
- assert.equal(arrived, false, "the opening goes on and re-encodes; it is not failed over a shortage of bytes");
117
- assert.equal(table.answered, false, "missing bytes say nothing about the file's keyframes");
118
-
119
- keyframes.readAgainIfUnanswered(FILE);
120
- await keyframes.read(FILE);
121
- assert.equal(calls, 2);
122
- assert.deepEqual(keyframes.of(FILE).times, [0, 4]);
123
- });
@@ -1,249 +0,0 @@
1
- /**
2
- * @file Where a file's keyframes are is a fact of the file, not of a session.
3
- *
4
- * It is a property of immutable bytes, like the duration and the track list, so
5
- * a second reading could only agree. Two sessions created in the same moment
6
- * used to read it twice — which is what two viewers opening one film do,
7
- * measured 13 ms apart on 2026-09-03 — and the answer decides whether the
8
- * picture can be copied at all, so it has to be one answer.
9
- *
10
- * And it has to be one OBJECT, not one value: a session created while the read
11
- * is still running must see the answer when it lands. Held as a value it could
12
- * not, and the read that outran its budget was lost to every session already
13
- * made.
14
- */
15
-
16
- import test from "node:test";
17
- import assert from "node:assert/strict";
18
- import { KeyframeTables } from "../services/media/KeyframeTables.js";
19
- import { KeyframeTable } from "../services/media/container/KeyframeTable.js";
20
- import { Container } from "../services/media/container/Container.js";
21
-
22
- const QUIET = { info: () => {}, warn: () => {} };
23
-
24
- /**
25
- * @param {(params: object) => Promise<object | null>} readTable
26
- * @param {number} [budgetMs]
27
- * @returns {KeyframeTables}
28
- */
29
- function tables(readTable, budgetMs = 1_000) {
30
- return new KeyframeTables({ readTable, budgetMs, logger: QUIET });
31
- }
32
-
33
- const FILE = { sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" };
34
-
35
- test("two askers at once make one read and join one wait", async () => {
36
- let reads = 0;
37
- let answer = null;
38
- const keyframes = tables(() => {
39
- reads += 1;
40
- return new Promise((resolve) => {
41
- answer = resolve;
42
- });
43
- });
44
-
45
- const first = keyframes.warm(FILE);
46
- const second = keyframes.warm(FILE);
47
- assert.equal(reads, 1, "the second asker joined the read already running");
48
-
49
- answer({ times: [0, 4, 8], tolerance: 0, format: "matroska" });
50
- await Promise.all([first, second]);
51
- assert.equal(reads, 1);
52
- });
53
-
54
- test("the answer is remembered for the file, so a later asker reads nothing", async () => {
55
- let reads = 0;
56
- const keyframes = tables(async () => {
57
- reads += 1;
58
- return { times: [0, 4, 8], tolerance: 0, format: "matroska" };
59
- });
60
-
61
- await keyframes.warm(FILE);
62
- await keyframes.warm(FILE);
63
-
64
- assert.equal(reads, 1);
65
- });
66
-
67
- test("two files of one torrent are two answers", async () => {
68
- const asked = [];
69
- const keyframes = tables(async ({ fileIndex }) => {
70
- asked.push(fileIndex);
71
- return { times: [0, 4], tolerance: 0, format: "matroska" };
72
- });
73
-
74
- await keyframes.warm({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" });
75
- await keyframes.warm({ sourceKey: "torrent:abc", fileIndex: 1, logName: "b.mkv" });
76
-
77
- assert.deepEqual(asked, [0, 1]);
78
- });
79
-
80
- test("a file with no readable index says so once, and keeps saying it", async () => {
81
- let reads = 0;
82
- const keyframes = tables(async () => {
83
- reads += 1;
84
- return null;
85
- });
86
-
87
- await keyframes.warm({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.ts" });
88
- await keyframes.warm({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.ts" });
89
-
90
- // "No index" is an answer about the file — it is what makes a copy of it
91
- // re-encode instead — and it must be the same answer for every viewer.
92
- assert.equal(reads, 1);
93
- const table = keyframes.of(FILE);
94
- assert.equal(table.answered, true, "something came back");
95
- assert.equal(table.readable, false, "and what came back was nothing");
96
- });
97
-
98
- test("a table read after a session was made still reaches it", async () => {
99
- let answer = null;
100
- const keyframes = tables(() => new Promise((resolve) => { answer = resolve; }), 30);
101
-
102
- // What a session does: ask for the file's table, wait as long as it may, and
103
- // carry whatever it was handed.
104
- const { table, arrived } = await keyframes.within(FILE);
105
- assert.equal(arrived, false, "the read outran the budget");
106
- assert.equal(table.answered, false, "and nothing has answered yet, which is not the same as no keyframes");
107
-
108
- answer({ times: [0, 4, 8], tolerance: 0, format: "matroska" });
109
- await new Promise((resolve) => { setImmediate(resolve); });
110
-
111
- // The session is holding THIS object, so the late answer is in its hands
112
- // without anybody having gone round telling it.
113
- assert.equal(table.answered, true);
114
- assert.deepEqual(table.times, [0, 4, 8]);
115
- assert.equal(keyframes.of(FILE), table, "and the file still has one table, not two");
116
- });
117
-
118
- test("a read that threw is not an answer, and the next asker reads again", async () => {
119
- let reads = 0;
120
- const keyframes = tables(async () => {
121
- reads += 1;
122
- if (reads === 1) {
123
- // The bytes it needed had not arrived. That says nothing about the file,
124
- // and recording it as "no keyframes" would re-encode every picture of
125
- // this file for as long as the process lives.
126
- throw new Error("the head is not downloaded");
127
- }
128
- return { times: [0, 6], tolerance: 0, format: "matroska" };
129
- });
130
-
131
- await assert.rejects(() => keyframes.read(FILE), /the head is not downloaded/);
132
- assert.equal(keyframes.of(FILE).answered, false);
133
-
134
- const table = await keyframes.read(FILE);
135
-
136
- assert.equal(reads, 2, "it was read again rather than refused from a cached failure");
137
- assert.deepEqual(table.times, [0, 6]);
138
- });
139
-
140
- test("the packet probe never displaces a fuller table", () => {
141
- const keyframes = tables(async () => ({ times: [0, 2, 4, 6, 8], tolerance: 0, format: "matroska" }));
142
- keyframes.learn(FILE, { times: [0, 2, 4, 6, 8], format: "matroska" });
143
-
144
- // Measured 2026-08-02: a packet scan found 77 keyframes in 45 s without
145
- // finishing, against all 570 in 0.8 s from the container's own index.
146
- keyframes.learn(FILE, { times: [0, 8], format: "packet probe" });
147
-
148
- const table = keyframes.of(FILE);
149
- assert.deepEqual(table.times, [0, 2, 4, 6, 8]);
150
- assert.equal(table.format, "matroska");
151
- });
152
-
153
- test("the packet probe IS the answer where no container index exists", () => {
154
- const keyframes = tables(async () => null);
155
- keyframes.learn(FILE, { times: null, format: "mpegts" });
156
- assert.equal(keyframes.of(FILE).readable, false);
157
-
158
- keyframes.learn(FILE, { times: [0, 3, 6], format: "packet probe" });
159
-
160
- assert.deepEqual(keyframes.of(FILE).times, [0, 3, 6]);
161
- });
162
-
163
- test("a registry with no reader says nothing about the file rather than lying about it", async () => {
164
- const keyframes = new KeyframeTables({ logger: QUIET });
165
-
166
- const table = await keyframes.read(FILE);
167
-
168
- assert.equal(table.readable, false, "there is no table, so a picture of this file is re-encoded");
169
- assert.equal(
170
- table.answered,
171
- false,
172
- "and nothing has ANSWERED — a proxy wired without a reader is not a statement about anybody's bytes"
173
- );
174
- });
175
-
176
- test("a table nobody holds is dropped, and one still being read is not", async () => {
177
- let answer = null;
178
- const keyframes = tables(() => new Promise((resolve) => { answer = resolve; }));
179
- const held = keyframes.of({ sourceKey: "torrent:abc", fileIndex: 0 });
180
- const dropped = keyframes.of({ sourceKey: "torrent:abc", fileIndex: 1 });
181
- void keyframes.warm({ sourceKey: "torrent:abc", fileIndex: 2, logName: "c.mkv" });
182
- const reading = keyframes.of({ sourceKey: "torrent:abc", fileIndex: 2 });
183
-
184
- keyframes.forgetUnused(new Set([held]));
185
-
186
- assert.equal(keyframes.of({ sourceKey: "torrent:abc", fileIndex: 0 }), held);
187
- assert.notEqual(keyframes.of({ sourceKey: "torrent:abc", fileIndex: 1 }), dropped);
188
- assert.equal(
189
- keyframes.of({ sourceKey: "torrent:abc", fileIndex: 2 }),
190
- reading,
191
- "dropping a file whose read is in flight loses the answer and pays the whole wait again"
192
- );
193
- answer(null);
194
- });
195
-
196
- test("the container reads and does not remember — one fact, one store", async () => {
197
- // It used to keep the answer, which made this table the one fact in the proxy
198
- // stored twice: here, and in the file's own `KeyframeTable`. Traced
199
- // 2026-09-15, this copy had no reader: nothing in the torrent thread asks
200
- // where a file's keyframes are, and the one path to it ends at
201
- // `KeyframeTables` on the other side of the channel.
202
- let parses = 0;
203
- class Counting extends Container {
204
- async parseKeyframeIndex() {
205
- parses += 1;
206
- return { times: [0, 2, 4], tolerance: 0 };
207
- }
208
- }
209
- const container = new Counting({ readRange: async () => null, fileSize: 10 });
210
-
211
- await container.readKeyframeIndex();
212
- await container.readKeyframeIndex();
213
-
214
- assert.equal(parses, 2, "a container that keeps the answer is a second owner of it");
215
- });
216
-
217
- test("reading once per file is the table registry's job, and it also bounds the wait", async () => {
218
- // Where the guarantee went. It is not merely moved: this is the only place
219
- // that can ALSO stop a viewer waiting for ever while letting the read finish,
220
- // which a container cannot — it does not know there is a viewer.
221
- let parses = 0;
222
- class Counting extends Container {
223
- async parseKeyframeIndex() {
224
- parses += 1;
225
- return { times: [0, 2, 4], tolerance: 0 };
226
- }
227
- }
228
- const container = new Counting({ readRange: async () => null, fileSize: 10 });
229
- const keyframes = tables(() => container.readKeyframeIndex());
230
-
231
- await Promise.all([keyframes.read(FILE), keyframes.read(FILE)]);
232
- await keyframes.read(FILE);
233
-
234
- assert.equal(parses, 1);
235
- assert.deepEqual(keyframes.of(FILE).times, [0, 2, 4]);
236
- });
237
-
238
- test("answered and readable are two questions, and a bag of fields cannot tell them apart", () => {
239
- const table = new KeyframeTable();
240
- assert.equal(table.answered, false);
241
- assert.equal(table.readable, false);
242
- assert.equal(table.format, "not yet read");
243
-
244
- table.learn({ times: null, format: "mpegts" });
245
-
246
- assert.equal(table.answered, true, "the container came back");
247
- assert.equal(table.readable, false, "with no keyframes, which is permanent for this file");
248
- assert.equal(table.format, "mpegts", "and the refusal can name what it is refusing");
249
- });
@@ -1,37 +0,0 @@
1
- /**
2
- * @file Adopting a new median only when it has moved further than the readings
3
- * behind it disagree with each other.
4
- */
5
- import assert from "node:assert/strict";
6
- import { test } from "node:test";
7
- import { medianOf, movedBeyondScatter, scatterOf } from "../services/encode/learned-median.js";
8
-
9
- test("the median is the middle reading, and the mean of the two middle ones", () => {
10
- assert.equal(medianOf([3, 1, 2]), 2);
11
- assert.equal(medianOf([1, 2, 3, 4]), 2.5);
12
- assert.equal(medianOf([]), null);
13
- assert.equal(medianOf([Number.NaN]), null);
14
- });
15
-
16
- test("the scatter is the median distance from the middle", () => {
17
- assert.equal(scatterOf([10, 10, 10]), 0);
18
- assert.equal(scatterOf([8, 10, 12]), 2);
19
- assert.equal(scatterOf([]), null);
20
- });
21
-
22
- test("the first answer is always adopted", () => {
23
- assert.equal(movedBeyondScatter(null, 5, [5]), true);
24
- });
25
-
26
- test("a move smaller than the readings' own disagreement is the same answer", () => {
27
- assert.equal(movedBeyondScatter(10, 11, [8, 10, 12]), false);
28
- });
29
-
30
- test("a move larger than that disagreement is adopted", () => {
31
- assert.equal(movedBeyondScatter(10, 13, [8, 10, 12]), true);
32
- });
33
-
34
- test("readings that all agree let any change through", () => {
35
- assert.equal(movedBeyondScatter(10, 10.4, [10, 10, 10]), true);
36
- assert.equal(movedBeyondScatter(10, 10, [10, 10, 10]), false);
37
- });