Обработка рассинхрона состояния с реальностью (state-reconciliation)

Распознаём ручное удаление источника (раздача в qBittorrent) и/или цели (разложенные хардлинки) и отражаем его в состоянии задачи, без автодействий. - Новая capability state-reconciliation (OpenSpec): фоновая сверка по матрице «источник × цель» → состояния target_missing/orphaned/deleted, переходы и самовосстановление (healing). - worker: reconcileDesync в Poll (только разложенные/desync-задачи), дебаунс пропажи источника (порог [worker].source_missing_threshold) и синхронный preflight перед действиями (relink/recognize/apply/undo) — не доверяем state в БД. - layout.Undo: отказ снять последнюю копию (nlink<=1 или нет источника), отказ всего батча без частичного отката (ErrLastCopy). - store: единый список terminalStates для IsTerminal и FindActiveByInfohash (иначе семантика «активности» разъезжается), столбец source_miss_count, миграция 0003. - httpapi/web и Telegram: показ новых состояний и уведомления о рассинхроне. - Доки: workflow.md, jellyfin-layout.md, database.md (+0003), config. Change заархивирован в openspec/changes/archive, дельта влита в openspec/specs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-29 11:07:09 +03:00
parent f9d7fd9216
commit cc7e51b3a4
29 changed files with 1556 additions and 80 deletions
@@ -41,6 +41,7 @@
 [worker]
 poll_interval  = "5s"              # как часто опрашивать qBittorrent; Go-duration (s/m/h)
 magnet_timeout = "30m"             # ждать метаданные magnet не дольше; Go-duration
+source_missing_threshold = 3       # тиков сверки без раздачи, чтобы счесть источник удалённым

 [recognition]
 auto_confidence_threshold = 0.85   # порог авто-раскладки без ревью; доля 0.0–1.0
@@ -9,7 +9,8 @@
 > в том же change. Расхождение схемы с миграциями считаем багом
 > документации.
 >
-> Состояние на: миграции `0001_init`, `0002_recognition_plan`.
+> Состояние на: миграции `0001_init`, `0002_recognition_plan`,
+> `0003_source_miss_count`.

 Назначение таблиц и почему так — [architecture.md](architecture.md) →
 «Хранилище». Значения `state` и переходы — [workflow.md](workflow.md).
@@ -34,6 +35,7 @@ erDiagram
        TEXT    state       "NOT NULL; см. workflow.md"
        TEXT    error_code  "nullable"
        TEXT    error_msg   "nullable"
+        INTEGER source_miss_count "NOT NULL DEFAULT 0; дебаунс пропажи источника (миграция 0003)"
        TEXT    created_at  "NOT NULL DEFAULT datetime('now')"
        TEXT    updated_at  "NOT NULL DEFAULT datetime('now')"
    }
@@ -57,6 +57,18 @@ inode общий — диск не дублируется.
 поддержки жёстких ссылок), `layout` не падает, а копирует файл с
 предупреждением в лог — см. architecture.md → «Раскладка файлов».

+## Безопасный undo (не снимать последнюю копию)
+
+`Undo` снимает **лишний** хардлинк, а не единственный файл. Перед удалением
+батча `layout` проверяет каждую цель: если исходный файл уже не существует
+**или** у цели не осталось других жёстких ссылок (`nlink <= 1`), это —
+последняя копия данных, и весь `Undo` отклоняется целиком (ошибка
+`ErrLastCopy`), не сняв ни одной ссылки (частичный откат тоже стёр бы часть
+данных). Так нарушенный инвариант «источник неприкосновенен» (источник
+удалён вручную) не приводит к потере данных. Отсутствующую цель `Undo`
+пропускает как уже снятую (идемпотентность). Связь с состояниями
+рассинхрона — [workflow.md](workflow.md) → «Сверка с реальностью».
+
 ## Крайние случаи

 - **Многофайловый фильм** (части) — стэкинг по точному токену Jellyfin
@@ -39,9 +39,19 @@ stateDiagram-v2
    stuck --> downloading: Retry
    failed --> downloading: Retry

+    done --> target_missing: сверка — цель удалена
+    done --> orphaned: сверка — источник пропал
+    target_missing --> recognizing: Привязать заново
+    target_missing --> orphaned: источник тоже пропал
+    target_missing --> deleted: источник тоже пропал
+    orphaned --> deleted: цель тоже удалена
+    target_missing --> done: healing (цель вернулась)
+    orphaned --> done: healing (источник вернулся)
+
    done --> [*]
    cancelled --> [*]
    reverted --> [*]
+    deleted --> [*]

    note right of cancelled
        «Отклонить» доступно из любого
@@ -85,6 +95,30 @@ stateDiagram-v2
  (авто-раскладку не делаем) и требует, чтобы раздача всё ещё была в
  qBittorrent.

+## Сверка с реальностью (рассинхрон)
+
+Состояние в БД может разойтись с диском при **ручном** удалении: раздачу
+стирают из qBittorrent (источник) или файлы убирают из Jellyfin (целевые
+хардлинки). `worker` периодически сверяет уже разложенные задачи с фактом по
+двумерной матрице «источник × цель» (источник = раздача в qBittorrent,
+цель = разложенные хардлинки на ФС) и выводит состояние:
+
+- **target_missing** — источник на месте, цель удалена. Доступна команда
+  «Привязать заново» (`→ recognizing`); авто-действий нет.
+- **orphaned** — источник пропал, цель (последняя копия данных) на месте.
+  Команд вперёд нет; `Undo` запрещён (снял бы единственную копию).
+- **deleted** — нет ни источника, ни цели; терминально.
+
+Сверка трогает только `done`/`target_missing`/`orphaned`/`deleted` —
+активные и пользовательски-терминальные (`reverted`/`cancelled`/`failed`/
+`stuck`) состояния не задевает. Реальность «лечится» сама: при возврате
+источника/цели задача переходит обратно (вплоть до `done`). Пропажа
+**источника** дебаунсится (`[worker].source_missing_threshold` подряд идущих
+тиков), пропажа цели проверяется немедленно (локальная ФС надёжна). Команды,
+которым нужен источник (relink/распознать/применить/undo), проверяют его
+**синхронно перед действием** и не полагаются на фоновую сверку. Полные
+требования — `openspec/specs/state-reconciliation/`.
+
 Все переходы и команды идут через `worker` под per-download блокировкой —
 два транспорта не гонятся за одно состояние. Состояние персистентно в
 SQLite; `worker` периодически сверяет qBittorrent с БД и **усыновляет**
@@ -25,38 +25,25 @@
 матч в базе), [jellyfin-layout.md](specs/jellyfin-layout.md) (папка
 сериала с провайдер-id).

-### Рассинхрон состояния с реальностью (удалённый торрент / файлы)
+### Удаление средствами jellybit («единое окно», path 2)

-Состояние jellybit может разойтись с тем, что реально лежит на диске.
-Несколько сценариев разной остроты:
+Распознавание **ручного** удаления (источник из qBittorrent / цель из
+Jellyfin) и пометка рассинхрона уже сделаны: фоновая сверка по матрице
+«источник × цель» → состояния `target_missing`/`orphaned`/`deleted`,
+безопасный `undo` (не снимает последнюю копию, `nlink <= 1`), синхронный
+preflight перед действиями. См. `openspec/specs/state-reconciliation/`,
+[workflow.md](specs/workflow.md) → «Сверка с реальностью».

- **Жёсткий — удалён источник.** Раздачу удаляют (вручную или авто по
-  достижении seed limit), и qBittorrent стирает скачанные файлы. Тогда
-  хардлинк в библиотеке становится **последней** ссылкой на inode, и
-  обычный `undo` (`unlink` цели + чистка пустых каталогов) сотрёт
-  единственную копию насовсем — прямая потеря данных. Инвариант «источник
-  неприкосновенен» молчаливо перестаёт держаться: источника уже нет.
- **Мягкий — удалена цель.** Файлы убрали из библиотеки Jellyfin (вручную
-  или из самого Jellyfin), а jellybit по-прежнему числит загрузку в
-  `done`. Состояние врёт: ссылок уже нет, а сервис думает, что всё
-  разложено.
-
-Нужно продумать сверку записанного состояния (`file_link`, состояние
-загрузки) с фактом на ФС:
-
- как `worker` реагирует на исчезновение раздачи из qBittorrent
-  (состояние/пометка загрузки);
- как `undo` защищается, когда источник недоступен — например,
-  отказываться удалять, если у целевого файла счётчик ссылок == 1 (нет
-  второй копии) или исходный путь не существует, и явно об этом сообщать.
-  Откат снимает **лишний** хардлинк, а не последнюю копию файла;
- как ловить пропажу целевых файлов и отражать её в состоянии (напр.
-  периодическая сверка или проверка при показе — «разложено, но файлов
-  нет»), чтобы можно было осознанно перепривязать/переразложить.
+Осталось (path 2) — продолжение «единого окна»: удалять просмотренное
+**из самого jellybit**, не идя руками в qBittorrent/Jellyfin. Нужно
+продумать: команду удаления (снять наши хардлинки + опц. удалить раздачу из
+qBittorrent с файлами), подтверждение осознанности (а не случайный клик) и
+как это сочетается с инвариантом «источник неприкосновенен», когда
+пользователь сам просит убрать источник.

 Связано: [ADR-2026-06-13-hardlinks](adr/ADR-2026-06-13-hardlinks.md),
-[architecture.md](specs/architecture.md) → «Раскладка файлов» (undo,
-инвариант источника), [workflow.md](specs/workflow.md) (`done → reverted`).
+[architecture.md](specs/architecture.md) → «Раскладка файлов»,
+[workflow.md](specs/workflow.md).

 ### Наблюдаемость: метрики и учёт стоимости LLM