jellybit/openspec/specs/download-tracking/spec.md

# download-tracking Specification

## Purpose
Отслеживание скачивания и прямой путь машины состояний загрузки: поллинг
qBittorrent и сопоставление его состояний (downloading → completed; готовность
только когда файлы на месте), таймауты-предохранители (`magnet_timeout`/
`stuck_after`), ошибка qBit → failed, усыновление раздач по категории/тегу и
переходы под per-download блокировкой. Сверка уже разложенного с реальностью —
в `state-reconciliation`.
## Requirements
### Requirement: Поллинг qBittorrent и сопоставление состояний

Worker SHALL периодически (`worker.poll_interval`, дефолт 5 с) опрашивать
qBittorrent и сопоставлять его состояния раздачи с состоянием загрузки в БД.
Готовые к раскладке состояния (`uploading`/`stalledUP`/`pausedUP`/`stoppedUP`/
`queuedUP`/`forcedUP`, с учётом различий имён между qBit v4 и v5) SHALL переводить
загрузку в `completed`. Ещё качающиеся состояния (`downloading`/`stalledDL`/
`metaDL`/…) SHALL оставлять её в `downloading`.

#### Scenario: Раздача завершилась

- **GIVEN** загрузка в `downloading`
- **WHEN** qBittorrent сообщает состояние `stalledUP` и файлы на месте
- **THEN** загрузка переходит в `completed`

### Requirement: Готовность только когда файлы на месте

Переходные состояния qBittorrent система SHALL трактовать как «ждём»
(`moving`/`checkingUP`/`checkingResumeData`/`allocating`): оставаться в
`downloading` и НЕ объявлять готовность, даже если выставлены флаги `UP`, пока
qBit не завершит перенос/проверку. Финальные пути файлов система SHALL брать из
API после завершения переноса.

#### Scenario: Ждём завершения переноса

- **GIVEN** загрузка, у которой qBittorrent в состоянии `moving`
- **WHEN** идёт тик поллинга
- **THEN** загрузка остаётся в `downloading`, готовность не объявляется

### Requirement: Таймауты-предохранители downloading

Система SHALL переводить `metaDL`/`forcedMetaDL` дольше `magnet_timeout` (дефолт
`24h`, редкий предохранитель) в `failed` (`error_code` `magnet_timeout`), а
`stalledDL` дольше `stuck_after` — в `stuck` (`error_code`
`stalled`). Возраст система SHALL считать от времени добавления в qBittorrent
(`added_on`), а не от создания задачи, чтобы базис переживал retry и усыновление.
Долгий `metaDL` система НЕ SHALL убивать агрессивно (медленные трекеры — норма).

#### Scenario: Завис на метаданных дольше таймаута

- **GIVEN** раздача в `metaDL` дольше `magnet_timeout` от `added_on`
- **WHEN** идёт тик поллинга
- **THEN** загрузка переходит в `failed` с `error_code` `magnet_timeout`

### Requirement: Ошибка qBittorrent переводит в failed

Состояния `error`/`missingFiles` система SHALL трактовать как настоящий провал и
переводить загрузку в `failed` (`error_code` `qbit_error`) — в отличие от
таймаутов-предохранителей, такой провал сверкой не воскрешается.

#### Scenario: qBit сообщает об ошибке

- **GIVEN** раздача в состоянии `missingFiles`
- **WHEN** идёт тик поллинга
- **THEN** загрузка переходит в `failed` с `error_code` `qbit_error`

### Requirement: Усыновление раздач по категории или тегу

Worker SHALL периодически сверять раздачи qBittorrent с БД и **усыновлять** те, у
которых наша категория (`qbittorrent.category`) ИЛИ тег (`qbittorrent.tag`), а
записи в БД ещё нет, заводя для них загрузку в состоянии `downloading`. Категория
ставится на добавляемые нами раздачи (push); тег позволяет подхватить уже
существующую раздачу (pull), не трогая её категорию и файлы.

#### Scenario: Подхват существующей раздачи по тегу

- **GIVEN** в qBittorrent есть раздача с тегом `qbittorrent.tag`, которой нет в БД
- **WHEN** worker сверяет qBittorrent с БД
- **THEN** для раздачи заводится загрузка в состоянии `downloading`

### Requirement: Переходы состояний сериализуются воркером

Все переходы состояний загрузки SHALL сериализоваться worker'ом под единой
блокировкой (поллинг-цикл и команды всех транспортов проходят через неё), чтобы
два источника перехода не гонялись за одно состояние. Состояние SHALL быть
персистентным в SQLite; активность загрузки SHALL выводиться только из `state`,
без отдельного флага.

#### Scenario: Команды сериализуются

- **GIVEN** две одновременные команды к одной загрузке из разных транспортов
- **WHEN** они обрабатываются
- **THEN** переходы применяются последовательно под блокировкой, без гонки

### Requirement: Добавление пойманной загрузки в qBittorrent

Worker SHALL периодически (в поллинг-цикле, под единой блокировкой переходов)
подхватывать загрузки в состоянии `catched` и для каждой (кроме случая уже
присутствующего в qBittorrent торрента, см. ниже): вывести отображаемое имя из
контекста (см. `ingest` «Отображаемое имя торрента из контекста»), добавить
источник в qBittorrent (категория `qbittorrent.category`, savepath, `rename`) и
перевести загрузку `catched → downloading`. Отдельного состояния между `catched`
и `downloading` быть SHALL NOT — успешный `add` сразу переводит в `downloading`
(которое и означает «в qBit, возможно `metaDL`»).

Перед добавлением worker SHALL проверять, **присутствует ли торрент загрузки уже
в qBittorrent** (по любому из её infohash), опираясь на листинг раздач того же
тика. Если торрент уже присутствует, worker SHALL **усыновить** его: перевести
загрузку `catched → downloading` **без повторного `add`** и без вывода имени
через LLM (`display_name` берётся из имени присутствующей раздачи). Повторный
`add` здесь не нужен и вреден — qBittorrent отверг бы дубль (напр. `409
Conflict`), и загрузка зациклилась бы на ретраях. Усыновлённая раздача дальше
идёт обычным путём отслеживания и раскладки. Проверка присутствия SHALL
выполняться **до вывода отображаемого имени**, чтобы не тратить LLM-вызов на
загрузку, которую добавлять не требуется.

Инвариант приёма («одна активная загрузка на infohash», см. `ingest`) гарантирует,
что до этого шага доходит лишь загрузка, для которой в jellybit НЕТ другой
активной задачи; поэтому присутствие торрента в qBittorrent worker трактует как
«усыновить и разложить», а не как конфликт с чужой задачей.

Если листинг раздач qBittorrent недоступен (сетевой сбой), worker пойманную
загрузку в этот тик трогать SHALL NOT (ни `add`, ни namer) и повторить на
следующем; устойчивая недоступность отсекается предохранителем `catch_timeout`
(см. «Предохранитель зависшего catched»).

Добавление в qBittorrent worker SHALL выполнять **по типу источника**
(`source_type`):

- Для `magnet`/`url` — передавать `source_ref` как ссылку (`urls` API
  `/torrents/add`); подсказку отображаемого имени брать из полей самой ссылки.
- Для `torrent` — загружать сохранённые байты `.torrent` (привязанные к
  загрузке при приёме) и передавать их **файлом** (`torrents` API
  `/torrents/add`), НЕ как ссылку; подсказку отображаемого имени брать из
  метаданных торрента (имя раздачи). Добавление байтами SHALL сохранять полные
  метаданные (qBittorrent стартует без докачки), поэтому воскрешать раздачу по
  magnet-хешу вместо файла система SHALL NOT.

`source_type` для выбора способа добавления worker SHALL перечитывать **под
блокировкой переходов** непосредственно перед добавлением (а не полагаться на
снимок, снятый ранее вне блокировки): иначе при точном оверлапе тика с апгрейдом
пойманной magnet-задачи до `.torrent` (см. `ingest`) воркер добавил бы magnet из
устаревшего снимка, хотя БД уже `torrent`.

Неуспешный `add` (qBittorrent временно отверг/недоступен) SHALL оставлять
загрузку в `catched` для повторной попытки на следующем тике; переход в
терминальное состояние по единичному сбою происходить SHALL NOT (ретраи —
естественными тиками поллинга, отсечка — `catch_timeout`).

Медленные вызовы (вывод имени через LLM, `qbt.Add`) SHALL выполняться **вне**
блокировки сериализации переходов, чтобы не задерживать команды транспортов и
поллинг. Под блокировкой сериализуется только **запись перехода** `catched →
downloading` (см. «Переходы состояний сериализуются воркером»), с ре-валидацией,
что загрузка всё ещё в `catched` (иначе переход отклоняется — например, при
параллельной отмене).

Вывод имени (LLM) занимает секунды и идёт вне блокировки, поэтому загрузку могут
отменить (`catched → cancelled`) в это окно. Чтобы отменённая задача не оставила
неуправляемый торрент в qBittorrent, worker SHALL применять комбинированную
защиту. Порядок шагов относительно блокировки переходов: `[под блокировкой]`
re-read состояния → `[вне блокировки]` свежий листинг присутствия → `[вне
блокировки]` `add` → `[под блокировкой]` запись перехода и (при неуспехе) re-read
состояния для решения об уборке → `[вне блокировки]` удаление. Сетевые вызовы
(листинг, `add`, удаление) под блокировкой держаться SHALL NOT.

- **Re-read состояния перед `add`.** Непосредственно перед `qbt.Add` (после
  вывода имени) worker SHALL под блокировкой переходов перечитать запись и, если
  она уже НЕ в `catched` (отменена), НЕ вызывать `add` и загрузку в этот тик
  пропустить. Это сужает окно гонки до промежутка между re-read и записью
  перехода.

- **Подтверждение отсутствия торрента перед `add`.** Непосредственно перед `add`
  worker SHALL свежим листингом раздач qBittorrent подтвердить, что раздачи ни с
  одним из infohash загрузки ещё НЕТ. Если этот листинг **не удался** (сетевой
  сбой), worker `add` выполнять SHALL NOT и загрузку в этот тик пропустить (повтор
  на следующем): без подтверждённого отсутствия признак «своё/чужое» неизвестен,
  и последующее удаление-с-данными было бы небезопасным. Если торрент уже
  присутствует (внешний клиент/пользователь добавил тот же infohash в окно
  гонки), worker `add` выполнять SHALL NOT и загрузку в этот тик пропустить — на
  следующем тике её усыновит ветка «уже присутствует». Подтверждённое отсутствие
  непосредственно-перед-`add` SHALL служить признаком того, что торрент,
  оказавшийся под этим infohash сразу после `add`, создан именно этим `add` (наш
  артефакт), а не пред-существовал.

- **Уборка добавленного торрента при отмене в окне после `add`.** Если `add`
  прошёл успешно, а последующая запись перехода `PromoteCatched` не применилась,
  worker SHALL принимать решение об уборке по **свежему re-read состояния под
  блокировкой**, а не по факту ошибки промоушена: неуспех промоушена бывает и
  из-за отмены (`state` уже не `catched`), и из-за транзиентного сбоя хранилища
  (`state` всё ещё `catched`, задача жива). Только при подтверждённом `state !=
  catched` worker SHALL удалить только что добавленный торрент из qBittorrent
  **вместе с его данными** (`deleteFiles = true`) по infohash загрузки. Если
  повторное чтение показало `state == catched` (транзиентный сбой) либо само не
  удалось, worker торрент удалять SHALL NOT — переход доводится на следующем тике
  усыновлением присутствующей (нашей) раздачи. Удаление SHALL идти через API
  qBittorrent (`torrents/delete`), не прямыми fs-операциями. Это легитимная уборка
  **собственного** артефакта, а не пользовательских данных: инвариант «источник
  неприкосновенен» защищает существующие раздачи/файлы пользователя под
  `paths.downloads`, а здесь удаляется торрент, который сам worker добавил
  секундами ранее — уже после намерения отмены. Состояние отменённой задачи
  (`cancelled`) уборка трогать SHALL NOT; неуспех удаления SHALL логироваться
  (торрент временно остаётся, повторная авто-уборка не требуется).

- **Негативный инвариант (удаляем только своё).** Удаление-с-данными допустимо
  ТОЛЬКО для торрента, который worker создал именно этим `add`. Торрент, который
  присутствовал в qBittorrent ДО нашего `add` (пользователь уже раздавал тот же
  infohash / внешний торрент с тем же хешем), удалять с данными worker SHALL NOT —
  иначе снёс бы чужие данные в нарушение инварианта. Гарантию обеспечивает
  подтверждение отсутствия перед `add`: путь уборки достижим только тогда, когда
  отсутствие infohash было подтверждено непосредственно перед `add`; при
  обнаруженном присутствии (или недоступном листинге) `add` не выполняется вовсе.

Записи об этом пути (торрент оставлен после отмены → удаляем; факт удаления) worker
SHALL логировать на уровне `WARN` с корреляцией по `download_id`/`infohash` и без
секретов; неуспех удаления — на `ERROR`.

#### Scenario: Пойманная magnet-загрузка добавляется в qBittorrent

- **GIVEN** загрузка в состоянии `catched` с `source_type = magnet`, торрента
  ещё нет в qBittorrent
- **WHEN** worker обрабатывает тик
- **THEN** выводится отображаемое имя, ссылка добавляется в qBittorrent с
  нашей категорией и `rename`
- **AND** загрузка переходит в `downloading`

#### Scenario: Пойманная .torrent-загрузка добавляется файлом

- **GIVEN** загрузка в состоянии `catched` с `source_type = torrent` и
  сохранёнными байтами файла, торрента ещё нет в qBittorrent
- **WHEN** worker обрабатывает тик
- **THEN** сохранённые байты добавляются в qBittorrent файлом (`torrents`), с
  нашей категорией и `rename`, без обращения к magnet-хешу
- **AND** загрузка переходит в `downloading`

#### Scenario: Торрент уже присутствует в qBittorrent — усыновление без add

- **GIVEN** загрузка в состоянии `catched`, торрент которой уже присутствует в
  qBittorrent (добавлен ранее вручную/другим клиентом либо `add` прошёл на
  прошлом тике, а запись перехода не удалась)
- **WHEN** worker обрабатывает тик
- **THEN** worker НЕ вызывает `qbt.Add` и НЕ выводит отображаемое имя через LLM
- **AND** `display_name` записывается из имени присутствующей раздачи
- **AND** загрузка переходит в `downloading` и идёт обычным путём к раскладке

#### Scenario: qBittorrent недоступен при проверке присутствия — повтор

- **GIVEN** загрузка в `catched`, листинг раздач qBittorrent не удался
- **WHEN** worker обрабатывает тик
- **THEN** worker НЕ вызывает namer и НЕ добавляет источник
- **AND** загрузка остаётся в `catched` и попытка повторяется на следующем тике

#### Scenario: Временный сбой добавления — повтор

- **GIVEN** загрузка в `catched`, торрента в qBittorrent нет, но `add` не удался
- **WHEN** worker пытается добавить источник и `add` возвращает ошибку
- **THEN** загрузка остаётся в `catched`
- **AND** на следующем тике попытка добавления повторяется

#### Scenario: Свежий листинг перед add недоступен — повтор

- **GIVEN** загрузка в `catched`, торрента в снимке тика нет, имя выведено
- **WHEN** свежий листинг присутствия непосредственно перед `add` не удался
  (сетевой сбой)
- **THEN** worker `add` НЕ вызывает (отсутствие infohash не подтверждено)
- **AND** загрузка остаётся в `catched`, попытка повторяется на следующем тике

#### Scenario: Отмена до add — источник не добавляется

- **GIVEN** загрузка в `catched`, worker выводит отображаемое имя вне блокировки
- **WHEN** параллельно приходит команда отмены (`catched → cancelled`) во время
  вывода имени, а затем worker перечитывает состояние перед `add`
- **THEN** re-read видит, что загрузка уже не в `catched`, и `qbt.Add` НЕ
  вызывается
- **AND** источник в qBittorrent не добавляется, задача остаётся `cancelled`

#### Scenario: Отмена в окне после add — добавленный торрент удаляется с данными

- **GIVEN** загрузка в `catched`, отсутствие её infohash в qBittorrent
  подтверждено перед `add`, и `add` прошёл успешно
- **WHEN** отмена (`catched → cancelled`) приходит в окне между `add` и записью
  перехода, из-за чего запись перехода не применяется, а re-read состояния под
  блокировкой показывает `state != catched`
- **THEN** worker удаляет только что добавленный торрент из qBittorrent вместе с
  его данными (`deleteFiles = true`) по infohash загрузки
- **AND** пишет `WARN` о том, что торрент оставлен после отмены и удалён
- **AND** состояние задачи остаётся `cancelled`

#### Scenario: Сбой записи перехода без отмены — торрент не удаляется

- **GIVEN** загрузка в `catched`, `add` прошёл успешно, но запись перехода
  `PromoteCatched` вернула ошибку из-за транзиентного сбоя хранилища
- **WHEN** re-read состояния под блокировкой показывает, что загрузка всё ещё в
  `catched` (отмены не было)
- **THEN** worker торрент из qBittorrent НЕ удаляет (это наш живой торрент)
- **AND** переход доводится на следующем тике усыновлением присутствующей раздачи

#### Scenario: Пред-существующий торрент не удаляется с данными

- **GIVEN** загрузка в `catched`, чей infohash уже присутствует в qBittorrent к
  моменту проверки перед `add` (внешний торрент/раздача пользователя с тем же
  хешем)
- **WHEN** worker обрабатывает тик и параллельно приходит отмена
- **THEN** worker `add` НЕ выполняет и торрент с данными НЕ удаляет (чужие данные
  неприкосновенны)
- **AND** загрузка пропускается в этот тик (усыновление присутствующей раздачи —
  на следующем тике, если задача ещё активна)

### Requirement: Предохранитель зависшего catched

Система SHALL переводить загрузку, задержавшуюся в `catched` дольше
`catch_timeout` (конфигурируемый предохранитель, дефолт консервативный), в
`failed` (`error_code` `qbit_add`) и уведомлять автора. Возраст SHALL считать
от времени попадания в `catched` (создания загрузки). Предохранитель —
редкий страховочный механизм на случай устойчивой недоступности qBittorrent, а
не штатный путь.

#### Scenario: catched висит дольше таймаута

- **GIVEN** загрузка в `catched` дольше `catch_timeout`
- **WHEN** идёт тик поллинга
- **THEN** загрузка переходит в `failed` с `error_code` `qbit_add`
- **AND** автор загрузки уведомляется

### Requirement: catched не считается пропажей раздачи

Система SHALL исключать состояние `catched` из проверок «раздача не найдена в
qBittorrent» — как в поллинге активных загрузок, так и в сверке рассинхрона
(`state-reconciliation`). У пойманной загрузки раздачи в qBittorrent ещё нет по
дизайну, поэтому её отсутствие система SHALL NOT трактовать как рассинхрон,
`orphaned` или пропажу источника.

#### Scenario: Отсутствие раздачи у catched — не рассинхрон

- **GIVEN** загрузка в `catched` (раздачи в qBittorrent ещё нет)
- **WHEN** идёт тик поллинга и сверки
- **THEN** загрузка не считается пропавшей/рассинхронизированной и остаётся в
  `catched` (до добавления воркером или срабатывания `catch_timeout`)

### Requirement: Легальность переходов задаётся декларативным графом

Множество легальных переходов машины состояний загрузки SHALL быть объявлено
декларативно в едином месте (`internal/store`) как отображение `from →
{разрешённые to}`, покрывающее все переходы, которые worker выполняет по всем
capability (прямой путь, `state-reconciliation`, `review`). Этот граф SHALL быть
единственным источником истины о легальности рёбер.

Запись состояния (`setState`, общая основа `SetDownloadState` и
`ActivateIfNoOtherActive`) SHALL применять переход, только если он либо объявлен
ребром графа, либо является идемпотентным самопереходом (`from == to`, переустановка
того же состояния — например, повторная запись ошибки). Переход, не удовлетворяющий
ни одному из условий, запись SHALL отклонять (0 строк UPDATE → ошибка), НЕ применяя
его.

Гейт графа SHALL быть **ортогонален** остальным гардам записи и НЕ SHALL их ослаблять:
существующий запрет молча оживить терминальную задачу (переход из терминального
состояния разрешён только через `ActivateIfNoOtherActive` с проверкой владения
хешами) и инвариант «не более одной активной загрузки на infohash» сохраняются. Как
следствие, ребро из терминального состояния (напр. `failed → downloading` при retry)
SHALL проходить только revive-путём (`ActivateIfNoOtherActive`) и SHALL отклоняться
обычным `SetDownloadState`.

Граф SHALL быть надмножеством всех переходов, которые worker уже выполняет: введение
гейта НЕ SHALL менять поведение существующих легальных переходов.

#### Scenario: Объявленный переход применяется

- **GIVEN** загрузка в состоянии `downloading`
- **WHEN** worker записывает переход `downloading → completed` (объявленное ребро)
- **THEN** состояние становится `completed`

#### Scenario: Необъявленный переход отклоняется

- **GIVEN** загрузка в состоянии `review`
- **WHEN** делается попытка записать переход `review → done` (ребра в графе нет)
- **THEN** запись отклоняется с ошибкой, состояние остаётся `review`

#### Scenario: Идемпотентная переустановка состояния разрешена

- **GIVEN** загрузка в состоянии `deferred`
- **WHEN** записывается переход `deferred → deferred` (самопереход)
- **THEN** запись проходит, состояние остаётся `deferred`

#### Scenario: Ребро из терминального состояния только через revive

- **GIVEN** загрузка в терминальном состоянии `failed`
- **WHEN** переход `failed → downloading` делается обычным `SetDownloadState`
- **THEN** запись отклоняется (терминальную задачу нельзя оживить мимо гарда владения)
- **AND** тот же переход через `ActivateIfNoOtherActive` (при свободном infohash)
  проходит

### Requirement: Пропажа источника у активной загрузки

Поллинг активных загрузок (`downloading`) SHALL обнаруживать пропажу источника:
если раздача, совпадающая с любым из известных хешей загрузки, отсутствует в
выдаче qBittorrent, система SHALL применять **тот же дебаунс пропажи источника**,
что и сверка рассинхрона (счётчик `source_miss_count`, порог
`[worker].source_missing_threshold`; см. `state-reconciliation` «Дебаунс пропажи
источника»). Любое обнаружение раздачи SHALL сбрасывать счётчик.

После `N` подряд идущих тиков без раздачи (`N =
[worker].source_missing_threshold`) система SHALL переводить загрузку
`downloading → failed` с `error_code` `source_gone` и уведомлять автора. До
достижения порога загрузка SHALL оставаться в `downloading` (транзиентная
недоступность qBittorrent, например рестарт демона, не должна ронять задачу).

`source_gone` система SHALL трактовать как отдельную причину, отличную от
`qbit_error` (реальная ошибка qBittorrent) и от `magnet_timeout`/`stalled` (наша
нетерпеливость). Восстановлению сверкой (`reconcileRecovery`) `source_gone`
подлежать SHALL NOT — удаление источника из qBittorrent намеренно, молча
воскрешать задачу нельзя. Задача SHALL оставаться штатно восстановимой вручную
(`Retry` заново отдаёт сохранённый источник в qBittorrent).

Состояние `catched` этим правилом затрагиваться SHALL NOT: у пойманной загрузки
раздачи в qBittorrent ещё нет по дизайну (см. «catched не считается пропажей
раздачи»), а цикл активных загрузок листает только `downloading`.

#### Scenario: Источник пропал у активной загрузки дольше порога

- **GIVEN** загрузка в `downloading`, чья раздача удалена из qBittorrent
- **WHEN** раздача отсутствует `source_missing_threshold` подряд идущих тиков
- **THEN** загрузка переходит в `failed` с `error_code` `source_gone`
- **AND** автор загрузки уведомляется

#### Scenario: Кратковременная пропажа источника не роняет задачу

- **GIVEN** загрузка в `downloading`
- **WHEN** раздача отсутствует в qBittorrent меньше `source_missing_threshold`
  тиков подряд
- **THEN** загрузка остаётся в `downloading`

#### Scenario: Возврат раздачи сбрасывает счётчик

- **GIVEN** загрузка в `downloading` с накопленными промахами источника (меньше
  порога)
- **WHEN** раздача снова обнаружена в qBittorrent
- **THEN** счётчик промахов сбрасывается в ноль и загрузка ведётся обычной
  сверкой состояния

#### Scenario: source_gone не воскрешается сверкой

- **GIVEN** загрузка в `failed` с `error_code` `source_gone`
- **WHEN** её раздача снова появляется в qBittorrent и продвигается
- **THEN** сверка восстановления её не трогает — задача остаётся в `failed` до
  ручного `Retry`