@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,225 +0,0 @@
1
- # The priority map is the only statement of what is wanted
2
-
3
- Measurements and decisions behind the work listed in the roadmap as "the
4
- priority map is the only source of truth about what is wanted". Written
5
- 2026-09-12, extended as the steps land.
6
-
7
- Everything below is tagged by where it comes from: READ (from the source),
8
- MEASURED (a number produced here), DECIDED (agreed with the user), or REFUSED
9
- (considered and not built, with the reason).
10
-
11
- ## Why 2.83.1 stopped playback — READ
12
-
13
- The map is built by `PriorityOrchestrator.publishFor`, and its only input is the
14
- live SESSIONS (`hls-session-manager.js` hands it `sessionGroups`). A session
15
- exists once a file has been chosen and its playback plan built. The torrent,
16
- however, is added on `POST /api/sources/:key/warm`, while the person is still
17
- reading the list of episodes.
18
-
19
- So there is an interval in which the map cannot say anything at all, and in it
20
- "the map wants nothing" is indistinguishable from "there is nobody to ask yet".
21
- The field record of 2026-09-11 lies entirely inside that interval: added
22
- 20:57:17, first peer 20:57:18, out of the swarm 20:57:21 with 741 connections
23
- let go.
24
-
25
- ## The same fault with the opposite sign — READ
26
-
27
- When the last viewer of a file leaves, `publishFor` deletes that file's map from
28
- its own memory and publishes NOTHING:
29
-
30
- ```js
31
- for (const key of [...this.#maps.keys()]) {
32
- if (!byFile.has(key)) { this.#maps.delete(key); this.#last.delete(key); }
33
- }
34
- ```
35
-
36
- `applyPriorityMap` withdraws a file's claimants only when it is CALLED, so the
37
- demand register keeps that file's zones for the life of the torrent — nothing
38
- else removes them but `forgetTorrent`, which runs when the torrent is removed
39
- altogether.
40
-
41
- Both ends are therefore broken: today the map can say neither "wanted" nor "not
42
- wanted". That is what has to be fixed before the register can be believed by
43
- anybody.
44
-
45
- ## The register alone cannot be asked — READ
46
-
47
- A read states a claim only while it is STOPPED on a missing piece
48
- (`piece-reader.js:765`, `Urgency.BLOCKED`) and withdraws it when the read ends
49
- (`:1052`). So an empty register routinely means "at this instant everybody has
50
- what they need", not "nobody wants this". A swarm rule built on the register
51
- alone would release and rejoin repeatedly. The stable statement is the map,
52
- which holds while people are there.
53
-
54
- ## No viewer-to-torrent link is needed — DECIDED
55
-
56
- A session carries `sourceKey`, and the map is addressed by source and file. So
57
- "is anybody here for this source" is already answered by any file of it having a
58
- non-empty map. A second holder of that same relation would be the two-owners
59
- fault this work removes, in a new place.
60
-
61
- ## What is in a torrent, as one statement — MEASURED
62
-
63
- `services/torrent/Contents.js`, validated against the survey collection in
64
- `Dropbox/trn` on 2026-09-12 (137 files, 134 parsed):
65
-
66
- | | |
67
- |---|---|
68
- | torrents parsed | 134 |
69
- | of them with more than one picture | 44 |
70
- | items (pictures with what belongs to them) | 1357 |
71
- | files paired to a picture | 421 |
72
- | files paired to more than one picture | 0 |
73
- | largest torrent | 265 pictures |
74
- | items whose grouping differs from the per-picture call it replaces | 0 |
75
-
76
- The last row is what says this is a move rather than a change: every one of the
77
- 1357 groupings agrees with `matchSidecarFiles` asked the old way, one picture at
78
- a time.
79
-
80
- The largest figure matters to the step that follows: a pack of 265 pictures is
81
- why the edges are claimed one item at a time rather than for the whole list —
82
- two pieces outstanding at a time, and the order is what bounds the cost.
83
-
84
- ## Telling an episode from an extra — REFUSED
85
-
86
- Proposed, measured, and not built.
87
-
88
- **Words.** `sample|trailer|extras?|bonus|preview|teaser|making|interview|
89
- deleted|featurette` as whole tokens against every video path of the 134
90
- torrents: **four matches, all four false**. Three are the word "making" inside
91
- ordinary episode titles ("Making cash with her pussy", "Perfect pleasure making
92
- pussy") and their sizes are 0.84 to 2.35 of their torrent's median, i.e. they
93
- are the content. Not one real `Sample/` file exists in the collection, so the
94
- rule cannot even be validated here — that is a property of this collection, not
95
- a claim that extras do not exist.
96
-
97
- **Size.** The ratio of each video to the median of the videos in its own torrent
98
- runs continuously from 0.0000 to 1.0 with no gap anywhere: 53 videos sit under a
99
- quarter of their median, and they are short clips that ARE what the torrent is
100
- for (`REX1080_<name> - 720P_4000K_….mp4`, 6-23 MB, in collections of them). Two
101
- shapes are genuinely not content — `preview1..5.mp4` in one torrent, and
102
- `VIDEO_TS/VIDEO_TS.VOB` plus `VTS_01_0.VOB`, which are a DVD's menu and a
103
- structure question rather than a size one.
104
-
105
- So there is nothing here to derive a threshold from, and an invented one would
106
- decide the order in which a stranger's bandwidth is spent. Every picture is an
107
- item. The survey script is `scratchpad`-only and is reproduced by walking the
108
- collection with `parse-torrent` and the two functions named above.
109
-
110
- ## Two classifications of one torrent, and they have already diverged — MEASURED
111
-
112
- The browser classifies the file list itself (`public/domain/torrent-parser.js`,
113
- `VIDEO_EXTENSIONS`, `classifyMediaFiles`, `orderForDisplay`) and the proxy does
114
- it again (`services/torrent/files.js`). Compared 2026-09-12: the browser offers
115
- `.dat` as video and the proxy does not count it, every other extension agreeing.
116
- On such a torrent the person is offered a file the proxy does not consider a
117
- picture, and `countVideoFiles` answers 0 — which also changes the one-picture
118
- relaxation in the pairing.
119
-
120
- One fact, one owner: the proxy owns the composition and the file-list route
121
- returns it. The cost is one round trip for a `.torrent` the browser parsed
122
- locally; the proxy holds those same bytes from registration, so it can answer
123
- without the swarm.
124
-
125
- ## What the pool asks now, and the two things it no longer counts — DECIDED
126
-
127
- One question: **is anything wanted of this torrent**, answered from the register
128
- (`isWanted`). It is true from the moment a torrent is opened, because a torrent
129
- with no file list yet cannot be stated about and is being fetched precisely
130
- because somebody asked for it; and it becomes false exactly when the last
131
- viewer leaves, because that is when the map is published with nothing in it.
132
-
133
- Two facts decide the swarm, and they are separated from the doing
134
- (`swarmDecisionFor`) because this is the rule that has failed twice in the
135
- field:
136
-
137
- | wanted | ever wanted | swarm | idle clock |
138
- |---|---|---|---|
139
- | yes | — | take | stopped |
140
- | no | yes | let go | running |
141
- | no | no | leave alone | running |
142
-
143
- The last row is the 2.83.1 failure as a rule rather than as a mechanism: a
144
- torrent nobody has ever wanted is one being OPENED, and taking its swarm away
145
- there destroys the connections it will need a minute later.
146
-
147
- **Leaving on `done` was considered and NOT built.** A complete torrent can want
148
- nothing from a swarm, and the field case of 596 connections was exactly that.
149
- But a piece can be lost after the fact — the disk tier discards pieces under
150
- its own cap — and rejoining would then need a trigger nothing states today, so
151
- the failure mode is a read that waits for ever. The complete-file case is
152
- already answered from two directions: the upload policy refuses to seed when
153
- nothing anybody asked for is missing, and `keepWholeFiles` destroys a torrent
154
- whose every file has been written out whole.
155
-
156
- **What is accepted as narrowed, and stated so it is not discovered as a
157
- surprise.** A read that is flowing states nothing — it is reading bytes that
158
- are present — so a torrent is no longer held by the mere existence of a read.
159
- Three cases were checked: a `/stream` read belongs to a session whose map is
160
- live; the subtitle walk reads only what is downloaded; the background fill of a
161
- sidecar is covered by that file's ends. What is left is the disk cap evicting a
162
- torrent whose read is in flight during a moment when nothing is stated for it.
163
- The eviction order is the mitigation rather than a guard: candidates are sorted
164
- by when they were last WANTED, so a torrent an encoder is reading sorts last
165
- among them.
166
-
167
- **A torrent is on the idle clock from the moment it exists.** Until now the only
168
- thing that ever started that clock was a reader letting go, so a file list
169
- fetched and never played was held for the life of the process.
170
-
171
- ## What the review of this work caught — READ
172
-
173
- Two defects, both found by reading the finished code rather than by a test, and
174
- both fixed with a check apiece.
175
-
176
- 1. **A warm-up could take the urgency away from a plan somebody was waiting
177
- for.** The two ends of a file are stated by whoever asks for them, and there
178
- are two such callers: the playback plan, which a person is watching a loading
179
- screen for, and the warm-up, which by its whole purpose nobody is waiting
180
- for. The warm-up fires off the files beside the picture without awaiting
181
- them, so it can arrive second — and it restated the same claimants at its own
182
- lower level. The statement is raise-only now; the one caller entitled to put
183
- them back down is the read that has just finished, which says so.
184
- 2. **A departure could be noticed by nobody.** The background fill states a
185
- claim of its own per file and withdraws it once nothing else wants that file
186
- — but the withdrawal happened inside a pass that nothing acted on, so a
187
- torrent everybody had left could be held "wanted" by the fill's own claim at
188
- the moment of the departure and then never re-examined: in its swarm, with no
189
- idle clock running. The pass acts on what it just said now.
190
-
191
- ## Where the shared statement lives — DECIDED, then REVERSED the same day
192
-
193
- It was first published as a package, `@torrent-tv/torrent-contents`, so that
194
- both runtimes could read the same three files: the proxy states what to fetch
195
- from them, and the browser showed the list of episodes the instant a `.torrent`
196
- was dropped, before a proxy had been chosen.
197
-
198
- **Withdrawn within the hour, on the user's question: is the package better than
199
- moving it all to the proxy, when the torrent has to go there after the choice
200
- anyway.** It is not. The package bought one property — the instant list — with
201
- three permanent costs: a third artifact to version and publish, two copies at
202
- runtime that drift by version (a test was written for that drift, which is an
203
- admission the risk is real), and three wiring points that break the page at load
204
- with no error anybody sees (a second test was written for those).
205
-
206
- The answer is the route that already lists a source's files. For a magnet
207
- nothing changes at all — that is the path it has always taken — and the dropped
208
- `.torrent` now takes the same one. What leaves the browser with it is not only
209
- the classification but the whole notion of deciding anything from a name; what
210
- stays is what only the browser can see (the trackers and the web seeds in the
211
- file it holds) and how a name is SHOWN.
212
-
213
- **The cost is answered by connecting earlier, which is the user's own point.**
214
- Everything a viewer does needs a proxy, and choosing one and connecting to it
215
- used to begin only after a file had been picked. It begins when the page loads
216
- now, silently and with its failure swallowed, and `#acquireTransport` is
217
- joinable — so whatever the viewer does next joins that attempt instead of
218
- starting a second. Verified in a browser 2026-09-12: the page opens, the connect
219
- runs on its own (`public-only connect failed …; trying local path` on a dev
220
- server with no proxies registered), nothing is shown for it, and the page's own
221
- adapter turns the proxy's answer into the three lists with the order preserved,
222
- the torrent's own numbers kept and the release's repeated part taken off the
223
- names.
224
-
225
- `@torrent-tv/torrent-contents@1.0.0` is deprecated on npm with the reason.
@@ -1,31 +0,0 @@
1
- /** Build-time only. No sample generation runs when the proxy starts. */
2
- import { spawnSync } from "node:child_process";
3
- import { mkdirSync, writeFileSync } from "node:fs";
4
- import path from "node:path";
5
- import { fileURLToPath } from "node:url";
6
-
7
- const directory = fileURLToPath(new URL("../assets/calibration/audio/", import.meta.url));
8
- const formats = [
9
- ["aac", "aac", "m4a"], ["ac3", "ac3", "ac3"], ["eac3", "eac3", "eac3"],
10
- ["dts", "dca", "dts"], ["flac", "flac", "flac"], ["opus", "libopus", "opus"],
11
- ["vorbis", "libvorbis", "ogg"], ["truehd", "truehd", "thd"], ["mp3", "libmp3lame", "mp3"],
12
- ["mp2", "mp2", "mp2"], ["alac", "alac", "m4a"], ["pcm", "pcm_s16le", "wav"]
13
- ];
14
- mkdirSync(directory, { recursive: true });
15
- const manifest = [];
16
- for (const [codec, encoder, extension] of formats) {
17
- const file = `${codec}.${extension}`;
18
- const result = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y",
19
- "-f", "lavfi", "-i", "anoisesrc=color=pink:seed=1:sample_rate=48000",
20
- "-t", "4", "-ac", "2", "-strict", "-2", "-c:a", encoder, path.join(directory, file)],
21
- { encoding: "utf8", windowsHide: true });
22
- if (result.status !== 0) throw new Error(`${codec}: ${result.stderr}`);
23
- const probe = spawnSync("ffprobe", ["-v", "error", "-show_streams", "-show_format", "-of", "json",
24
- path.join(directory, file)], { encoding: "utf8", windowsHide: true });
25
- if (probe.status !== 0) throw new Error(`${codec}: ${probe.stderr}`);
26
- const { streams, format } = JSON.parse(probe.stdout);
27
- const stream = streams.find(({ codec_type }) => codec_type === "audio");
28
- manifest.push({ codec, file, durationSeconds: Number(format.duration), channels: stream.channels,
29
- samplingFrequency: Number(stream.sample_rate), bytes: Number(format.size) });
30
- }
31
- writeFileSync(path.join(directory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -1,173 +0,0 @@
1
- #!/usr/bin/env node
2
- /**
3
- * @file Render the encoder-run table as a document, FROM the table.
4
- *
5
- * The picture is not drawn beside the code — it is produced from the same data
6
- * the code executes, so it cannot describe a machine that no longer exists. A
7
- * test regenerates it and compares, which is what makes "the table is the
8
- * single source" enforceable rather than a promise.
9
- *
10
- * Run it with `npm run graph`.
11
- */
12
-
13
- import { writeFileSync } from "node:fs";
14
- import path from "node:path";
15
- import { fileURLToPath } from "node:url";
16
-
17
- import {
18
- ABSENT_EDGE_INVARIANTS,
19
- ENCODE_RUN_EVENT,
20
- ENCODE_RUN_STATE,
21
- EVENT_MEANING,
22
- INITIAL_RUN_STATE,
23
- STATE_MEANING,
24
- answerForMissingSegment,
25
- declaredContainment,
26
- declaredEdges,
27
- isInputBeingRead,
28
- mayRestart,
29
- processCanBeSignalled,
30
- wireState
31
- } from "../services/encode/encode-run-state.js";
32
-
33
- /** Where the rendered document lives. */
34
- export const GRAPH_DOC_PATH = path.join(
35
- path.dirname(fileURLToPath(import.meta.url)),
36
- "..",
37
- "docs",
38
- "encode-run-state.md"
39
- );
40
-
41
- const ALL_STATES = Object.values(ENCODE_RUN_STATE);
42
- const ALL_EVENTS = Object.values(ENCODE_RUN_EVENT);
43
-
44
- /**
45
- * Children of each node of the containment tree, in declaration order.
46
- *
47
- * @returns {{ root: string, childrenOf: Map<string, string[]> }}
48
- */
49
- function containmentTree() {
50
- const childrenOf = new Map();
51
- let root = null;
52
- for (const { state, parent } of declaredContainment()) {
53
- if (parent === null) {
54
- root = state;
55
- continue;
56
- }
57
- if (!childrenOf.has(parent)) {
58
- childrenOf.set(parent, []);
59
- }
60
- childrenOf.get(parent).push(state);
61
- }
62
- return { root, childrenOf };
63
- }
64
-
65
- /**
66
- * One composite block, and everything nested inside it.
67
- *
68
- * @param {string} node
69
- * @param {Map<string, string[]>} childrenOf
70
- * @param {number} depth
71
- * @returns {string[]} Lines, already indented.
72
- */
73
- function renderBlock(node, childrenOf, depth) {
74
- const pad = " ".repeat(depth);
75
- const children = childrenOf.get(node) ?? [];
76
- if (children.length === 0) {
77
- return [`${pad}${node}`];
78
- }
79
- const lines = [`${pad}state ${node} {`];
80
- if (children.includes(INITIAL_RUN_STATE)) {
81
- lines.push(`${pad} [*] --> ${INITIAL_RUN_STATE}`);
82
- }
83
- for (const child of children) {
84
- lines.push(...renderBlock(child, childrenOf, depth + 1));
85
- }
86
- lines.push(`${pad}}`);
87
- return lines;
88
- }
89
-
90
- /**
91
- * The whole document.
92
- *
93
- * @returns {string}
94
- */
95
- export function renderRunGraphMarkdown() {
96
- const { root, childrenOf } = containmentTree();
97
- const lines = [];
98
-
99
- lines.push(
100
- "<!-- GENERATED from services/encode/encode-run-state.js by scripts/render-run-graph.js.",
101
- " Do not edit by hand: change the table and run `npm run graph`. -->",
102
- "",
103
- "# The encoder run — states and transitions",
104
- "",
105
- "One run of one ffmpeg inside one transcode session. The table this is drawn",
106
- "from is executed by `services/encode/EncodeRuns.js`; every transition a real",
107
- "run makes is logged as state, event and target, so a run that takes an edge",
108
- "absent here is a violation the log names.",
109
- "",
110
- "```mermaid",
111
- "stateDiagram-v2"
112
- );
113
- lines.push(...renderBlock(root, childrenOf, 1));
114
- lines.push("");
115
- for (const edge of declaredEdges()) {
116
- lines.push(` ${edge.from} --> ${edge.to} : ${edge.event}`);
117
- }
118
- lines.push("```", "");
119
-
120
- lines.push("## States", "", "| state | means |", "|---|---|");
121
- for (const state of ALL_STATES) {
122
- lines.push(`| \`${state}\` | ${STATE_MEANING[state]} |`);
123
- }
124
- lines.push("");
125
-
126
- lines.push("## Events", "", "| event | means |", "|---|---|");
127
- for (const event of ALL_EVENTS) {
128
- lines.push(`| \`${event}\` | ${EVENT_MEANING[event]} |`);
129
- }
130
- lines.push("");
131
-
132
- lines.push(
133
- "## What each state answers",
134
- "",
135
- "Outputs depend on the state alone — computed here by calling the same",
136
- "functions the session manager calls.",
137
- "",
138
- "| state | reads its input | can be signalled | a missing segment | on the wire | may restart |",
139
- "|---|---|---|---|---|---|"
140
- );
141
- for (const state of ALL_STATES) {
142
- lines.push(
143
- `| \`${state}\` | ${isInputBeingRead(state) ? "yes" : "no"} | ` +
144
- `${processCanBeSignalled(state) ? "yes" : "no"} | ${answerForMissingSegment(state)} | ` +
145
- `\`${wireState(state)}\` | ${mayRestart(state) ? "yes" : "no"} |`
146
- );
147
- }
148
- lines.push("");
149
-
150
- lines.push(
151
- "## Edges that must never exist",
152
- "",
153
- "The machine's real content: a near-complete digraph asserts nothing.",
154
- "",
155
- "| from | event | must not reach | because |",
156
- "|---|---|---|---|"
157
- );
158
- for (const invariant of ABSENT_EDGE_INVARIANTS) {
159
- lines.push(
160
- `| \`${invariant.from}\` | \`${invariant.event}\` | \`${invariant.mustNotReach}\` | ${invariant.because} |`
161
- );
162
- }
163
- lines.push("");
164
-
165
- return `${lines.join("\n")}`;
166
- }
167
-
168
- // Written only when this file is the program being run, so importing it from a
169
- // test cannot rewrite the very file the test is about to compare against.
170
- if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
171
- writeFileSync(GRAPH_DOC_PATH, renderRunGraphMarkdown(), "utf8");
172
- process.stdout.write(`wrote ${GRAPH_DOC_PATH}\n`);
173
- }
@@ -1,28 +0,0 @@
1
- /**
2
- * @file Paths a module builds from its own location still name what they meant.
3
- *
4
- * A file that joins `..` onto its own directory is right only at the depth it
5
- * was written at. Moving files into their components (2.87.0) left the gdb
6
- * script of the usrsctp reader pointing one directory short, and no check
7
- * noticed: the path is read only when a wedge is diagnosed.
8
- */
9
-
10
- import test from "node:test";
11
- import assert from "node:assert/strict";
12
- import { existsSync } from "node:fs";
13
- import path from "node:path";
14
- import { CALIBRATION_DIR } from "../services/encode/hwaccel.js";
15
- import { PROXY_ROOT } from "../services/encode/quality/HostTimings.js";
16
- import { SCTPSTATE_SCRIPT_PATH } from "../services/transport/usrsctp-state.js";
17
-
18
- test("the calibration clips are where the benchmark looks", () => {
19
- assert.ok(existsSync(CALIBRATION_DIR), CALIBRATION_DIR);
20
- });
21
-
22
- test("the usrsctp state script is where the reader looks", () => {
23
- assert.ok(existsSync(SCTPSTATE_SCRIPT_PATH), SCTPSTATE_SCRIPT_PATH);
24
- });
25
-
26
- test("the default place for host timings is the proxy's own directory", () => {
27
- assert.ok(existsSync(path.join(PROXY_ROOT, "package.json")), PROXY_ROOT);
28
- });
@@ -1,77 +0,0 @@
1
- import assert from "node:assert/strict";
2
- import { readFileSync } from "node:fs";
3
- import test from "node:test";
4
- import { readPresentationRanges, servedPresentationRanges, walkBoxes } from "../services/encode/segment-formats/mp4-boxes.js";
5
- import { predictPlaybackReadiness } from "../services/viewer/playback-readiness.js";
6
-
7
- const evidence = JSON.parse(readFileSync(new URL("./fixtures/audio-frame-boundary.json", import.meta.url), "utf8"));
8
- const header = Buffer.from(evidence.files["init.mp4"], "base64");
9
-
10
- function served(name, shiftedFrames = 0) {
11
- const bytes = Buffer.from(evidence.files[name], "base64");
12
- let frameTicks;
13
- walkBoxes(bytes, (type, start) => {
14
- if (type === "tfhd") {
15
- const flags = bytes.readUIntBE(start + 1, 3);
16
- const at = start + 8 + ((flags & 1) ? 8 : 0) + ((flags & 2) ? 4 : 0);
17
- if (flags & 8) frameTicks = bytes.readUInt32BE(at);
18
- }
19
- if (type === "tfdt" && shiftedFrames) {
20
- assert.ok(frameTicks > 0);
21
- bytes.writeBigUInt64BE(bytes.readBigUInt64BE(start + 4) + BigInt(frameTicks * shiftedFrames), start + 4);
22
- }
23
- });
24
- return servedPresentationRanges(readPresentationRanges(Buffer.concat([header, bytes])), header);
25
- }
26
-
27
- const seconds = ({ timescale }, ticks) => Number(ticks) / Number(timescale);
28
-
29
- function state(second = served("segment-00172.mp4")) {
30
- const first = served("segment-00171.mp4");
31
- const now = 1000;
32
- const firstStart = seconds(first, first.ranges[0].start);
33
- const secondStart = seconds(second, second.ranges[0].start);
34
- const secondEnd = seconds(second, second.ranges.at(-1).end);
35
- return {
36
- now,
37
- positionSeconds: firstStart,
38
- durationSeconds: secondEnd,
39
- reserveSeconds: 0,
40
- lookaheadSeconds: secondEnd - firstStart,
41
- sources: [{ id: "source", complete: true }],
42
- linkReadings: [{ at: now, value: 1_000_000 }],
43
- tracks: [{
44
- id: "audio", sourceIds: ["source"], clockOffsetSeconds: 0, clientRanges: [
45
- { start: evidence.browserBufferedRanges[0][0], end: evidence.browserBufferedRanges[0][1] }
46
- ],
47
- readings: [{ at: now, value: 1 }],
48
- readySegmentIndices: [0, 1], segmentSizesBytes: { 0: 170000, 1: 170000 },
49
- segments: [
50
- { index: 0, startSeconds: firstStart, endSeconds: secondStart, mediaRanges: first },
51
- { index: 1, startSeconds: secondStart, endSeconds: secondEnd, mediaRanges: second }
52
- ]
53
- }]
54
- };
55
- }
56
-
57
- test("the captured AAC join, 432 ticks at 48 kHz, is one Chrome closed and every engine closes", () => {
58
- const input = state();
59
- assert.equal(predictPlaybackReadiness(input).ready, true);
60
- // Without the frame durations the pieces state, nothing allows the gap.
61
- for (const segment of input.tracks[0].segments) {
62
- segment.mediaRanges = { ...segment.mediaRanges,
63
- ranges: segment.mediaRanges.ranges.map((range) => ({ ...range, frame: 0n })) };
64
- }
65
- assert.equal(predictPlaybackReadiness(input).reason, "media-continuity-unavailable");
66
- });
67
-
68
- test("four missing AAC frames preserve the discontinuity observed in Chrome", () => {
69
- assert.equal(predictPlaybackReadiness(state(served("segment-00172.mp4", 4))).reason,
70
- "media-continuity-unavailable");
71
- });
72
-
73
- test("a join never supplies audio before the adjacent segment arrives", () => {
74
- const input = state();
75
- input.linkReadings[0].value = 1;
76
- assert.notEqual(predictPlaybackReadiness(input).ready, true);
77
- });
@@ -1,23 +0,0 @@
1
- import assert from "node:assert/strict";
2
- import test from "node:test";
3
- import { audioReadingFor } from "../services/encode/audio-calibration.js";
4
-
5
- const readings = [
6
- { codec: "ac3", operation: "aac", channels: 2, samplingFrequency: 48000, speed: 120 },
7
- { codec: "aac", operation: "copy", channels: 2, samplingFrequency: 48000, speed: 200,
8
- bytes: 64000, durationSeconds: 4 }
9
- ];
10
-
11
- test("audio processing uses codec and sample work instead of a video-copy rate", () => {
12
- assert.equal(audioReadingFor(readings, { codec: "ac3", transcode: true, channels: 6,
13
- samplingFrequency: 48000 }).speed, 40);
14
- assert.equal(audioReadingFor(readings, { codec: "ac3", transcode: true, channels: 2,
15
- samplingFrequency: 24000 }).speed, 240);
16
- assert.equal(audioReadingFor(readings, { codec: "dts", transcode: true }), null);
17
- });
18
-
19
- test("copying uses encoded byte work when the source declares its bitrate", () => {
20
- assert.equal(audioReadingFor(readings, { codec: "aac", transcode: false, bitrateKbps: 256 }).speed, 100);
21
- assert.equal(audioReadingFor(readings, { codec: "aac", transcode: false }).speed, 200);
22
- assert.equal(audioReadingFor(readings, { codec: "aac", transcode: true }), null);
23
- });