jellybit/openspec/specs/state-reconciliation/spec.md

# state-reconciliation Specification

## Purpose

Сверка записанного состояния загрузки с фактом на файловой системе и в
qBittorrent. Capability описывает периодическую и принудительную проверку
присутствия **источника** (раздача в qBittorrent) и **цели** (разложенные
хардлинки), вывод состояний рассинхрона (`target_missing`/`orphaned`/
`deleted`) из матрицы «источник × цель», их переходы и самовосстановление,
дебаунс пропажи источника, инвариант безопасного `Undo` (не снимать
последнюю копию) и уведомления о рассинхроне.

## Requirements

### Requirement: Периодическая сверка состояния с реальностью

`worker` SHALL периодически (на тике поллинга) сверять задачи, для которых
ожидаются разложенные файлы, с фактом на файловой системе и в qBittorrent, и
выводить состояние задачи из двух независимых признаков: присутствия
**источника** (раздача с `download.infohash` в выдаче qBittorrent) и
присутствия **цели** (все `file_link` со `status = linked` существуют на ФС).

Сверке SHALL подвергаться только состояния `done`, `target_missing`,
`orphaned`, `deleted`. Активные (`downloading`/`recognizing`/`review`/
`deferred`/`linking`) и пользовательски-терминальные (`reverted`/`cancelled`/
`failed`/`stuck`) состояния сверка трогать SHALL NOT.

Состояние SHALL переписываться только при его изменении (без записи и логов,
когда выведенное состояние совпадает с текущим).

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

- **WHEN** для задачи в `done` раздача присутствует в qBittorrent и все её
  разложенные хардлинки существуют
- **THEN** задача остаётся в `done`
- **AND** запись состояния и лог перехода не выполняются

#### Scenario: Частичная пропажа цели считается отсутствием

- **WHEN** часть разложенных хардлинков задачи удалена, а источник на месте
- **THEN** цель считается отсутствующей и задача переходит в `target_missing`

### Requirement: Принудительная проверка источника/цели перед действием

Команда workflow, требующая наличия источника или цели, SHALL синхронно
проверять их присутствие непосредственно перед выполнением действия и SHALL
NOT полагаться только на фоновую сверку `worker` (она отстаёт на интервал
поллинга и дебаунс). Проверка перед действием выполняется как **единичная
немедленная проба без дебаунса**: дебаунс применяется только к фоновому
авто-маркированию.

Под это требование подпадают как минимум: повторная привязка/распознавание
(`relink`, «Распознать заново», «Уточнить») и раскладка (`Apply`) — требуют
**источника**; `Undo` — требует **источника** (чтобы не снять последнюю
копию).

Если предусловие не выполнено, система SHALL NOT выполнять действие, SHALL
привести состояние задачи в соответствие с реальностью (вывести состояние из
матрицы «источник × цель», как при сверке) и SHALL сообщить причину
пользователю.

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

- **WHEN** пользователь даёт команду, требующую источника (например
  «Привязать заново»)
- **THEN** система синхронно проверяет наличие раздачи в qBittorrent перед
  запуском распознавания
- **AND** если источника нет — распознавание не запускается, задача
  приводится к `orphaned` либо `deleted` (по наличию цели), причина
  сообщается

#### Scenario: Проверка не ждёт фоновую сверку

- **WHEN** источник уже удалён, а фоновая сверка ещё не отметила это (в БД
  состояние, например, `done`)
- **THEN** команда, требующая источника, немедленно обнаруживает его
  отсутствие собственной проверкой и отказывает, не дожидаясь `worker`

### Requirement: Состояние target_missing и доступность повторной привязки

Когда у задачи источник присутствует, а цель отсутствует, система SHALL
переводить её в состояние `target_missing` и SHALL NOT предпринимать
автоматических действий (не запускать повторное распознавание/раскладку
самостоятельно).

Из `target_missing` система SHALL предоставлять пользовательскую команду
повторной привязки (relink) с переходом `target_missing → recognizing`, как
из `reverted`/`cancelled`; повторная привязка идёт через `review` с ручным
подтверждением.

#### Scenario: Цель удалена, источник на месте

- **WHEN** сверка обнаруживает, что разложенных хардлинков задачи `done`
  больше нет, но раздача в qBittorrent присутствует
- **THEN** задача переходит в `target_missing`
- **AND** система не запускает распознавание или раскладку автоматически

#### Scenario: Пользователь инициирует повторную привязку

- **WHEN** для задачи в `target_missing` пользователь даёт команду «Привязать
  заново»
- **THEN** задача переходит в `recognizing` и далее проходит через `review`
  с ручным подтверждением

### Requirement: Состояние orphaned при пропаже источника

Система SHALL переводить задачу в состояние `orphaned`, когда источник
отсутствует (с учётом дебаунса), а цель присутствует, отражая, что
библиотечный хардлинк остался единственной копией данных.

#### Scenario: Источник удалён, цель на месте

- **WHEN** сверка устойчиво (после дебаунса) не находит раздачу задачи в
  qBittorrent, а её разложенные хардлинки существуют
- **THEN** задача переходит в `orphaned`

### Requirement: Состояние deleted при пропаже источника и цели

Когда отсутствуют и источник (с учётом дебаунса), и цель, система SHALL
переводить задачу в состояние `deleted`. В `deleted` действий над задачей
больше нет.

#### Scenario: Источник и цель удалены

- **WHEN** сверка устойчиво не находит раздачу в qBittorrent и разложенных
  хардлинков задачи на ФС больше нет
- **THEN** задача переходит в `deleted`

### Requirement: Дебаунс пропажи источника

Система SHALL дебаунсить только **отсутствие источника**, чтобы временная
недоступность qBittorrent (рестарт демона, сбой API) не вызывала ложных
пометок: источник считается удалённым лишь после `N` подряд тиков сверки без
него, где `N = [worker].source_missing_threshold`. Любое обнаружение раздачи
SHALL сбрасывать счётчик пропусков.

Отсутствие цели дебаунсу подвергаться SHALL NOT (локальная проверка ФС
надёжна).

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

- **WHEN** раздача отсутствует в qBittorrent меньше `source_missing_threshold`
  тиков подряд
- **THEN** источник трактуется как присутствующий и состояние задачи не
  меняется

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

- **WHEN** раздача снова обнаружена в qBittorrent
- **THEN** счётчик пропусков источника сбрасывается в ноль

### Requirement: Самовосстановление состояния при возврате реальности

Система SHALL возвращать задачу в согласованное состояние, когда реальность
восстановилась (состояние выводится из текущей матрицы «источник × цель»):
при возврате источника и/или цели задача SHALL переходить из
`orphaned`/`target_missing`/`deleted` обратно (в т.ч. в `done`, когда
присутствуют оба).

#### Scenario: Источник вернулся

- **WHEN** для задачи в `orphaned` раздача снова появилась в qBittorrent, а
  цель по-прежнему на месте
- **THEN** задача возвращается в `done`

### Requirement: Безопасный Undo не снимает последнюю копию

`Undo` (снятие созданных хардлинков) SHALL отказываться удалять целевую
ссылку, если она является последней копией данных: целевой файл существует и
его счётчик ссылок `nlink <= 1`, либо исходный файл (`src_path`) не
существует. В этом случае система SHALL NOT выполнять `unlink` такого файла и
SHALL явно сообщать причину отказа; задача в `reverted` при отказе переходить
SHALL NOT.

Отсутствующую целевую ссылку (файла уже нет) `Undo` SHALL пропускать как
успешно снятую (идемпотентность). Команда `Undo` для задачи в `orphaned`
SHALL отклоняться сразу с пояснением, что источник удалён.

#### Scenario: Отказ снять единственную копию

- **WHEN** при `Undo` целевой хардлинк существует, но его `nlink <= 1` (или
  исходный файл отсутствует)
- **THEN** система не удаляет файл и сообщает, что это последняя копия
- **AND** задача остаётся в текущем состоянии (не `reverted`)

#### Scenario: Undo снимает лишний хардлинк при живом источнике

- **WHEN** при `Undo` целевой хардлинк существует, исходный файл на месте и
  `nlink > 1`
- **THEN** система снимает целевой хардлинк, оставляя исходный файл нетронутым

### Requirement: Уведомление о рассинхроне

При переходе задачи в `orphaned` или `target_missing` система SHALL
уведомлять автора загрузки через настроенный механизм уведомлений
(`notifier`), чтобы рассинхрон не оставался незамеченным.

#### Scenario: Уведомление при потере источника

- **WHEN** задача переходит в `orphaned`
- **THEN** система отправляет автору загрузки уведомление о потере источника