@torrent-tv/proxy 2.89.16 → 2.89.18

package/research/handover-2026-09-13.md

@@ -1,209 +0,0 @@
-# Передача: клин доставки, стенд и werift — 2026-09-13
-
-Написано для того, кто продолжит. Всё, что ниже, либо прочитано из журналов и
-кода, либо помечено как непроверенное.
-
-## 1. Что установила сессия 2026-09-12 (прокси 2.83.5)
-
-Показ встал на **521,2 с фильма** и не возобновился. Причина — клин доставки,
-и он снят на проводе с обеих сторон. Разбор:
-`research/delivery-wedge-on-the-wire-2026-09-12.md`.
-
-Цепочка, каждое звено с числом из журнала:
-
-1. 21:50:39.658 — последнее, что браузер получил. Его счётчик канала
-   `proxy=12112msg/479898176B` не сдвинулся больше ни разу;
-2. прокси продолжал отдавать: `sent=485243979 → 485263428`, очереди
-   `queued[proxy:0B proxy-control:0B proxy-fast:0B]`, `rtt=24ms`,
-   `pc=connected ice=completed`. Обратное направление работало весь клин;
-3. через ассоциацию прошло **485 МБ**. Прежние эпизоды: 783, 813, 825, 2294 МБ.
-   Порога по объёму нет;
-4. обрыв пойман посреди отдачи одного куска: `bytes=10657210 sendMs=360
-   bufferedAtEnd=0` — usrsctp принял всё, очередь пуста; на проводе за
-   следующие три секунды ушло 6 727 961 байт (≈63 %), и в середине четвёртой —
-   ноль, без ретрансмиссий и без утоньшения подтверждений.
-
-**Лечение было измерено и выброшено.** Браузер поднял вторую ассоциацию к тому
-же пиру, прокачал `GET /api/delivery-sink?bytes=4194304` за 140 мс, записал
-`the fault is held in the wedged association` — и **закрыл её через 0,45 с**.
-Показ остался на мёртвой.
-
-**Почему зритель сидит навсегда, а не минуту:** лестница пересоединения не
-запускается. В клиентском журнале нет ни `transport lost`, ни `reconnect
-attempt`, потому что заклинивший канал остаётся `state=connected
-ice=connected`, и объявлять его потерянным нечему. В тот же вечер в 20:03 на
-ЗАКРЫТОМ канале та же лестница отработала штатно.
-
-## 2. Две поправки к роадмапу, сделанные чтением кода
-
-1. **`waitForBufferDrain` УЖЕ починен** (`services/data-channel-handler.js:1199`,
-   выпущено в 2.80.6): он ждёт нижней отметки с опросом каждые 50 мс,
-   постоянная `DC_BUFFER_DRAIN_TIMEOUT_MS` удалена. Запись в роадмапе
-   («fails open», 2026-09-06) устарела.
-2. **И он всё равно не защищает.** В поле 2026-09-12 `bufferedAtEnd=0` и
-   `drainMs=0` на каждой строке: наша очередь пуста, потому что libdatachannel
-   отдал байты в usrsctp, а держит их usrsctp. `bufferedAmount()` слеп к этому
-   по построению — прокси отдал 10,6 МБ в тишину и не узнал.
-
-**Что на месте этого предложено и НЕ построено:** backpressure по тому, что
-зритель ПОДТВЕРДИЛ. Браузер уже сообщает счётчики каждого канала
-(`proxy=12112msg/479898176B` в строке `[dc-far]`, раз в 500 мс). Отправка
-сверяется с ними, а не только с `bufferedAmount()`. Порог не выбирать — вывести
-из того, сколько байт эта связь держит в полёте при здоровой работе.
-
-## 3. Обновление зависимости — проверено, не лечит
-
-Пин `^0.32.0`, в npm **0.33.4**. Внутри libdatachannel 0.24.2 → 0.24.5.
-Подмодуль usrsctp сверен по четырём тегам (v0.24.2, .3, .4, .5):
-`fec583d54493f879d2ae44a743423bf8a04371ab` во всех. **От клина не лечит.**
-Запись роадмапа «upstream fix waiting нет» была верна на 26.08; теперь
-перепроверена и по-прежнему верна по существу, но libdatachannel ушёл вперёд
-на три версии (там исправление прерывистых отказов DTLS-рукопожатия).
-
-## 4. werift — исследовано, читая сам пакет
-
-werift 0.24.4, MIT, обновлён 2026-08-10, один автор. 4,2 МБ, 9 зависимостей.
-`ice/`, `dtls/`, `sctp/`, `rtp/`, `webrtc/` — полная реализация на TypeScript.
-
-**За:**
-1. usrsctp исчезает целиком, а с ним и подозреваемый;
-2. ни одной нативной зависимости (`@noble/curves`, `tweetnacl`,
-   `@peculiar/x509` — чистый JS). Ни prebuilt, ни musl/aarch64, ни сборки в
-   дополнении. Для проекта с одним форком нативного модуля и девятью смертями
-   процесса это существенно;
-3. `bufferedAmount`, `bufferedAmountLow`, `bufferedAmountLowThreshold` есть —
-   наш backpressure переносится.
-
-**Против:**
-1. **Мультиплексирования одного UDP-порта нет.** `lib/common/src/transport.js:130`
-   создаёт `dgram.createSocket` на соединение; `icePortRange` — диапазон, а не
-   общий сокет. У нас `IceUdpMuxListener` держит один порт 9090 на все сессии,
-   и ровно он замаплен UPnP — шаг 3 удалённого доступа (2.9.18). На werift
-   каждая сессия берёт свой порт, которого в маппинге нет;
-2. **Цена в процессоре не измерена и может быть запретительной.**
-   `lib/sctp/src/sctp.js:16` — `USERDATA_MAX_LENGTH = 1200`. Сообщение в 65 КБ
-   режется на 55 SCTP-кусков, каждый собирается в JS, CRC32c через
-   `Buffer.concat` на пакет (`chunk.js:763`), поверх — DTLS-шифрование на JS.
-   При 8 Мбит/с ≈830 пакетов/с; на измеренных 24.08 пиках 150-330 Мбит/с —
-   за 30 000/с. На CM4, который кодирует 1080p на 1,96x.
-
-**Вывод:** werift снимает подозреваемого и платит сломанным единым портом и
-неизвестной производительностью. Назвать его решением до замера нельзя.
-Замер дешёвый: поднять werift-приёмник, прокачать гигабайт, сравнить загрузку
-процессора с сегодняшней.
-
-## 5. Стенд — построен наполовину, упёрся в выбор прокси
-
-Цель: измерить, ЗАВИСИТ ЛИ КЛИН ОТ РАЗМЕРА ПОРЦИИ. Это гейт на всё остальное,
-и он не снят ни разу — стенд 26.08 прокачал 1,0 ГБ без отказов, но его
-приёмник был libdatachannel, а нужен dcSCTP браузера.
-
-**Что работает:** `chrome-devtools` MCP подключён к Chrome 155 на 9222
-(`list_pages` отвечает). Локальный прокси поднимается и регистрируется:
-
-```
-node bin/cli.js --server-url https://webauth.courses --port 9091 \
-  --delivery-sink --name wedge-stand --log-file <path>
-```
-
-**Что мешает:** браузер его не выбирает. Дважды подряд, включая после
-перезагрузки страницы:
-
-```
-selectedId: f3013ad3 (полевой, хост дополнения)
-candidates: wedge-stand score=0.6075, proxy-f3013ad3 score=0.4466
-```
-
-Стенд имеет ЛУЧШИЙ счёт и не выбран. Отличие одно: `reachable: false` —
-сервер дозванивается снаружи и до машины разработчика не достаёт. Значит
-нагрузка пошла бы на рабочий узел, чего делать нельзя.
-
-**Два выхода, решение за пользователем:** сделать стенд достижимым (проброс
-порта) или добавить способ назначить прокси явно (правка продукта ради
-стенда).
-
-**Оговорка, которую надо держать при любом прогоне:** клин наступал при 485,
-783, 813, 825 и 2294 МБ — разброс впятеро. Одна прогонка на значение не
-докажет ничего; нужно по нескольку, и это часы прокачки. Если разброс внутри
-одного размера порции останется таким же, честный ответ — «не установлено», а
-не число.
-
-**Механика автономного прогона, продуманная и не построенная:** фоновый
-процесс через `run_in_background`; цикл в странице ставится ОДНИМ вызовом
-`evaluate_script` и дальше живёт сам; результат выходит через `client-logger`
-на сервер, а не через канал данных, — этот путь HTTP и переживает клин, чего
-сегодня не хватило (пункт 85: браузер замолчал ровно на клине).
-
-## 6. Что делать дальше, по порядку
-
-1. снять препятствие со стендом и взять замер размера порции — это гейт;
-2. backpressure по подтверждённому зрителем (§2), целиком наш код;
-3. замер werift на процессоре, если §1 не даст ответа;
-4. сообщить наверх: у нас есть то, чего нет ни у кого — два захвата с обеих
-   сторон и доказательство, что вторая ассоциация к тому же пиру работает в ту
-   же секунду. Ни в libdatachannel, ни в usrsctp вопрос не открыт.
-
-**Чего делать НЕ надо:** прямой HTTPS (шаги 6-7) как ответ на этот клин.
-Сказано пользователем 2026-09-12: это не решение проблемы.
-
-## 7. Что осталось незакрытым от прошлых сессий и всплыло сегодня
-
-1. ложное срабатывание 21:13:34 при 76 МБ прокачанных — 180 с захвата и файлы
-   кольца на показ, который шёл дальше ещё 37 минут;
-2. `--delivery-sink` включён на полевом прокси. Он отдаёт ответ любого размера
-   и существует только для стенда.
-
-## 8. СОСТОЯНИЕ НА КОНЕЦ 2026-09-12: дополнение ОСТАНОВЛЕНО, на его месте стенд
-
-**Смотреть нельзя, пока это не свёрнуто.** Дополнение остановлено намеренно
-(`ha apps stop b34a1737_torrent_tv_proxy`), и его место на порту 9090 занял
-контейнер `ttv-wedge-stand`, запущенный из того же образа
-(`b34a1737/aarch64-addon-torrent_tv_proxy:0.74.4`) с пропатченными
-`services/data-channel-handler.js` и `bin/cli.js`.
-
-**Свернуть:**
-
-```
-ssh ha 'sudo docker rm -f ttv-wedge-stand'
-ssh ha 'sudo docker exec hassio_cli ha apps start b34a1737_torrent_tv_proxy'
-```
-
-**Почему свой контейнер, а не правка живого.** Пробовал патчить контейнер
-дополнения — не выживает: `ha apps restart` пересоздаёт его из образа, а
-убийство процесса внутри поднимает watchdog, который тоже пересоздаёт. Дважды
-проверено по дате создания контейнера. Свой контейнер watchdog не трогает.
-
-**Что построено в продукте** (в npm НЕ опубликовано, в git НЕ закоммичено):
-`--send-chunk-bytes <N>` — размер одного сообщения канала данных;
-`bodySender` — чистая функция нарезки и склейки, восемь проверок
-(`test/send-chunk-bytes.test.js`), одна проверена на красноту поломкой склейки
-через границу чтения; `msgBytes=` в строке `[net-debug]`; `chunks=` теперь
-считает сообщения, а не чтения тела. Запись в CHANGELOG на 2.83.7.
-
-**Как сменить размер** (стенд перезапускается изнутри своего контейнера):
-
-```
-ssh ha 'sudo docker exec ttv-wedge-stand pkill -f cli.js'
-ssh ha 'sudo docker exec -d ttv-wedge-stand sh -c "node /usr/local/lib/node_modules/@torrent-tv/proxy/bin/cli.js --server-url https://webauth.courses --host 0.0.0.0 --port 9090 --ffmpeg-bin /usr/bin/ffmpeg --state-dir /standdata --delivery-sink --send-chunk-bytes 16384 --name wedge-stand > /standdata/stand.log 2>&1"'
-```
-
-**Нагрузка** ставится одним вызовом `evaluate_script` в открытой на
-`webauth.courses` вкладке Chrome (9222, chrome-devtools MCP): цикл поднимает
-СВОЁ соединение `new WebRtcProxy(id)` — рабочее соединение страницы не
-трогается, — тянет `GET /api/delivery-sink?bytes=4194304` подряд и пишет отчёты
-через `POST /api/client-logs`, то есть по HTTP, мимо заклинивающего канала.
-Состояние лежит в `window.__WEDGE_STAND__`, остановка — `.stopped = true`.
-
-**Читать результат:**
-
-```
-ssh do 'docker logs --tail 400 infra-server-1' | grep wedge-stand
-ssh ha 'sudo docker exec ttv-wedge-stand grep msgBytes /standdata/stand.log | tail -5'
-```
-
-**Ловушка, стоившая одного прогона:** локальный стенд на машине разработчика
-назывался тем же именем `wedge-stand`, и цикл подключился к нему вместо ХА.
-Целиться по id, не по имени. Локальный остановлен.
-
-**Опорный прогон запущен 2026-09-12 23:36 UTC** на `f312d1e6`, размер `asread`
-(65 382 байта), 4 МБ на запрос, 190-325 Мбит/с. Результата на момент записи нет.

package/research/handover-reader-claims-removal-2026-09-12.md

@@ -1,166 +0,0 @@
-# Handover: the priority map is the only thing that says a file is wanted
-
-Written 2026-09-12, after the instruction that reversed the work in the tree.
-
-## The instruction, in the user's own terms
-
-The priority map answers ONE question: how much is this stretch of this file
-wanted. Nothing anywhere asks WHO is reading a torrent. There are no reader
-counters. Everything built around counting readers comes out.
-
-The map is rebuilt when viewers come and go, so it already shows the current
-state of affairs. A second bookkeeping of the same thing is what has to go.
-
-## What is in the working tree right now, and why it is all wrong
-
-HEAD is `79e802a`. On top of it, UNCOMMITTED:
-
-| file | what was done to it |
-|---|---|
-| `services/torrent/ReaderClaims.js` | NEW, untracked. The whole class is the mistake. |
-| `services/torrent-pool.js` | `fileUsageByTorrent` replaced by `this.readers = new ReaderClaims()`; a listener on it calls `rejoinSwarm`, `leaveSwarm` and `#scheduleIdleRemoval`; `torrentsForUploadPolicy` changed from taking a usage map to taking an `isRead` predicate. |
-| `services/torrent-worker/worker.js` | `warmActiveFiles` (`:842`) and `keepWholeFiles` (`:1024`) read `pool.readers.of(torrent)`. |
-| `test/swarm-follows-readers.test.js` | the announcement test rewritten around `ReaderClaims`. |
-| `test/upload-hurry.test.js` | rewritten around the `isRead` predicate. |
-
-All of it counts readers. All of it comes out. Two further facts about this
-tree, both of which the next agent needs:
-
-1. A bulk text replacement earlier in that session DESTROYED three methods of
-   `TorrentPool` — `#scheduleIdleRemoval`, `#cancelIdleRemoval` and
-   `#forgetDeadTorrent` — which were then called but not defined. They were
-   restored BY HAND from HEAD and adapted, not diffed line by line against the
-   original. One log line was changed deliberately: the idle-timer message no
-   longer prints a reader count. **Diff the restored bodies against
-   `git show HEAD:services/torrent-pool.js` before trusting them**, or discard
-   the tree and start from HEAD.
-2. Discarding the uncommitted changes is probably the cheapest start, since
-   every one of them is being reversed. That is a destructive action and is the
-   USER'S CALL — ask before running anything that throws work away.
-
-## What already exists and answers the question without counting anybody
-
-Read these before designing. Line numbers are of the working tree.
-
-**The map is built from viewers and published.** `services/priority/PriorityOrchestrator.js`
-builds one map per film+file, and a second per output, from where the viewers
-are. `services/priority/PriorityMap.js` holds the scale and the words for
-reading it — `isAtAWatchingViewer`, `isBehindEverybody`, `isNobodyComingNow`.
-
-**The map reaches the torrent thread as a command.** `Command.PRIORITY_MAP` in
-`services/torrent-worker/worker.js:539` calls `pool.applyPriorityMap(torrent,
-fileIndex, zones, durationSeconds)`.
-
-**`applyPriorityMap` (`services/torrent-pool.js:1191`) is where seconds become
-bytes**, and it writes the result into the demand register:
-`demandFor(torrent).register.state({ claimant, fileIndex, byteStart, byteEnd,
-urgency })`, with the claimant named `${MAP_CLAIMANT}:${fileIndex}:${index}`
-(`:1257`). It WITHDRAWS its own stale claimants for that file afterwards
-(`:1266-1273`), so a map that shrinks does shrink the register. **Whether a map
-that wants NOTHING leaves the register empty for that file is not established —
-check it, do not assume it.**
-
-**The register is therefore the existing statement of what is wanted.**
-`services/demand/DemandRegister.js` offers `size`, `files()`, `windows()`,
-`at(urgency)`, `union(fileIndex)`, `mostUrgent()`, `withdraw(claimant)`,
-`clear()`. `services/download/registry.js` offers `demandFor(torrent)`,
-`hasUnmetDemand(torrent)`, `forgetTorrent(torrent)`, `reconcileAll()`.
-
-## THE TRAP — read this before writing a line
-
-**Not every claimant in the register is a viewer, and the ones that are not are
-exactly what a naive rule kills.**
-
-Measured claimants other than the map:
-
-- `services/torrent-worker/piece-reader.js:670` — a read that is STOPPED on a
-  piece right now, stated at the BLOCKED level. Only a read can say this; the
-  map deliberately never states BLOCKED (see the comment at
-  `torrent-pool.js:1204`).
-- `services/torrent-pool.js:1147`, `:1159`, `:1162` — the background fill and
-  the tail.
-
-And several reads exist that no viewer has yet asked for: the codec probe
-reading the file's head and tail, the keyframe table, the subtitle cluster
-walk, a sidecar soundtrack being fetched whole.
-
-**This is not hypothetical.** On 2026-09-11 a rule of exactly this shape shipped
-as proxy 2.83.1: a torrent nobody had stated anything about left its swarm. A
-torrent that has just been added has stated nothing yet, because its edges are
-still being read and its playback plan is still being built. Field record:
-added 20:57:17, first peer 20:57:18, out of the swarm 20:57:21 with 741
-connections let go, and nothing ever rejoined it — rejoining waited for a
-reader, and the reader was waiting for the header the swarm had been fetching.
-`peers=0 connected of 0 known (94 queued, 5 tracker(s) offered up to 683
-seeders)` for as long as the viewer would wait. Playback never started.
-
-So "the map wants nothing, therefore let the swarm go" is WRONG as written. The
-honest question is whether ANYTHING in the register wants bytes of this torrent
-— the map's zones and every other claimant together — and that question has to
-be asked of the register, which already knows, rather than of a counter.
-
-## What has to change, and what each site should ask instead
-
-Each of these currently asks "who is reading". Work out, per site, what it
-actually needs from the register.
-
-1. **`TorrentPool.acquireFile`** (`torrent-pool.js:1770`) and its release
-   function. Callers: `routes/stream/get.js:211`,
-   `routes/api/transcode-sessions/post.js:47`,
-   `services/controllers/SubtitleController.js:54`,
-   `services/torrent-worker/worker.js:251` and `:366`,
-   `services/torrent-worker/pool-adapter.js:88`,
-   `services/torrent-worker/client.js:327`. Note it also does two things that
-   are NOT counting: it cancels a pending idle removal and stamps
-   `#lastAccess`, which the disk-cap LRU reads. Decide where those two belong
-   before deleting the method.
-2. **Leaving and rejoining the swarm.** `leaveSwarm` and `rejoinSwarm` are
-   exported from `torrent-pool.js:465` and `:497`. Today the trigger is the
-   first claim taken and the last released. It becomes a fact of the register.
-3. **Idle removal.** `#scheduleIdleRemoval` fires on the last reader leaving and
-   re-checks for readers when the timer fires.
-4. **The upload policy.** `torrentsForUploadPolicy` (`torrent-pool.js:349`) sets
-   `torrent.hasActiveReader` and `torrent.hasUnmetDemand`. The second already
-   comes from the register (`hasUnmetDemand`); the first is the counter.
-5. **`#reportStalledDownloads`** (`:1311`) and **`#adjustUploadLimit`** (`:1354`)
-   skip a torrent with no readers.
-6. **The disk-cap LRU** (`:1411`) picks torrents with no readers.
-7. **`#removeTorrent`** (`:1886`) prints a refcount for diagnostics.
-8. **`warmActiveFiles`** (`worker.js:842`) walks "the files being read" to keep
-   subtitle cues current. `register.files()` says which files anything wants.
-9. **`keepWholeFiles`** (`worker.js:1024`) refuses to write a completed file out
-   while it is being read, so that the write does not take the disk from a
-   viewer. This one genuinely needs "is anybody reading THIS file right now" and
-   is the site most likely to need a different answer from the register than a
-   plain "is it wanted".
-
-## Rules that hold whatever the design turns out to be
-
-- **Plan first, approval before any edit.** No exceptions, including when told
-  to get on with it.
-- **Never add a line to `services/hls-session-manager.js`.** It is being taken
-  apart. Deletion only; `git diff --numstat` must show more removed than added.
-- **All code, comments and documents in the repositories are English.**
-- **Do not run the whole test suite.** Run the tests of the files changed.
-  Relevant here: `test/swarm-follows-readers.test.js`, `test/upload-hurry.test.js`,
-  `test/file-claims.test.js`, `test/background-fill.test.js`,
-  `test/priority-map-download.test.js`, `test/read-window.test.js`,
-  `test/piece-reader.test.js`, `test/dead-torrent-handle.test.js`.
-- **A CHANGELOG entry is part of the change**, written at the version
-  `npm run patch` will produce — the current `package.json` version plus one
-  patch. Never edit the version in `package.json` by hand.
-- **Bumping the proxy means bumping the addon**, `ha-addon/torrent_tv_proxy/config.yaml`,
-  with its own CHANGELOG entry, and the proxy is published FIRST.
-- **Publishing is pre-authorised.** Destructive actions are not.
-- Refer to work by what it is, never by a list number.
-
-## State of the tree as measured, 2026-09-12
-
-- `node --check` passes on the three touched source files.
-- Biome is clean over `services/`, `test/` and `routes/` — 282 files.
-- Tests of the changed files: 131 of 131 pass.
-- Nothing has been verified in the field; the released proxy is 2.83.3 with
-  addon 0.74.0 on the host.
-
-None of that argues for keeping the work. It is recorded so that a failure
-after the removal is not mistaken for a failure that was already there.

package/research/piece-withdrawn-but-still-claimed-2026-09-12.md

@@ -1,175 +0,0 @@
-# A film played 80 seconds and then stood still for 92 minutes — 2026-09-12
-
-Proxy 2.83.4, addon 0.74.1, one viewer, `Reacher.S04E07.1080p.rus.LostFilm.TV.mkv`
-(2 363 497 962 bytes). Reported by the user as "the film only managed to play
-one minute nineteen seconds".
-
-Every claim below is tagged by where it comes from: **[log]** read out of a
-captured log, **[code]** read out of the source, **[measured]** computed from
-the captured logs, **[derived]** reasoned from two of the above.
-
-## 1. What the viewer saw
-
-**[log, browser]** Every one of the 1112 `decode` readings in the captured
-window is identical: `t=80.0s size=1920x1080 frames=1920 dropped=0
-readyState=2`. 1920 frames at 24 fps is 80.0 s, so the picture advanced 80
-seconds and then never moved again. The page stayed open until 18:52.
-
-**[log, browser]** From then on the player asked for one segment and was
-refused, about once a minute for 92 minutes:
-
-```
-18:30:47 non-fatal: fragLoadError currentTime=79.97 msReadyState=open
-         frag=segment-00008.mp4 sn=8 action=5 error=Error: HTTP Error 503 …
-18:41:15 fatal:     fragLoadError … sn=8 … HTTP Error 503
-18:41:17 recovered fatal networkError, resuming at 80.0s
-```
-
-`msReadyState=open` throughout, so this is **not** the closed-MediaSource
-failure of item 86. **[log]** The transport was healthy the whole time —
-`rtt=4ms`, `state=connected ice=connected`, every counter advancing — so it is
-not item 10 either.
-
-## 2. What the proxy answered, and why
-
-**[code]** 503 in `routes/transcode/session-file/get.js:143` is the
-`warming-up` branch: the segment is still being produced. It was never produced.
-
-**[log]** 239 times:
-
-```
-transcode 17ec5953 holding segment-00008.mp4: the file is not on disk
-  (runs from #8, viewer at #8, encoder alive, index #8, produced 0.0s at 2.23x
-   — the encoder has not made it)
-[hold] segment-00008.mp4 warming-up after 60400ms (the map wants it now, rank 69 of 69)
-```
-
-**[log]** The encoder could not open its input, 5712 times:
-
-```
-encode-run #8..#247 lost its input ([http @ …] Error reading HTTP response: End of file)
-Error opening input file http://127.0.0.1:9090/stream?sourceKey=94dda59f…   (8514×)
-Error opening input files: End of file                                       (5712×)
-```
-
-**[log]** And `/stream` said exactly what was wrong, 2884 times:
-
-```
-stream: read of "Reacher.S04E07.1080p.rus.LostFilm.TV.mkv" bytes 0-2363497961
-  ended after 0 of 2363497962 bytes: Piece 0 is verified but absent from the store.
-```
-
-Zero bytes of 2.36 GB. ffmpeg reads an empty body as the end of the file.
-
-## 3. The cause
-
-**[log]** The torrent believed it had the whole file:
-
-```
-[stats] 94dda59f 5d276be5 peers=54 connected … file=100.0% header=8388608/8388608B
-```
-
-**[log]** The store did not:
-
-```
-piece-store "Reacher.S04E07…": resident=27/42 (108MB of 168MB allowed)
-  committed=108MB blocks=27 on-disk=26MB pinned=0 spilled=7
-  reads=5932 (73.8% from memory) spills=571 revivals=41
-```
-
-**[measured]** 571 spills at a 4 MB piece is about 2284 MB written to disk;
-26 MB remained. So roughly 565 pieces had been removed. **[log]** It was not
-the disk cap: `disk: 93634MB free; spilled pieces 26MB of 46656MB` — the
-ceiling never came near binding, and 93 GB were free.
-
-**[code]** That leaves exactly one remover: `PieceDiskStore.forgetBehind`,
-called from `SharedPieceStore.reviseSpillCeiling`, which drops every piece
-lying behind the earliest read head. **[log]** The encoder had reached
-`proxyProcessed=725.643`, twelve minutes of film, so piece 0 — the start of the
-file and its Matroska header — was far behind every reader and was dropped.
-That is the rule working as designed.
-
-**[code]** `piece-reader.js:151` then asks `torrent.bitfield.get(index)`. The
-library still answered yes, because it had downloaded and hashed that piece
-once. **Nothing ever told it otherwise:** `bitfield.set` does not occur
-anywhere in `services/piece-store/`, `services/torrent-pool.js` or
-`services/torrent-worker/`. So the read concluded the piece was had, asked the
-store, was told it was absent, and threw.
-
-**[derived]** And it was never fetched again, because the library does not
-download a piece it believes it owns. The comment on `forgetBehind` states the
-bargain in as many words — "a seek back re-downloads it, which is the same
-bargain this tier makes whenever it drops a piece for room" — and that bargain
-had never once been honoured.
-
-**[derived]** The trigger is ordinary: an encoder restart re-opens its input at
-byte 0 (`bytes 0-2363497961` in the log), which is precisely the region
-`forgetBehind` removes first.
-
-This is the "un-have problem" the parent `CLAUDE.md` names in the Level 2 disk
-design — "mark the piece incomplete in the completion store → it re-downloads on
-the next read". The eviction shipped; the un-have did not.
-
-## 4. Two amplifiers, each a defect of its own
-
-### The delay after a lost input did not bind
-
-**[code]** `hls-session-manager.js` timed a retry against the DEAD RUN, doubling
-2 s → 15 s. **[code]** `EncodeRun.isAlive` is false in `RETRY_WAIT`, and the
-orchestrator plans from live runs only — so the plan saw the stretch as free and
-placed a new run at once, on every event.
-
-**[measured]** 2432 `restart for` lines in 23 minutes: one every 0.57 s, for 61
-minutes, while the delay printed `retrying in 15s`. The comment beside that
-timer predicted this exactly and the code did not prevent it.
-
-### The log destroyed the record of its own failure
-
-**[measured]** 76 385 lines in 23 minutes and 159 000 in the previous 38 — about
-55 lines a second, of which **52 567 of 76 385 (68.8 %) are byte-identical
-repeats**. **[code]** `MAX_FILE_BYTES` was 32 MiB with one previous turn kept, so
-the file turned over twice inside the session: 61 minutes of 92 survived, and the
-onset — everything before 17:51 — was overwritten by the second rotation and is
-gone. **[log]** `/data` had 91.4 GB free.
-
-## 5. What was built (proxy 2.83.5)
-
-1. the store announces when it can no longer produce a piece at all — not
-   resident, not on disk, not in a file held whole — and the pool withdraws the
-   library's claim with `_markUnverified`. The disk tier states only its own
-   loss; the store decides whether that is a loss;
-2. a read whose piece is withdrawn under it goes back one step and takes the
-   whole ordinary path again instead of throwing. Once per piece;
-3. the delay lives in the orchestrator, per output, and the plan places nothing
-   there until it is over — unless something on that output is still producing.
-   It is lifted only by a run that actually produced;
-4. an established fact is logged once, then at doubling intervals to a minute,
-   saying how many were held back. Matched verbatim; digits are deliberately not
-   normalised, because that would merge the memory series;
-5. the log file may reach 1 GB before turning over.
-
-## 6. What this does NOT establish
-
-1. **Nothing here has been seen in the field.** The next session is the proof.
-   What should appear: `withdrawn=` climbing on the piece-store line while reads
-   keep succeeding, `its input was not there (attempt N) — placing nothing for
-   Xs`, and `[said N more time(s) …]` instead of a flood. What should disappear:
-   `Piece N is verified but absent from the store`.
-2. **The onset was not read.** Both log turns begin with the failure already
-   established, so which piece failed FIRST, and whether the encoder's first
-   input loss had the same cause, is not known. The mechanism is established;
-   its first instance is not.
-3. **A consequence, stated rather than discovered later:** a torrent whose
-   pieces have been withdrawn is no longer `done`, so a film watched to the end
-   is not assembled into a whole file. That is the honest state — those bytes
-   are not here — and the previous behaviour was worse than it looked, since the
-   assembly reads the file through the store and would have waited for pieces
-   the library wrongly believed it had. What is NOT measured is how often a film
-   now fails to be assembled, and whether keeping the pieces of a nearly-finished
-   file would be worth the disk.
-4. **The re-download cost is not measured.** A seek back past the read heads now
-   waits for pieces to be fetched again instead of failing. How long that takes
-   on a real swarm, and whether the viewer notices, needs a session.
-5. **`peers=54 connected of -4599 known (…, -1128 queued)`** — the negative
-   figures come from WebTorrent's own `_peersLength`/`_numQueued`, read for the
-   log only. Not investigated, not touched.

package/research/preset-benchmark-size-scaling-2026-08-22.md

@@ -1,55 +0,0 @@
-# Does the preset benchmark's pixels/sec figure hold at a different size? (2026-08-22)
-
-Roadmap item 4(e): the software-preset benchmark (`benchmarkSoftwarePresets`,
-`services/hwaccel.js`) measures encoder throughput at one fixed reference size —
-640×360 — and every later use of that figure (deciding which quality rungs this
-host can sustain) scales it by pixel count, assuming cost per pixel is constant
-regardless of frame size. This was never checked against a second size.
-
-## Measurement
-
-Same clip (`cal-h264-1080-hi.mp4`), same `libx264` presets, same measurement
-method as the shipped benchmark (slope between two `-progress` reports,
-excluding startup) — run once at the existing 640×360 reference and once at
-1280×720 (4× the pixel count), on the developer's desktop:
-
-| preset    | 640×360        | 1280×720       | ratio (should be ~1.0) |
-|-----------|----------------|----------------|-------------------------|
-| ultrafast | 1322.8 Mpx/s   | 588.6 Mpx/s    | 0.445                   |
-| fast      | 176.6 Mpx/s    | 128.1 Mpx/s    | 0.725                   |
-
-Script: ad-hoc, not committed (reused the benchmark's own ffmpeg arguments at a
-second `-vf scale=`/`-s` size; available on request if this needs re-running).
-
-## Reading
-
-The assumption does not hold. Cost per pixel RISES with frame size on this
-host — by 2.25× for `ultrafast`, 1.38× for `fast`, at 4× the pixel count — and
-the effect is preset-dependent, not a single constant. A quality ladder priced
-from the 640×360 figure alone over-states what this host can sustain at 1080p,
-worse for the faster presets that the ladder falls back to under load.
-
-## Why this does not become a code change yet
-
-One host, one clip, two sizes. [[feedback_pool_diversity]] — a correction fitted
-to this desktop and applied to every proxy in the pool would be exactly the
-mistake that memory exists to prevent: the pool spans ARM boards (HA Yellow /
-CM4) with different cache sizes and memory bandwidth, where a size penalty of
-this shape could be smaller, larger, or absent. [[feedback_no_fudged_numbers]] —
-publishing 0.445/0.725 as universal constants is fabricating a number for hosts
-that were never measured.
-
-The benchmark already measures per-host (item 4(f), 4(h)); a size-scaling
-correction belongs there too — the benchmark itself gains a second, cheap
-measurement point (one preset, one second size) and derives its own exponent
-from that host's two readings, the same way `fitDecodeCost` derives its terms
-from clips rather than from a stated formula. That is the remaining work under
-item 4(e); this note is the measurement that justifies doing it, not the fix
-itself.
-
-## What is verified
-
-The measurement method matches the shipped benchmark exactly (real footage,
-raw frames decoded once, slope between two progress reports) — the only
-variable changed was the target size, so this is not comparing two different
-methodologies.