## Context

Набор capabilities в `openspec/specs/` сложился по ходу пилотной миграции и не
отражает цепочку обработки загрузки. Три проблемы:

1. `recognition` смешивает разбор LLM и работу с метабазами.
2. Поведение ревью размазано: часть — в `web-ui`, основная часть — в не
   перенесённом `docs/specs/review-ux.md`.
3. Звенья цепочки `file-layout`, `download-tracking`, `notifications` в OpenSpec
   отсутствуют — источник истины по ним в `docs/specs/` (`jellyfin-layout.md`,
   `workflow.md`, `architecture.md`).

Разбор цепочки «загрузка → распознавание → матч → ревью → раскладка» (действие →
артефакт в БД) дал естественный набор доменов; приводим capabilities к нему.

Ограничение: **рефакторинг только спек, код не трогаем.** Формулировки переносим
эквивалентными — ни одно нормативное требование не должно измениться по смыслу.

## Goals / Non-Goals

**Goals:**
- Одно поведение — один capability; имя читается без знания кода.
- Полная цепочка представлена в `openspec/specs/` (перенос из `docs/specs/`).
- Источник истины по мигрируемым темам переезжает в OpenSpec; в `docs/specs/`
  остаётся пометка о переезде (как пилот `ingest`).

**Non-Goals:**
- Никаких изменений поведения, схемы БД, кода, конфигурации.
- Не вводим новые сущности домена (напр. «тайтл» — отдельная задача беклога).
- Не дробим метабазу на search/match (решено: одна `metadata-match`).
- Мульти-бот маршрутизация уведомлений — отдельная задача, здесь только фиксируем
  текущее поведение `notifier`.

## Decisions

### D1. Механика переноса требований между capabilities

OpenSpec 1.4.x поддерживает `RENAMED` только внутри одной спеки. Межспековый
перенос оформляем парой: **`REMOVED Requirement`** в исходной спеке (с
`**Reason**`/`**Migration**`, указывающими целевую capability) + **`ADDED
Requirement`** в целевой. Текст требования в ADDED — эквивалент исходного
(перенос, не переписывание). Альтернатива (просто RENAMED) не подходит:
capability меняется, а не имя внутри одной спеки.

### D2. `recognition` → `recognition` + `metadata-match`

Разные действия: «разобрать сигналы моделью» и «найти/подтвердить запись в базе».
`Контракт LLM на оригинальное и локализованное названия` **остаётся в
recognition** (это требование к выходу модели), хотя используют эти поля обе:
recognition — чтобы модель их заполнила, metadata-match — как ключи поиска.

| Текущее требование (recognition) | Назначение |
|---|---|
| Сверка с базой по нескольким названиям | → `metadata-match` |
| Контракт LLM на оригинальное и локализованное названия | остаётся `recognition` |
| Локаль запроса к TMDB | → `metadata-match` |
| Нормализация названий при сравнении | → `metadata-match` |
| Кандидат несёт URL для внешней проверки | → `metadata-match` |

Backfill `recognition` из `docs/specs/recognition.md` (ADDED — сейчас в OpenSpec
этих требований нет):
- Пред-парс имени релиза (`go-ptn`).
- Разбор сигналов LLM в структурированный план (схема: `type`, `title`,
  `original_title`, `year`, `provider_hint`, `files[]` с per-file `season`/
  `episode`, `confidence`).
- Провайдер LLM за абстракцией (`openai-compat`, JSON-mode, ретраи с передачей
  ошибки/схемы; неразобранный после ретраев → review, не failed).
- Модель уверенности и решение auto/review (авто только при подтверждённом матче
  в базе + структурная валидация + согласованность с пред-парсом).
- Роли файлов на краях (sample/extra/ignore, привязка внешних субтитров).

ADDED в `metadata-match` (сам поиск/подтверждение, backfill из `recognition.md`
§3, помимо 4 перенесённых):
- Поиск записи в TMDB/TVDB/TVMaze, сбор кандидатов с дедупом `provider:id`.
- Подтверждение единичного сильного матча → `provider`/`provider_id`/канон. имя/год.
- Опциональность баз: нет баз или нет матча → авто-раскладки нет (граница с
  recognition-решением; здесь — что матч не подтверждён).

### D3. `review` как отдельный capability

Переносим из `web-ui`:

| Текущее требование (web-ui) | Назначение |
|---|---|
| Единый список источников совпадения на ревью | → `review` |
| Ручное добавление источника по id или URL | → `review` |
| Предпросмотр полей источника до фиксации выбора | → `review` |

`Матч с записью метабазы ссылкой` **остаётся в web-ui** — это отображение на
странице загрузки, а не действие ревью.

ADDED в `review` (миграция `docs/specs/review-ux.md`):
- Триггеры входа в review с явной причиной.
- Команды: Применить, Уточнить (подсказка+перераспознавание), Распознать заново,
  Тип, Игнор файла, Позже, Отклонить, Undo, Привязать заново.
- Подсказка (мягкая, интерпретирует LLM) vs override (жёсткий пин;
  перераспознавание не затирает).
- Единый список источников (нейронка наравне с кандидатами) + ручное добавление
  + предпросмотр «превью = применение» (перенесены из web-ui, п. выше).
- Разделение труда транспортов (веб — точные правки, Telegram — быстрые действия/
  эскалация в веб); одно состояние ревью, команды сериализует worker.

### D4. Миграция `file-layout`, `download-tracking`, `notifications` из docs/specs

**`file-layout`** ← `docs/specs/jellyfin-layout.md`:
- Целевые имена фильмов (`Название (Год) [providerid-…]`).
- Целевые имена сериалов (папка с provider-id, `Season xx`, `SxxEyy`).
- Сопоставление источник→цель хардлинками (`save_path`+относит. имя; mkdir 0755).
- Санитизация целевого имени и запрет выхода за библиотеку.
- Never-overwrite (тот же inode → готово; другой файл → коллизия → review).
- Copy-fallback при невозможности хардлинка.

**Владение целевым путём** (`superseded`) и **безопасный undo** (`nlink<=1` →
`ErrLastCopy`) в `file-layout` НЕ дублируем: их доминирующая забота — сверка с
реальностью (присутствие цели определяется по владению; отказ Undo при пропавшем
источнике), и они уже живут более полными версиями в `state-reconciliation`.
`file-layout` описывает акт прямой раскладки; на владение/undo он опирается,
оставляя их дом в `state-reconciliation` (см. ревью дизайна: устранение дубля).

**`download-tracking`** ← `docs/specs/workflow.md` (прямой путь; сверка
разложенного остаётся в `state-reconciliation`):
- Поллинг qBittorrent и сопоставление его состояний с нашими.
- Готовность только когда файлы на месте (не `moving`/`checking*`).
- Таймауты-предохранители: `metaDL` > `magnet_timeout` → failed; `stalledDL` >
  `stuck_after` → stuck; базис возраста — `added_on` (переживает retry/усыновление).
- Ошибка qBit (`error`/`missingFiles`) → failed (`qbit_error`).
- Усыновление раздач по категории **или** тегу, которых нет в БД → `downloading`.
- Владелец переходов — worker под per-download блокировкой (FSM).

**`notifications`** ← `workflow.md` + `state-reconciliation`:
- Уведомление автора о падении (`failed`/`stuck`), включая приёмный `qbit_add`
  мимо поллинга.
- Дебаунс повторных падений одной задачи (мерцающий stalled не спамит).
- Пинг о входе в review и о готовности.
- Уведомление о рассинхроне (перенос из `state-reconciliation`).

| Текущее требование (state-reconciliation) | Назначение |
|---|---|
| Уведомление о рассинхроне | → `notifications` |
| (остальные 11) | остаются `state-reconciliation` |

### D5. `identity` → инфраструктура id; приём → `ingest`

| Текущее требование (identity) | Назначение |
|---|---|
| ULID как первичный ключ сущностей | остаётся `identity` |
| Нормализация и валидация id на входных границах | остаётся `identity` |
| Множество инфохэшей загрузки | → `ingest` |
| Дедупликация приёма по любому из хешей | → `ingest` |
| Атомарность возврата загрузки в активное состояние | → `ingest` |
| Корреляция сущностей в логах | остаётся `identity` |
| Миграция существующих записей | остаётся `identity` |

Примечание: `Атомарность возврата в активное состояние` используется и «Привязать
заново» (review) — но это инвариант приёма/активации загрузки, поэтому его дом —
`ingest`; review на него ссылается.

### D6. Формулировки — эквивалентный перенос

При ADDED в целевой capability текст берём из исходного требования (или из
`docs/specs/` при backfill), сохраняя нормативную силу (SHALL/MUST) и сценарии.
Правки — только связочные (ссылки на соседние capability), не смысловые. Это
делает `openspec archive` безопасным: живые спеки после влития эквивалентны сумме
прежних.

## Risks / Trade-offs

- **Большой diff, риск потерять требование при переносе** → Перенос по таблицам
  D2–D5 (чек-лист: каждое исходное требование учтено — либо STAY, либо REMOVED+
  ADDED). `openspec validate --strict` + сверка счётчика требований до/после.
- **Расхождение docs/specs ↔ openspec после переезда** → В `docs/specs/`
  мигрированных файлов ставим шапку «источник истины переехал в
  `openspec/specs/<cap>`»; содержимое не дублируем.
- **Граница recognition ↔ metadata-match может «поплыть» на будущих задачах**
  (сила совпадения кандидата — идея беклога) → Сейчас фиксируем по действию;
  дальнейшее уточнение — отдельным change.
- **Пробел: у `ingest` нет формального требования на сам приём** (парс magnet →
  завести download → отдать в qBittorrent) — сейчас поведение не выражено
  требованием ни в одной спеке → см. Open Questions.

## Migration Plan

1. Дельты change: ADDED в новых/целевых спеках, REMOVED в исходных (D1).
2. `openspec validate --strict refactor-capability-boundaries`.
3. Ревью дизайна (этот документ) — **чекпоинт до написания всех дельт**.
4. После апрува — генерация дельта-спек, повторная валидация.
5. Пометки о переезде в `docs/specs/` мигрированных файлов; снять пункт беклога.
6. `openspec archive` — влить дельты в `openspec/specs/`.

Откат: change не тронул код; отмена = удалить директорию change (спеки не влиты до
archive).

## Resolved Questions

1. **Ядро приёма в `ingest` — ДА.** Добавляем ADDED «Приём источника и заведение
   загрузки» (backfill из `architecture.md` → «Транспорты»): парс magnet → дедуп →
   завести `download`+`download_infohash` → отдать в qBittorrent; ошибка добавления
   → `failed` (`qbit_add`). Иначе `ingest` остаётся про имя+инфохэши без ядра.
2. **«Секция раздачи на странице загрузки» — остаётся в `live-status`** (меняется
   вместе с телеметрией).
3. **Один change** (решение автора). При необходимости порядок дельт разложим на
   этапе apply.