@torrent-tv/proxy 2.89.17 → 2.89.18

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 (299) hide show
  1. package/README.md +14 -3
  2. package/package.json +10 -2
  3. package/server.js +0 -11
  4. package/.claude/commands/opsx/apply.md +0 -155
  5. package/.claude/commands/opsx/archive.md +0 -160
  6. package/.claude/commands/opsx/explore.md +0 -174
  7. package/.claude/commands/opsx/propose.md +0 -109
  8. package/.claude/commands/opsx/sync.md +0 -143
  9. package/.claude/skills/openspec-apply-change/SKILL.md +0 -159
  10. package/.claude/skills/openspec-archive-change/SKILL.md +0 -117
  11. package/.claude/skills/openspec-explore/SKILL.md +0 -289
  12. package/.claude/skills/openspec-propose/SKILL.md +0 -113
  13. package/.claude/skills/openspec-sync-specs/SKILL.md +0 -147
  14. package/.dockerignore +0 -5
  15. package/AGENTS.md +0 -363
  16. package/CHANGELOG.md +0 -2377
  17. package/Dockerfile +0 -30
  18. package/biome.json +0 -412
  19. package/corpus.tmp.json +0 -1
  20. package/docs/browser-proxy-contract.md +0 -155
  21. package/docs/container-architecture.md +0 -273
  22. package/docs/download-architecture.md +0 -261
  23. package/docs/encode-architecture.md +0 -765
  24. package/docs/encode-run-state.md +0 -96
  25. package/docs/logs.md +0 -151
  26. package/docs/playback-start-forecast.md +0 -113
  27. package/docs/socks5-egress-research.md +0 -114
  28. package/docs/storage-architecture.md +0 -273
  29. package/knip.json +0 -14
  30. package/main2.cpuprofile +0 -1
  31. package/openspec/changes/adaptive-bitrate/.openspec.yaml +0 -0
  32. package/openspec/changes/adaptive-bitrate/design.md +0 -92
  33. package/openspec/changes/adaptive-bitrate/proposal.md +0 -56
  34. package/openspec/changes/adaptive-bitrate/specs/adaptive-bitrate/spec.md +0 -51
  35. package/openspec/changes/adaptive-bitrate/tasks.md +0 -40
  36. package/openspec/changes/binary-distribution/.openspec.yaml +0 -2
  37. package/openspec/changes/binary-distribution/proposal.md +0 -53
  38. package/openspec/changes/chunked-request-bodies/design.md +0 -81
  39. package/openspec/changes/chunked-request-bodies/proposal.md +0 -53
  40. package/openspec/changes/chunked-request-bodies/specs/chunked-request-bodies/spec.md +0 -30
  41. package/openspec/changes/chunked-request-bodies/tasks.md +0 -40
  42. package/openspec/changes/cold-start/design.md +0 -98
  43. package/openspec/changes/cold-start/proposal.md +0 -62
  44. package/openspec/changes/cold-start/specs/cold-start/spec.md +0 -47
  45. package/openspec/changes/cold-start/tasks.md +0 -48
  46. package/openspec/changes/disk-cap/.openspec.yaml +0 -2
  47. package/openspec/changes/disk-cap/proposal.md +0 -37
  48. package/openspec/changes/disk-cap/specs/disk-cap/spec.md +0 -25
  49. package/openspec/changes/disk-cap/tasks.md +0 -19
  50. package/openspec/changes/proxy-observability/.openspec.yaml +0 -2
  51. package/openspec/changes/proxy-observability/design.md +0 -38
  52. package/openspec/changes/proxy-observability/proposal.md +0 -49
  53. package/openspec/changes/proxy-observability/specs/observability/spec.md +0 -33
  54. package/openspec/changes/proxy-observability/tasks.md +0 -21
  55. package/openspec/changes/seek-debounce/.openspec.yaml +0 -0
  56. package/openspec/changes/seek-debounce/design.md +0 -118
  57. package/openspec/changes/seek-debounce/proposal.md +0 -59
  58. package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md +0 -41
  59. package/openspec/changes/seek-debounce/tasks.md +0 -33
  60. package/openspec/changes/subtitle-language/.openspec.yaml +0 -2
  61. package/openspec/changes/subtitle-language/proposal.md +0 -50
  62. package/openspec/changes/subtitle-language/specs/subtitle-language/spec.md +0 -34
  63. package/openspec/changes/subtitle-language/tasks.md +0 -26
  64. package/openspec/changes/track-selection/.openspec.yaml +0 -2
  65. package/openspec/changes/track-selection/design.md +0 -47
  66. package/openspec/changes/track-selection/proposal.md +0 -45
  67. package/openspec/changes/track-selection/specs/track-selection/spec.md +0 -41
  68. package/openspec/changes/track-selection/tasks.md +0 -20
  69. package/openspec/changes/transcode-quality/.openspec.yaml +0 -2
  70. package/openspec/changes/transcode-quality/proposal.md +0 -51
  71. package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md +0 -139
  72. package/openspec/changes/transcode-quality/tasks.md +0 -63
  73. package/openspec/config.yaml +0 -38
  74. package/public/.well-known/appspecific/com.chrome.devtools.json +0 -1
  75. package/research/delivery-wedge-stand-ladder-2026-09-13.md +0 -329
  76. package/research/double-spawn-2026-09-10.md +0 -171
  77. package/research/handover-2026-09-13.md +0 -209
  78. package/research/handover-reader-claims-removal-2026-09-12.md +0 -166
  79. package/research/piece-withdrawn-but-still-claimed-2026-09-12.md +0 -175
  80. package/research/preset-benchmark-size-scaling-2026-08-22.md +0 -55
  81. package/research/priority-map-is-the-truth-2026-09-12.md +0 -225
  82. package/research/valgrind-replica-2026-08-27/logs.tar.gz +0 -0
  83. package/scripts/build-audio-samples.mjs +0 -31
  84. package/scripts/render-run-graph.js +0 -173
  85. package/test/asset-paths.test.js +0 -28
  86. package/test/audio-buffer-continuity.test.js +0 -77
  87. package/test/audio-calibration.test.js +0 -23
  88. package/test/audio-inventory.test.js +0 -212
  89. package/test/audio-track-bitrate.test.js +0 -40
  90. package/test/audio-warm-recorded.test.js +0 -63
  91. package/test/auto-quality-step.test.js +0 -762
  92. package/test/available-share.test.js +0 -76
  93. package/test/background-fill.test.js +0 -190
  94. package/test/client-log-file.test.js +0 -126
  95. package/test/client-logs-route.test.js +0 -34
  96. package/test/coalesce.test.js +0 -39
  97. package/test/completed-files.test.js +0 -115
  98. package/test/concurrent-cost.test.js +0 -148
  99. package/test/container-media-info.test.js +0 -228
  100. package/test/contention.test.js +0 -76
  101. package/test/core-dumps.test.js +0 -57
  102. package/test/coverage-follows-the-disk.test.js +0 -233
  103. package/test/coverage-map.test.js +0 -195
  104. package/test/cue-push-carries-what-the-walk-found.test.js +0 -58
  105. package/test/cut-times-timeline.test.js +0 -65
  106. package/test/cuts-follow-published-grid.test.js +0 -109
  107. package/test/data-channel-frame.test.js +0 -63
  108. package/test/data-channel-viewer-lifecycle.test.js +0 -193
  109. package/test/dead-torrent-handle.test.js +0 -52
  110. package/test/declared-rates.test.js +0 -116
  111. package/test/declared-tracks.test.js +0 -43
  112. package/test/decode-cost-fit.test.js +0 -202
  113. package/test/decode-cost.test.js +0 -475
  114. package/test/delivery-probe-field.test.js +0 -173
  115. package/test/delivery-probe.test.js +0 -382
  116. package/test/demand-register.test.js +0 -206
  117. package/test/dht-bootstrap.test.js +0 -72
  118. package/test/drain-threat.test.js +0 -65
  119. package/test/duplicate-add.test.js +0 -48
  120. package/test/encode-admission.test.js +0 -170
  121. package/test/encode-cost.test.js +0 -275
  122. package/test/encode-exit.test.js +0 -111
  123. package/test/encode-orchestrator.test.js +0 -426
  124. package/test/encode-plan-viewers.test.js +0 -725
  125. package/test/encode-plan.test.js +0 -545
  126. package/test/encode-run-state.test.js +0 -314
  127. package/test/encode-run.test.js +0 -248
  128. package/test/encode-slope.test.js +0 -46
  129. package/test/encoded-output.test.js +0 -39
  130. package/test/encoder-kinds.test.js +0 -122
  131. package/test/encoder-readings.test.js +0 -68
  132. package/test/episode-naming.test.js +0 -131
  133. package/test/every-claimant-is-told-its-share.test.js +0 -152
  134. package/test/failed-encoder-still-serves-what-exists.test.js +0 -354
  135. package/test/failed-start-breaker.test.js +0 -202
  136. package/test/fastest-wires.test.js +0 -143
  137. package/test/ffmpeg-stream-counts.test.js +0 -101
  138. package/test/file-edges.test.js +0 -191
  139. package/test/files-in-use.test.js +0 -34
  140. package/test/fixtures/audio-frame-boundary.json +0 -1
  141. package/test/fixtures/refused-audio-20261002.json +0 -10
  142. package/test/fmp4-presentation-clock.test.js +0 -148
  143. package/test/fmp4-self-contained.test.js +0 -80
  144. package/test/fmp4-timestamps.test.js +0 -140
  145. package/test/fmp4-track-completeness.test.js +0 -41
  146. package/test/format-keyed-outputs.test.js +0 -78
  147. package/test/health-metrics.test.js +0 -36
  148. package/test/held-read-ownership.test.js +0 -77
  149. package/test/held-request-width.test.js +0 -157
  150. package/test/helpers/encode-run.js +0 -248
  151. package/test/helpers/held-file.js +0 -77
  152. package/test/helpers/manager.js +0 -62
  153. package/test/helpers/matroska-file.js +0 -296
  154. package/test/helpers/output-spec.js +0 -63
  155. package/test/host-load.test.js +0 -68
  156. package/test/index-accuracy-is-about-the-file.test.js +0 -128
  157. package/test/init-compat.test.js +0 -219
  158. package/test/input-lost-quiets-the-plan.test.js +0 -261
  159. package/test/input-unavailable.test.js +0 -48
  160. package/test/installation-id.test.js +0 -39
  161. package/test/keeping-period.test.js +0 -83
  162. package/test/keyframe-index-accuracy.test.js +0 -188
  163. package/test/keyframe-table-budget.test.js +0 -123
  164. package/test/keyframes-belong-to-the-file.test.js +0 -249
  165. package/test/learned-median.test.js +0 -37
  166. package/test/letting-go-asks-who-is-watching.test.js +0 -191
  167. package/test/limit-row-by-area.test.js +0 -60
  168. package/test/link-budget.test.js +0 -111
  169. package/test/link-probe.test.js +0 -56
  170. package/test/local-encoding-data.test.js +0 -273
  171. package/test/logger-repeats.test.js +0 -134
  172. package/test/look-ahead-coverage.test.js +0 -56
  173. package/test/manager-surface.test.js +0 -291
  174. package/test/matroska-blocks.test.js +0 -0
  175. package/test/matroska-cluster-discovery.test.js +0 -323
  176. package/test/matroska-cues-track.test.js +0 -192
  177. package/test/media-time.test.js +0 -62
  178. package/test/memory-budget.test.js +0 -390
  179. package/test/move-cost.test.js +0 -216
  180. package/test/mp4-composition-times.test.js +0 -0
  181. package/test/mp4-subtitles.test.js +0 -173
  182. package/test/one-authority.test.js +0 -285
  183. package/test/one-budget.test.js +0 -149
  184. package/test/one-output-one-session.test.js +0 -273
  185. package/test/one-resource-divided.test.js +0 -185
  186. package/test/one-serving-output-per-height.test.js +0 -458
  187. package/test/orchestrator-wired.test.js +0 -207
  188. package/test/output-catalog.test.js +0 -39
  189. package/test/output-shape.test.js +0 -21
  190. package/test/output-spec.test.js +0 -251
  191. package/test/output-speed.test.js +0 -92
  192. package/test/outputs-being-prepared.test.js +0 -40
  193. package/test/packet-witness-ring.test.js +0 -236
  194. package/test/packet-witness.test.js +0 -148
  195. package/test/piece-completeness.test.js +0 -78
  196. package/test/piece-disk-store.test.js +0 -401
  197. package/test/piece-from-whole-file.test.js +0 -129
  198. package/test/piece-lru.test.js +0 -319
  199. package/test/piece-reader.test.js +0 -162
  200. package/test/piece-selection-offset.test.js +0 -85
  201. package/test/piece-store-eviction.test.js +0 -595
  202. package/test/piece-store-never-refuses.test.js +0 -153
  203. package/test/piece-store-reservations.test.js +0 -403
  204. package/test/piece-store-slow-disk.test.js +0 -159
  205. package/test/piece-tail.test.js +0 -97
  206. package/test/plan-host-timings.test.js +0 -68
  207. package/test/plan-is-steady.test.js +0 -225
  208. package/test/playback-readiness.test.js +0 -518
  209. package/test/playback-start-regressions.test.js +0 -101
  210. package/test/priority-map-download.test.js +0 -174
  211. package/test/priority-map-emptied.test.js +0 -204
  212. package/test/priority-map-per-output.test.js +0 -215
  213. package/test/priority-map.test.js +0 -163
  214. package/test/probe-wedge-certainty.test.js +0 -60
  215. package/test/produced-copy-choice.test.js +0 -213
  216. package/test/published-timeline.test.js +0 -83
  217. package/test/quality-offer.test.js +0 -160
  218. package/test/quality-variants.test.js +0 -1274
  219. package/test/rate-control-in-the-output.test.js +0 -181
  220. package/test/read-survives-withdrawal.test.js +0 -164
  221. package/test/read-window.test.js +0 -365
  222. package/test/reads-not-yet-arrived.test.js +0 -218
  223. package/test/resume-warm.test.js +0 -39
  224. package/test/run-graph-drift.test.js +0 -37
  225. package/test/run-inputs.test.js +0 -80
  226. package/test/run-intervals.test.js +0 -100
  227. package/test/run-position-follows-published-grid.test.js +0 -89
  228. package/test/run-progress.test.js +0 -64
  229. package/test/same-height-switch.test.js +0 -663
  230. package/test/seek-frees-the-viewers-requests.test.js +0 -217
  231. package/test/seek-landing.test.js +0 -109
  232. package/test/seek-target-not-superseded.test.js +0 -195
  233. package/test/segment-closed-on-both-branches.test.js +0 -114
  234. package/test/segment-cut-times.test.js +0 -63
  235. package/test/segment-demand.test.js +0 -80
  236. package/test/segment-hold-supersede.test.js +0 -91
  237. package/test/segment-judged-by-its-own-header.test.js +0 -222
  238. package/test/segment-serve-wiring.test.js +0 -481
  239. package/test/segment-store-eviction.test.js +0 -247
  240. package/test/segment-store.test.js +0 -352
  241. package/test/segment-true-start.test.js +0 -86
  242. package/test/segments-are-shared.test.js +0 -176
  243. package/test/send-chunk-bytes.test.js +0 -86
  244. package/test/serving-existing-output.test.js +0 -111
  245. package/test/serving-output.test.js +0 -102
  246. package/test/shared-piece-store.test.js +0 -310
  247. package/test/sidecar-naming.test.js +0 -142
  248. package/test/soundtrack-rate-bound.test.js +0 -289
  249. package/test/source-file.test.js +0 -133
  250. package/test/source-files-route.test.js +0 -113
  251. package/test/source-registry.test.js +0 -18
  252. package/test/split-a-stretch.test.js +0 -139
  253. package/test/stale-request-after-seek.test.js +0 -158
  254. package/test/startup-readings.test.js +0 -124
  255. package/test/stream-route.test.js +0 -237
  256. package/test/subtitle-cue-framing.test.js +0 -200
  257. package/test/subtitle-cue-source.test.js +0 -102
  258. package/test/subtitle-cue-walk.test.js +0 -385
  259. package/test/subtitle-cursor.test.js +0 -63
  260. package/test/subtitle-defaults.test.js +0 -118
  261. package/test/subtitle-language.test.js +0 -252
  262. package/test/subtitle-metadata.test.js +0 -15
  263. package/test/subtitle-plan-waits.test.js +0 -125
  264. package/test/subtitle-track-numbering.test.js +0 -391
  265. package/test/supply-margin.test.js +0 -190
  266. package/test/swarm-follows-readers.test.js +0 -174
  267. package/test/swarm-reach.test.js +0 -130
  268. package/test/swarm-selection.test.js +0 -220
  269. package/test/tail-duplication.test.js +0 -167
  270. package/test/the-channel-has-both-ends.test.js +0 -91
  271. package/test/the-torrent-thread-serves-bytes.test.js +0 -107
  272. package/test/thread-pool.test.js +0 -53
  273. package/test/timeline.test.js +0 -84
  274. package/test/torrent-contents.test.js +0 -235
  275. package/test/torrent-cost.test.js +0 -71
  276. package/test/torrent-files.test.js +0 -221
  277. package/test/torrent-naming.test.js +0 -255
  278. package/test/tracks-begin-together.test.js +0 -209
  279. package/test/tunnel-renewal.test.js +0 -167
  280. package/test/two-viewers-one-picture.test.js +0 -508
  281. package/test/upload-hurry.test.js +0 -186
  282. package/test/usrsctp-state.test.js +0 -131
  283. package/test/video-facts.test.js +0 -102
  284. package/test/viewer-assignments.test.js +0 -143
  285. package/test/viewer-outputs.test.js +0 -285
  286. package/test/viewer-presence.test.js +0 -116
  287. package/test/viewer-requests-admission.test.js +0 -92
  288. package/test/viewer-starts-on-map.test.js +0 -27
  289. package/test/viewer-states.test.js +0 -192
  290. package/test/viewer-subtitle-subscription.test.js +0 -96
  291. package/test/viewer.test.js +0 -139
  292. package/test/viewing-generations.test.js +0 -390
  293. package/test/visible-rung.test.js +0 -37
  294. package/test/wait-ledger.test.js +0 -100
  295. package/test/webrtc-shim.test.js +0 -149
  296. package/test/wedge-certainty.test.js +0 -131
  297. package/test/whole-file-held-read.test.js +0 -30
  298. package/test/withdraw-piece-claim.test.js +0 -212
  299. 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
- });