Приём: пропажа источника у активной загрузки → failed(source_gone) (MAJOR-3)

Раздача активной (downloading) загрузки, исчезнувшая из qBittorrent (удалил
пользователь/другой клиент), делала задачу вечным зомби: поллинг промахивался
по torrentFor, писал Warn и continue каждый тик — состояние не менялось,
уведомления и телеметрии не было, checkTimeouts без торрента не срабатывал.
Пропажей источника у downloading не владел никто (сверка рассинхрона покрывает
только done/target_missing/orphaned, восстановление — failed/stuck).

Активный цикл Poll теперь применяет тот же дебаунс пропажи источника, что и
сверка рассинхрона (source_miss_count / source_missing_threshold): после порога
подряд идущих промахов задача уходит downloading → failed с distinct error_code
source_gone и уведомлением. До порога транзиентная недоступность qBit
(рестарт демона) задачу не роняет. source_gone восстановлению сверкой не
подлежит (удаление намеренно), но штатно retriable — Retry заново отдаёт
сохранённый источник; Retry сбрасывает source_miss_count, чтобы вернувшаяся
задача получила полное грейс-окно, а не упала снова на ближайшем тике.

Ребро downloading → failed уже было в графе, миграций/полей БД нет. Спека
download-tracking дополнена требованием, диаграмма workflow.md — ребром.
Change downloading-source-gone заархивирован.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

openspec/changes/archive/2026-07-08-downloading-source-gone/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-08

openspec/changes/archive/2026-07-08-downloading-source-gone/design.md

@@ -0,0 +1,135 @@
+# Design — Пропажа источника у активной загрузки
+
+## Контекст
+
+`Poll` под `w.mu` листает `downloading`-задачи и для каждой ищет торрент в
+`byHash`. Промах сейчас — только `Warn` + `continue` (worker.go:503-508). Механизм
+дебаунса пропажи источника уже есть в `state-reconciliation`: поле
+`download.source_miss_count`, метод `debounceSource(ctx, d, sourceSeen) bool` и
+порог `[worker].source_missing_threshold` (дефолт 3). Он применяется только в
+`reconcileOneDesync`. Задача — переиспользовать его в активном цикле.
+
+## Решение
+
+### Целевое состояние: `failed`/`source_gone`, а не `deleted`
+
+Развилка из беклога: «downloading → `deleted` ИЛИ `failed` с distinct error_code
+для re-Add». Выбран **`failed`/`source_gone`**:
+
+- **Восстановимость.** Источник у нас сохранён (magnet `source_ref` или байты
+  `.torrent`). `Retry` заново отдаёт его в qBittorrent — задача продолжится.
+  `deleted` терминален навсегда и не оставляет пользователю выхода, хотя пропажа
+  могла быть случайной.
+- **Минимальная дельта графа.** Ребро `downloading → failed` уже объявлено
+  (`allowedTransitions`), нового ребра не нужно. `downloading → deleted` ребра нет
+  — пришлось бы вводить.
+- **Переиспользование инфраструктуры.** `StateFailed` уже шлёт `EventFailed`
+  (с дебаунсом уведомлений) и уже retriable — не нужен ни новый notify-повод, ни
+  новая команда.
+- **Distinct `error_code`.** `source_gone` отличается от `qbit_error`
+  (реальная ошибка qBit), `magnet_timeout`/`stalled` (наша нетерпеливость) — по
+  нему UI/лог различает причину, и он **осознанно не в наборе** `reconcileRecovery`
+  (`ListRecoverable(magnet_timeout, stalled)`): намеренно удалённый источник не
+  должен молча воскресать, у пользователя есть явный `Retry`.
+
+`deriveState(false, false) = deleted` (матрица «источник × цель») здесь НЕ
+применяется: у активной `downloading`-задачи цели ещё нет, и это не путь сверки
+рассинхрона, а отдельное правило прямого пути. Матрица по-прежнему не трогает
+активные состояния.
+
+### Переиспользование дебаунса в активном цикле
+
+`debounceSource(ctx, d, sourceSeen)`:
+- `sourceSeen=true` → сбрасывает счётчик в 0, возвращает `true`;
+- `sourceSeen=false` → инкремент, возвращает `miss < threshold`.
+
+Активный цикл `Poll` перестраивается так:
+
+```go
+t, ok := torrentFor(d, byHash)
+if present := w.debounceSource(ctx, d, ok); !present {
+    // порог промахов исчерпан — источник действительно пропал
+    lctx := w.scoped(ctx, capIngest, d.ID, d.PrimaryInfohash())
+    w.transition(lctx, d, store.StateFailed, errCodeSourceGone,
+        "источник удалён из qBittorrent")
+    continue
+}
+if !ok {
+    // до порога: транзиентный промах (рестарт qBit) — ждём следующий тик
+    continue
+}
+w.captureInfohashes(ctx, d, t)
+w.captureSourceAddedAt(ctx, d, t)
+w.reconcile(ctx, d, t)
+```
+
+`debounceSource` вызывается в ЛЮБОМ случае (и при `ok`, и при промахе), поэтому
+появление раздачи сбрасывает счётчик, накопленный ранее.
+
+### Сброс `source_miss_count` при `Retry` (иначе нет грейс-окна)
+
+`source_gone` — единственный путь, оставляющий у **retriable** задачи ненулевой
+`source_miss_count` (у `magnet_timeout`/`stalled` источник на падающем тике
+присутствовал, значит счётчик уже 0). Без сброса `Retry` вернул бы задачу в
+`downloading` с `source_miss_count == threshold`: на первом же тике, если
+переотданная раздача ещё не видна в выдаче qBittorrent (Add без ошибки, но
+регистрация с задержкой), `debounceSource` даёт `miss = threshold+1` → мгновенный
+повторный `source_gone`, минуя обещанное спекой грейс-окно.
+
+Поэтому `Retry` SHALL сбрасывать `source_miss_count` в 0 — рядом с существующим
+сбросом `retried_at` (та же интенция «свежее окно», MAJOR-1), best-effort. Это
+покрывает общий случай: любая retriable-задача входит в `downloading` с чистым
+счётчиком. Путь авто-восстановления (`reconcileRecovery`) сброса не требует —
+туда `source_gone` не попадает, а у `magnet_timeout`/`stalled` счётчик уже 0.
+
+### Почему нет двойного учёта `source_miss_count`
+
+Задача в один момент времени находится ровно в одном состоянии: либо в активном
+цикле (`downloading`), либо в `reconcileDesync` (`done`/`target_missing`/
+`orphaned`) — не в обоих за тик. Поле `source_miss_count` используется с единой
+семантикой «сброс при наличии источника», поэтому пересечения нет. При переходе
+`downloading → completed` счётчик уже 0 (источник виден на том же тике).
+
+### catched-исключение сохраняется
+
+`catched`-задачи в активный цикл не попадают (там нет раздачи по дизайну) —
+требование «catched не считается пропажей раздачи» не затрагивается: цикл листает
+только `StateDownloading`.
+
+## Альтернативы
+
+- **`downloading → deleted`** — отклонено: терминально без выхода, требует нового
+  ребра, теряет ещё-скачиваемую задачу при, возможно, случайной пропаже.
+- **Авто-восстановление `source_gone` при возврате раздачи** (добавить в
+  `reconcileRecovery`) — отклонено для v1: намеренное удаление не должно тихо
+  оживать; есть явный `Retry`. Отложено (можно добавить позже отдельным change,
+  если появится боль).
+- **Отдельный notify-повод `EventSourceGone`** — избыточно: `EventFailed`
+  семантически покрывает «задача упала», текст уведомления берётся по состоянию.
+
+## Принятые ограничения (вне scope)
+
+- **Дебаунс уведомлений может проглотить пинг.** `shouldNotifyFail` дебаунсит
+  `EventFailed` по `download_id` на 1 ч. Узкая последовательность (задача уже
+  падала `stalled`/`stuck` с пингом < 1 ч назад → `Retry` → источник удалён →
+  `source_gone` в то же окно) не пришлёт повторный пинг. Приемлемо: смена
+  состояния и телеметрия всё равно фиксируются (главная боль зомби — «никто не
+  двигает» — закрыта); отдельный пинг именно про source_gone не критичен.
+- **Задача `downloading` с пустым `Infohashes`** остаётся вне правила: гард
+  `len(d.Infohashes)==0 { continue }` стоит до `torrentFor` (как и в
+  `reconcileOneDesync`). В Ф1 не случается (magnet всегда с infohash); отдельный
+  класс зомби, этим change не адресуется.
+- **Пустая выдача qBittorrent при живом демоне** (HTTP 200 сразу после рестарта,
+  resume-data ещё не загружены) нарастит промахи всем активным задачам. Экспозиция
+  предсуществующая и общая с `reconcileDesync` (тот массово пометил бы
+  `orphaned`/`deleted`); change лишь распространяет её на активные загрузки.
+  Дебаунс (`source_missing_threshold`) — уже имеющаяся защита; принимаем.
+
+## Тесты
+
+- Промах меньше порога → задача остаётся `downloading` (дебаунс).
+- Промах ≥ порога → `downloading → failed`/`source_gone` + `EventFailed`.
+- Возврат раздачи до порога → счётчик сброшен, задача жива, ушла по обычному
+  reconcile.
+- `source_gone` не воскрешается `reconcileRecovery` (источник вернулся — задача
+  остаётся `failed` до ручного `Retry`).

openspec/changes/archive/2026-07-08-downloading-source-gone/proposal.md

@@ -0,0 +1,47 @@
+# Пропажа источника у активной загрузки (MAJOR-3)
+
+## Why
+
+Если раздача исчезает из qBittorrent (пользователь или другой клиент удалил её),
+пока задача в `downloading`, задача становится **вечным зомби**. Поллинг активных
+загрузок промахивается по `torrentFor`, пишет `Warn "active download not found in
+qbittorrent"` и делает `continue` — и так каждый тик, бесконечно. Состояние не
+меняется, уведомления нет, телеметрии нет, `checkTimeouts` требует торрент (значит
+таймауты-предохранители не срабатывают). Единственный выход — ручной Cancel/Defer.
+
+Дыра: сверка рассинхрона (`state-reconciliation`) покрывает пропажу источника
+только для уже разложенных состояний (`done`/`target_missing`/`orphaned`), а
+восстановление (`reconcileRecovery`) — только `failed`/`stuck`. Для активного
+`downloading` пропажей источника не владеет НИКТО. Сравни: та же пропажа в
+`completed`/`recognizing`/`review` деградирует штатно (там источник уже не нужен
+или его отсутствие ведёт через матрицу).
+
+## What Changes
+
+- Поллинг активных загрузок SHALL применять **дебаунс пропажи источника** (тот же
+  `SourceMissCount` / `[worker].source_missing_threshold`, что и сверка
+  рассинхрона): промах `torrentFor` наращивает счётчик, любое появление раздачи
+  его сбрасывает.
+- После порога подряд идущих промахов задача SHALL переходить `downloading →
+  failed` с новым отдельным `error_code` `source_gone` и уведомлять автора
+  (`EventFailed`).
+- `source_gone` **восстановлению сверкой не подлежит** (не входит в набор
+  `reconcileRecovery`): удаление источника из qBittorrent — намеренное действие,
+  молча воскрешать задачу нельзя. Задача остаётся штатно **retriable**: `Retry`
+  заново отдаёт источник (у нас сохранены magnet/`.torrent`-байты).
+
+Ребро графа `downloading → failed` уже объявлено — нового ребра не требуется.
+Меняется только набор `error_code` и поведение поллинга активных загрузок.
+
+## Capabilities
+
+- `download-tracking` — ADDED: «Пропажа источника у активной загрузки».
+
+## Impact
+
+- Код: `internal/worker/worker.go` (поллинг активных загрузок, новый
+  `errCodeSourceGone`), тесты воркера.
+- Спека: `download-tracking` (новое требование). Диаграмма `docs/specs/workflow.md`
+  (миррор FSM) — добавить ребро `downloading → failed (source_gone)`.
+- Миграции БД нет: `source_miss_count` уже существует, новых полей не вводим.
+- Конфиг без изменений: переиспользуем `source_missing_threshold`.

openspec/changes/archive/2026-07-08-downloading-source-gone/specs/download-tracking/spec.md

@@ -0,0 +1,58 @@
+# download-tracking Specification
+
+## ADDED Requirements
+
+### 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`

openspec/changes/archive/2026-07-08-downloading-source-gone/tasks.md

@@ -0,0 +1,38 @@
+# Tasks — Пропажа источника у активной загрузки
+
+## 1. Код воркера
+
+- [x] 1.1 Ввести `errCodeSourceGone = "source_gone"` в блок кодов ошибок
+  (`internal/worker/worker.go`) с комментарием: distinct-код, восстановлению
+  сверкой не подлежит, retriable вручную.
+- [x] 1.2 Перестроить активный цикл в `Poll`: при промахе `torrentFor` прогонять
+  `debounceSource`; при исчерпании порога — `transition downloading → failed`
+  (`source_gone`); до порога — `continue`; при наличии источника — сброс счётчика
+  и обычная сверка (`captureInfohashes`/`captureSourceAddedAt`/`reconcile`).
+- [x] 1.3 Убедиться, что `debounceSource` вызывается и при наличии источника
+  (сброс накопленных промахов).
+- [x] 1.4 `Retry` сбрасывает `source_miss_count` в 0 (рядом с `SetRetriedAt`),
+  чтобы retried `source_gone`-задача получила полное грейс-окно, а не падала
+  сразу (см. design «Сброс source_miss_count при Retry»).
+
+## 2. Тесты
+
+- [x] 2.1 Промах < порога → задача остаётся `downloading`.
+- [x] 2.2 Промах ≥ порога → `downloading → failed`/`source_gone` + `EventFailed`.
+- [x] 2.3 Возврат раздачи до порога → счётчик сброшен, задача ведётся обычной
+  сверкой.
+- [x] 2.4 `source_gone` не воскрешается `reconcileRecovery` (источник вернулся —
+  задача остаётся `failed`).
+- [x] 2.5 `Retry` задачи `source_gone` сбрасывает `source_miss_count`: после
+  retry с ещё-не-видимой раздачей задача остаётся `downloading` полный порог
+  тиков (грейс-окно не съедено).
+
+## 3. Документация
+
+- [x] 3.1 `docs/specs/workflow.md`: добавить ребро `downloading → failed`
+  (`source_gone`, пропажа источника) в диаграмму и список переходов.
+
+## 4. Верификация
+
+- [x] 4.1 `task test` / `task lint` зелёные.
+- [x] 4.2 `openspec validate downloading-source-gone --strict`.