jellybit/openspec/changes/archive/2026-07-10-dedup-target-missing-and-dismiss/design.md

Context

Дедуп приёма (ingest) держит инвариант «не более одной активной загрузки на infohash», где «активная» = state NOT IN terminalStates. Терминальный набор (done, cancelled, failed, reverted, target_missing, orphaned, deleted) смешивает две разные ситуации:

• «Отработали, забыли» — done/cancelled/failed/reverted/deleted. Повторный приём такого инфохэша — осознанное «хочу заново», новая загрузка легитимна (ingest/spec.md, сценарий «Повторный приём после завершения»).
• «Держим источник ради незакрытого намерения» — target_missing (источник жив в qBittorrent, ждёт relink) и orphaned (источник пропал, запись держит претензию на последнюю копию данных).

Дедуп трактует обе группы одинаково: терминально → не активна → плоди новую. Во второй группе это рождает близнеца (реальный прод-случай: target_missing + done на один торрент). Причём усыновление раздачи воркером (download-tracking, change catched-promote-without-readd) делает близнеца «боевым» — он раскладывается и занимает целевой путь, из-за чего у осиротевшей записи Привязать заново упирается в коллизию владения путём.

Отдельно: закрыть лишнюю target_missing-запись сейчас нечем. Единственная команда, убирающая её из активного внимания, — «Удалить», но она сносит раздачу в qBittorrent (deleteFiles=true), а этого как раз не нужно: раздача общая, её ведёт done-близнец.

Goals / Non-Goals

Goals:

• Повторный приём инфохэша, удерживаемого записью в target_missing/orphaned, не создаёт новую загрузку, а возвращает существующую (attach), сохраняя приём быстрым и без обращения к qBittorrent.
• Пользователь может вручную закрыть любую зависшую/спорную загрузку (стоп-кран), ничего не делая с файлами и раздачей.
• Инвариант «≤1 активной на infohash» и его атомарные гарды не ослабляются.

Non-Goals:

• Авто-схлопывание/слияние уже существующих дублей фоновой сверкой — сознательно ручной путь.
• Изменение логики усыновления раздачи в воркере и общей матрицы «источник × цель» сверки.
• Авто-relink при повторном приёме (это обращение к qBittorrent — противоречит «быстрому приёму без сети»); relink остаётся отдельным явным действием.
• Разбор коллизии владения целевым путём при relink target_missing, чьи файлы уже разложены другой записью, — эту ситуацию закрывает команда «Закрыть», а не relink.
• Любое удаление/создание файлов или снятие раздачи командой «Закрыть» — для этого есть «Удалить». «Закрыть» — чисто смена статуса.

Decisions

Р1. Дедуп: reingest-blocking states = active ∪ {target_missing, orphaned}

Вводим понятие «состояний, блокирующих повторный приём»: активные состояния плюс target_missing и orphaned. Поиск дедупа при приёме (FindActiveByInfohash → по сути FindReingestBlockingByInfohash) ищет запись в любом из этих состояний по любому из хешей и, найдя, возвращает её вместо создания новой. Приоритет — активная (если вдруг есть и активная, и desync-запись на один хеш, что допускает текущий инвариант), иначе desync-запись.

• Почему не «сделать target_missing/orphaned активными»: сломает семантику «активность выводится только из state» и потянет за собой сверку, healing, выборки активных. Дедуп — единственное место, которому нужна расширенная оптика; локализуем изменение там.
• Атомарность: гард создания (CreateDownloadIfNoActive) остаётся про активные — он бэкстоп инварианта «≤1 активной». Расширенная проверка — это read-ветка дедупа ДО создания; она короткозамыкает на attach. Гонка «два приёма одновременно на свежий target_missing» в худшем случае даёт одну лишнюю попытку create, которую по-прежнему отсекает активный гард; близнец на target_missing при этом не создаётся, т.к. обе ветки видят одну и ту же desync-запись (она уже в БД, коммитнута ранее).

Р2. Attach для desync-записи не воскрешает и не доносит хеши сам по себе

Ветка attach для target_missing/orphaned возвращает запись как «спящую, требует relink» (флаг в результате приёма), НЕ переводя её в активное состояние и НЕ вызывая qBittorrent. Донесение недостающих хешей (гибридный торрент) для desync-записи допустимо и безопасно (терминальная запись не «активна», гонки за хеш нет), но подчиняется тому же правилу «не красть хеш у другой активной» (ingest/spec.md, «Атомарность возврата…»). Бот/веб сообщают: запись существует, приложите relink или закройте.

• Почему не авто-relink: relink делает синхронный source-preflight (обращение к qBittorrent) — это нарушает инвариант «синхронный приём не ходит в qBittorrent». Явный relink пользователем сохраняет разделение шагов.

Почему failed/reverted НЕ блокирующие (в отличие от target_missing/ orphaned): у них нет удерживаемого источника ради незакрытого намерения — повторный приём осознанно трактуется как свежая попытка. Новая активная загрузка забирает хеш, старая терминальная им не владеет; её фоновое самовосстановление (revive failed) корректно отклонится активным гардом «infohash занят». Дубля-призрака (как с target_missing) при этом не возникает: старая запись остаётся терминальной и не раскладывается повторно. Реализация не переиспользует общий active-хелпер для desync-проверки — расширенная оптика нужна только дедуп-пред-риду (см. Р1, Б-развязка с ActivateIfNoOtherActive/ AddInfohashes).

Р3. «Закрыть» = переход в cancelled, без нового статуса (принято)

Команда «Закрыть» (dismiss) переводит запись в существующее терминальное cancelled с error_code-дискриминатором (user_dismiss), человекочитаемой причиной в error_msg и логом перехода.

Почему cancelled, а не новый dismissed:

• Прецедент в коде: Delete переиспользует deleted + error_code="user_delete" и явно постулирует «новый статус вводить SHALL NOT» — терминальный набор завязан на семантику активности, любой новый статус её разъедает и тянет правки во все выборки/сверку.
• cancelled уже значит «пользователь отказался от этой записи, источник не трогаем», из него доступен relink — естественный safety valve, если передумал.
• cancelled не входит в reingest-blocking (Р1) → после «Закрыть» повторный приём заведёт свежую загрузку. Это осознанно: запись закрыта, дубля-призрака больше нет.

Различение причины отмены (закрытие стоп-краном vs. отклонение на ревью) несёт error_code, а не отдельный статус.

Р4. «Закрыть» — универсальный стоп-кран из любого состояния, кроме deleted (принято)

Команда доступна из любого состояния, кроме deleted (строго терминально, сверка его не переоценивает — не воскрешаем граф). На cancelled — идемпотентный no-op (самопереход). Инвариант команды: только меняет статус, файлы под paths.* и раздачу в qBittorrent НЕ трогает.

• Из target_missing (исходный прод-случай) — закрытие инертно (целевых ссылок нет, источник жив и остаётся раздаваться).
• Из done/orphaned — библиотечные хардлинки сознательно остаются на месте (не удаляем: «Закрыть» ≠ «Удалить»). Запись перестаёт отслеживаться.
• Из активных/stuck/failed/deferred — источник в qBittorrent остаётся как есть (докачивается/раздаётся); мы лишь снимаем запись из внимания.

Отличие от существующего Cancel/«Отклонить» (review-флоу, только из нетерминальных): «Закрыть» — универсальный стоп-кран, доступный и из терминальных done/failed/reverted/target_missing/orphaned, и живёт в отдельной danger zone внизу страницы. Оба ведут в cancelled; различаются гардом источника и error_code.

Рёбра allowedTransitions, которые нужно добавить (у нетерминальных cancelled как цель уже есть): done → cancelled, failed → cancelled, reverted → cancelled, target_missing → cancelled, orphaned → cancelled. После этого cancelled — легальная цель из любого состояния, кроме deleted.

Risks / Trade-offs

• Relink target_missing при существующем done-близнеце всё ещё упрётся в коллизию пути. → Ожидаемо и допустимо: правильное действие для лишней записи — «Закрыть», а не relink; коллизия владения путём (state-reconciliation, «Занятый путь даёт коллизию») отрабатывает штатно и не портит данные.
• Reingest-blocking расширен → пользователь, реально желающий переснять target_missing-торрент заново, получит attach, а не новую загрузку. → Приемлемо: у него есть relink (вперёд) и «Закрыть» (закрыть и, при желании, переслать снова — новая загрузка заведётся из cancelled).
• Гонка двух одновременных приёмов на свежую desync-запись. → Оба видят уже коммитнутую desync-запись → attach; активный гард отсекает случайный create. Близнец не рождается.
• error_code=user_dismiss в cancelled смешивает две причины отмены. → Дискриминатор в error_code + error_msg/лог различают их; телеметрия по причине доступна без нового статуса.
• «Закрыть» из done/orphaned оставляет неотслеживаемые хардлинки под paths.movies/series, чей file_link продолжает «владеть» путём (cancelled сверкой не переоценивается). → Осознанный компромисс стоп-крана «только статус»: файлы оставляем как есть, реальную зачистку делает «Удалить». Повторная закачка того же пути упрётся в штатную коллизию владения путём (state-reconciliation, «Занятый путь даёт коллизию»), а не в порчу данных.
• «Закрыть» из активных состояний рвёт запись из-под воркера (напр. в linking/downloading). → Команды сериализуются воркером под единой блокировкой (как прочие команды ревью) — «Закрыть» применяется как последняя валидная команда, а не посреди операции; частично созданные ссылки остаются, что соответствует контракту «только статус».
• Восстановление orphaned через приём — двухшаговое. orphaned (источник пропал) блокирует повторный приём (attach), но relink из orphaned не реализован, а приём не добавляет источник в qBittorrent. → Рабочий путь возврата источника: «Закрыть» (→ cancelled) → повторный приём (уже не блокируется) → свежая активная загрузка, которую воркер добавит и разложит. Прямой приём без attach создал бы близнеца с коллизией целевого пути (файл orphaned ещё на месте), поэтому attach выбран сознательно; транспорты в orphaned формулируют действие как «закройте, затем добавьте заново» (не «привяжите заново»). Прямой relink-из-orphaned — возможное будущее улучшение вне scope этого change.
• danger zone скрывает завершённую (done) запись одним действием. → Разместить «Закрыть» в отдельной danger zone внизу страницы; для необратимо выглядящих случаев (done и прочие терминальные) UI SHOULD запрашивать подтверждение (относительно дёшево — из cancelled доступен relink).

Migration Plan

• Схема БД не меняется (нет таблиц/столбцов/статусов). Миграции не требуются.
• Изменения — код + дельта-спеки; деплой обычным бинарём. Откат — откат бинаря; данные не мигрированы, несовместимости нет.
• Обновить граф переходов в тесте (cancelled как цель из done/failed/reverted/target_missing/orphaned) и описание статусов/переходов в docs/specs/database.md.

Open Questions

• Р3 (cancelled + error_code) и Р4 (универсальный стоп-кран из любого состояния, кроме deleted) — приняты.
• Требует ли «Закрыть» из терминальных/done подтверждения в UI (см. риск) — решить на реализации веб-UI.
• Тексты для транспортов: формулировка ответа приёма при attach на desync-запись («существует как #id без цели — привяжите заново или закройте») и подпись кнопки «Закрыть» в веб/Telegram.