# 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`).