jellybit/openspec/changes/archive/2026-07-08-retry-stall-basis/specs/state-reconciliation/spec.md

MODIFIED Requirements

Requirement: Восстановление зависшей загрузки при оживлении источника

Система SHALL возвращать в активный поток задачу, упавшую из-за нашей нетерпеливости (failed/magnet_timeout или stuck/stalled), если её источник в qBittorrent жив и продвинулся: переход выводится из текущего состояния торрента так же, как при штатной сверке загрузки (uploading/stalledUP/… → completed; downloading/metaDL/… → downloading). Восстановление SHALL опираться на фактическое состояние торрента в qBittorrent, а не на время с момента создания записи.

После возврата в любое нетерминальное состояние (downloading или completed) повторный приём того же infohash SHALL снова дедуплицироваться на эту задачу: активность задачи выводится только из её state, отдельный восстанавливаемый ключ идемпотентности отсутствует. Если за время простоя в failed/stuck тем же infohash (любым из хешей задачи) уже завладела другая активная задача (новый приём, пока эта лежала упавшей), система SHALL NOT воскрешать упавшую задачу и SHALL оставить её в failed/stuck, сохраняя инвариант «не более одной активной задачи на infohash».

magnet_timeout/stalled SHALL быть редким страховочным исходом, а не рабочим механизмом. Две страховочные меры при этом РАЗНЫЕ: magnet_timeout SHALL мериться по возрасту торрента (время от добавления в qBittorrent, added_on, с фолбэком на created_at задачи), а stuck_after — по длительности простоя (время от last_activity qBittorrent — момента последнего движения данных), а НЕ по возрасту. Пока торрент в metaDL/forcedMetaDL или иным образом прогрессирует в пределах страховочного таймаута, задача в failed/stuck из-за него оказаться SHALL NOT; в частности, торрент со свежим last_activity в stuck система пометить SHALL NOT, даже если его общий возраст превышает stuck_after (см. требование о терпеливости к долгим метаданным и меры таймаутов в docs/specs/workflow.md).

Scenario: Метаданные пришли после magnet_timeout

• GIVEN задача в failed с error_code magnet_timeout, а её торрент в qBittorrent уже получил метаданные и качается (downloading)
• WHEN срабатывает фоновая сверка
• THEN задача возвращается в downloading
• AND повторный приём того же infohash снова дедуплицируется на неё

Scenario: Торрент уже завершился, пока задача была в failed

• GIVEN задача в failed с error_code magnet_timeout, а её торрент в qBittorrent уже готов к раскладке (uploading/stalledUP)
• WHEN срабатывает фоновая сверка
• THEN задача переходит в completed и продолжает обычный поток (распознавание/раскладка)

Scenario: Источник так и не ожил — состояние не меняется

• GIVEN задача в failed с error_code magnet_timeout, а её торрент всё ещё висит в metaDL без метаданных (или отсутствует в qBittorrent)
• WHEN срабатывает фоновая сверка
• THEN задача остаётся в failed

Scenario: infohash уже занят другой активной задачей

• GIVEN задача #1 в failed/magnet_timeout, а тем же infohash уже владеет другая активная задача #2 (приём повторили, пока #1 лежала упавшей)
• WHEN источник ожил (торрент получил метаданные или готов) и сверка пытается воскресить #1
• THEN #1 остаётся в failed (восстановление не выполняется)
• AND активной по этому infohash остаётся #2

Scenario: Долго качавшийся торрент на миг зашёл в stalledDL

• GIVEN торрент качался часами и двигал данные только что (свежий last_activity), но на текущем тике qBittorrent показывает его stalledDL
• WHEN worker проверяет таймаут зависания
• THEN задача остаётся в downloading (простой меньше stuck_after), несмотря на большой возраст торрента
• AND ложного stuck со «stalled for <возраст>» и уведомления о падении не возникает

Requirement: Ручной повтор зависшей/упавшей загрузки из транспортов

Система SHALL предоставлять пользователю команду повторной попытки (retry) для задач в failed/stuck из веб-UI и Telegram (не только через REST API). Retry SHALL переводить задачу обратно в downloading, не вызывая её немедленного повторного падения по таймауту: базис отсчёта таймаутов SHALL сбрасываться.

Сброс базиса система SHALL выполнять сохранением времени retry в поле задачи (retried_at, RFC 3339 UTC), которое приподнимает пол ОБОИХ страховочных мер (magnet_timeout по возрасту и stuck_after по простою): отсчёт ведётся от max(базис, retried_at). retried_at SHALL храниться в задаче (не в памяти процесса), чтобы сброс базиса пережил интервал поллинга и рестарт процесса. Благодаря этому даже живой, но давно добавленный либо давно простаивающий торрент после retry SHALL получать свежее окно и на ближайшем тике сверки падать снова SHALL NOT.

Если источник задачи уже жив и ЗДОРОВ в qBittorrent, retry SHALL перецепляться к существующему торренту, а не добавлять источник повторно вслепую. Если же живой торрент в состоянии ошибки qBittorrent (error/missingFiles), retry перецепляться к нему SHALL NOT (перецепка к сломанному торренту тут же вернула бы задачу в failed по сверке) и SHALL повторно отдать источник, как при отсутствии раздачи. Повторный Add выполняется, только когда раздачи в qBittorrent нет ЛИБО она сломана.

Повторный Add при retry система SHALL выполнять по типу источника (source_type), как и добавление пойманной загрузки (см. download-tracking «Добавление пойманной загрузки в qBittorrent»): magnet/url — ссылкой; torrent — сохранёнными байтами .torrent файлом. Для torrent-источника retry БЕЗ живой раздачи система SHALL добавлять раздачу байтами и SHALL NOT активировать задачу в downloading, не добавив её (иначе задача повиснет как «нет в qBittorrent»).

Scenario: Retry упавшей magnet-загрузки из веб-UI

• GIVEN задача в failed, её торрент жив и здоров в qBittorrent
• WHEN пользователь нажимает retry в веб-UI
• THEN задача возвращается в downloading без повторного Add
• AND не падает снова на ближайшем тике сверки по таймауту

Scenario: Retry живого, но давно простаивающего торрента не падает снова

• GIVEN задача в stuck/stalled, её торрент жив в qBittorrent, но добавлен давно и данные не двигались дольше stuck_after
• WHEN пользователь нажимает retry
• THEN задача возвращается в downloading без повторного Add
• AND на ближайшем тике сверки НЕ падает снова в stuck (базис сброшен через retried_at)

Scenario: Retry доступен в Telegram

• WHEN для задачи в failed/stuck пользователь вызывает retry в Telegram-боте
• THEN задача возвращается в downloading

Scenario: Retry без живого источника добавляет источник заново

• GIVEN задача в failed, раздачи в qBittorrent нет
• WHEN пользователь инициирует retry
• THEN источник добавляется в qBittorrent заново — magnet/url ссылкой, torrent сохранёнными байтами файлом
• AND задача переходит в downloading

Scenario: Retry сломанного живого торрента повторно отдаёт источник

• GIVEN задача в failed, её торрент присутствует в qBittorrent, но в состоянии ошибки (error/missingFiles)
• WHEN пользователь инициирует retry
• THEN источник отдаётся заново (перецепка к сломанному торренту не выполняется)
• AND задача переходит в downloading

Scenario: Retry torrent-загрузки без живого источника

• GIVEN задача с source_type = torrent в failed, раздачи в qBittorrent нет, байты .torrent сохранены
• WHEN пользователь инициирует retry
• THEN сохранённые байты добавляются в qBittorrent файлом
• AND задача переходит в downloading (не остаётся без раздачи)