jellybit/openspec/changes/archive/2026-07-08-state-transition-graph/design.md

Design: декларативный граф переходов

Почему не библиотека (looplab/fsm, qmuntal/stateless)

Отклонено сознательно, три причины из нашего кода:

1. Тяжёлую часть библиотека не заберёт — она в SQL. Настоящий инвариант («не более одной активной загрузки на infohash» + «терминальную нельзя молча оживить») держится атомарно в SQLite-транзакциях (BEGIN IMMEDIATE через _txlock): CreateDownloadIfNoActive, ActivateIfNoOtherActive, гард WHERE state='catched' в PromoteCatched. In-memory FSM физически не может участвовать в транзакции с БД — она сядет поверх реального гарда как второй, более слабый слой.

2. У нас не событийный автомат, а reconciliation. Воркер в основном сверяет состояние БД с реальностью qBittorrent (reconcile, reconcileDesync — двумерная матрица источник×цель, reconcileRecovery). FSM-библиотеки моделируют линейный «событие → переход» хорошо, а сверку — плохо.

3. Состояние persisted, а не в объекте. State — колонка SQLite, перечитывается каждый тик. Библиотечная FSM держит состояние в структуре; пришлось бы конструировать FSM-объект на загрузку на тик только ради валидации одного ребра.

Соразмерная альтернатива — свой декларативный граф в internal/store: 80% ценности (граф в одном месте, документирован, тестируем, роняет нелегальный переход) без зависимости, без второго слоя, без импеданса. Соответствует принципу «минимум компонентов».

Где живёт гейт: store.setState

setState — истинная точка схождения: через неё проходят и SetDownloadState (reviveOK=false), и ActivateIfNoOtherActive (reviveOK=true). Единственный обход — PromoteCatched (собственный UPDATE ... WHERE state='catched'): его переход catched → downloading объявлен ребром графа, а from-состояние жёстко фиксирует его собственный гард, поэтому он согласован по построению и в setState не заводится.

Гейт — SQL-предикатом, не Go-проверкой с предварительным чтением:

UPDATE download SET state=?, ... WHERE id=?
  AND state IN (<легальные источники для to>)     -- граф (+ сам to: самопереход)
  AND state NOT IN (<terminal>)                    -- прежний гард, только если !reviveOK и to не терминально

Так проверка остаётся атомарной (без окна между чтением и записью), естественно композится с существующими предикатами и не требует держать доп. блокировку. При 0 строк — одно диагностическое чтение текущего состояния (только на пути ошибки, редко) даёт точное сообщение: «not found» / «illegal transition from→to».

Ортогональность (ключевой инвариант дизайна)

Граф и гард терминальности независимы и оба применяются:

• Граф говорит «ребро failed → downloading существует» (его выполняет retry).
• Гард терминальности говорит «но обычным SetDownloadState терминальную не оживить».

Поэтому failed → downloading проходит только через ActivateIfNoOtherActive (reviveOK=true, гард терминальности снят, но проверка владения хешами добавлена), а SetDownloadState(failed → downloading) отклоняется. Гейт графа аддитивен: он ничего не ослабляет, только добавляет ещё одно необходимое условие.

Самопереходы

Правило: from == to разрешён всегда (в графе не перечисляется). Причина — идемпотентная переустановка того же состояния уже используется (напр. Defer на уже deferred-задаче; повторная запись error_msg). legalSources(to) всегда включает сам to. Это сохраняет текущую семантику (такой UPDATE успешен, трогает error_*/updated_at) и избавляет от ручного перечисления петель.

Граф (from → to), выведенный из реального кода

Источник каждого ребра — конкретный метод воркера/store (w.transition → SetDownloadState, ActivateIfNoOtherActive, PromoteCatched, reconcileToReality):

from	to	кто выполняет
catched	downloading	PromoteCatched (успех add)
catched	failed	processCatched таймаут (qbit_add)
catched	cancelled	Cancel
catched	deferred	Defer (любое не-терминальное)
downloading	completed	reconcile (classReady)
downloading	failed	reconcile (qbit_error), checkTimeouts (magnet_timeout)
downloading	stuck	checkTimeouts (stalled)
downloading	cancelled	Cancel
downloading	deferred	Defer
completed	recognizing	recognizeOne
completed	cancelled / deferred	Cancel / Defer
recognizing	linking	finishRecognition (авто)
recognizing	review	finishRecognition
recognizing	cancelled / deferred	Cancel / Defer (окно на время LLM)
review	linking	Apply
review	recognizing	Refine / Rerecognize / SetType
review	deferred / cancelled	Defer / Cancel
review	orphaned / deleted	reconcileToReality (preflight: источник пропал)
linking	done	linkPlan (успех)
linking	review	linkPlan (build/collision)
linking	failed	linkPlan (apply error)
linking	cancelled / deferred	Cancel / Defer (задача застряла в linking после краха процесса)
done	reverted	Undo
done	target_missing / orphaned / deleted	reconcileDesync
deferred	linking	Apply
deferred	recognizing	Refine / Rerecognize / SetType
deferred	cancelled	Cancel
deferred	orphaned / deleted	reconcileToReality (preflight: источник пропал)
stuck	downloading	Retry, reconcileRecovery
stuck	completed	reconcileRecovery (classReady)
stuck	cancelled / deferred	Cancel / Defer (stuck не терминально)
failed	downloading	Retry, reconcileRecovery
failed	completed	reconcileRecovery
reverted	recognizing	Relink
reverted	orphaned / deleted	reconcileToReality (Relink: источник пропал)
cancelled	recognizing	Relink
cancelled	orphaned / deleted	reconcileToReality (Relink: источник пропал)
target_missing	recognizing	Relink
target_missing	done / orphaned / deleted	reconcileDesync / reconcileToReality (heal/preflight)
orphaned	done / target_missing / deleted	reconcileDesync
deleted	—	окончательно терминально; сверка его не переоценивает

Правило Cancel/Defer — любое не-терминальное → cancelled/deferred (проверка IsTerminal на входе). Поэтому в графе cancelled и deferred — легальная цель из каждого не-терминального состояния (включая linking после краха, включая catched); это закрепляется тест-инвариантом, а не ручной аккуратностью (см. tasks.md 3.6) — именно ручное перечисление рискует пропустить состояние.

reconcileToReality (preflight-приведение к реальности перед действием ревью, когда раздача исчезла из qBittorrent) — отдельный источник рёбер → orphaned/deleted из пользовательских/ревью-состояний; из терминальных reverted/cancelled он проходит SetDownloadState, так как цель (orphaned/deleted) тоже терминальна и гард терминальности не срабатывает.

Заметки о намеренных исключениях (чтобы граф был тесным, а не «на всякий случай»):

• failed/done → cancelled/deferred не включены: это терминальные состояния, Cancel/Defer их отвергают на входе (IsTerminal).
• Рёбра из терминальных (failed, reverted, cancelled, target_missing, orphaned) в активные состояния (downloading/completed/recognizing) в графе есть, но проходят только через ActivateIfNoOtherActive — см. «Ортогональность».

Риск и его закрытие

Главный риск — слишком тесный граф (пропущенное ребро ломает реально работающий переход, у которого нет теста). Закрытие: (1) граф выведён построчно из кода выше; (2) весь существующий набор тестов воркера/store гоняет реальные переходы — если предикат отвергнёт хоть один, тесты покраснеют; (3) новый тест графа проверяет объявленные рёбра на проход и репрезентативные необъявленные — на отказ.