jellybit/openspec/changes/large-release-recognition/design.md

## Context

Распознавание собирает промпт в `internal/recognize/prompt.go` и разбирает ответ в
`validate.go`. Список файлов печатается нумерованным (`1. путь (размер)`), но номер
служит только человеку: модель обязана вернуть `files[].src` дословной копией пути, а
`validateSchema` ищет эту строку среди реальных файлов торрента (`validate.go:75`). Это и
есть главный инвариант безопасности недоверенного выхода: сослаться на посторонний путь
нельзя.

Цена контракта видна на больших сериальных паках. Путь вида
`Отчаянные домохозяйки (Сезон 1-8 из 8) Дубляж/Сезон 8/Desperate.Housewives.S08E13.WEB-DLRip.Rutracker.org.avi`
— около 70 токенов на кириллице; с ролью и номерами элемент плана стоит ~85 выходных
токенов. Раздача на 180 файлов требует ~15k токенов ответа при зашитом
`defaultMaxTokens = 4000`, а список в промпте заранее подрезан `defaultMaxFiles = 100`.
Ни то, ни другое в конфиг не выведено. Отсюда все наблюдаемые симптомы: ровно 100 файлов
в плане, невидимые 80, сорок строк причин про пропуски серий.

Вход при этом не жмёт: 180 путей — это 12–15k токенов промпта, для рабочей модели
(`deepseek-v4-flash` через bothub) это не проблема. Дорог и хрупок именно ответ, и дорог
он ровно тем, что модель переписывает наши же строки.

Дополнительное ограничение задаёт следующий этап: разметку файлов будет проверять
детерминированный разбор имён, а для этого источники должны остаться независимыми. Всё,
что похоже на «подсказать модели наш ответ», в этом change недопустимо.

## Goals / Non-Goals

**Goals:**

- Раздача на сотни файлов распознаётся целиком, без усечения списка и без обрыва ответа.
- Ошибка модели видна: непокрытые файлы показаны, покрытие названо числом.
- Лимиты распознавания настраиваются на проде без пересборки.
- Инвариант «`files[].src` — реальный файл торрента» не ослабевает.
- Цена неудачной попытки не растёт вместе с размером раздачи.

**Non-Goals:**

- Детерминированный разбор сезона/серии из имён файлов и сверка с моделью — этап B.
- Батчирование запроса по пачкам файлов: при компактном формате ответа нужды нет, а
  склейка шапки между пачками добавляет свой класс расхождений.
- Групповка раскладки по сезонам со свёрткой в UI: раздача на 180 строк читается, если
  строки упорядочены; свёртка — отдельная задача интерфейса.
- Пересмотр модели уверенности и гейта авто-раскладки. Единственное исключение — новая
  причина покрытия, и она заведена так, чтобы гейт не двигать (см. решение ниже);
  всё остальное в решении auto/review остаётся как есть.

## Decisions

### Файл адресуется номером строки нашего списка

`files[]` несёт `i` — номер из напечатанного нами перечня (1-based, в порядке печати).
`src` заполняет резолв на разборе: `in.Files[i-1].Path`. Валидация вырождается в проверку
диапазона, и посторонний путь становится невыразимым — инвариант усиливается, а не
слабеет. Выход падает до ~14 токенов на файл: 180 файлов укладываются в 2.5k, то есть в
нынешний потолок даже без его подъёма.

Альтернативы:

- *Оставить дословный `src`, подняв лимиты.* Отвергнуто: 15k выходных токенов — это минуты
  генерации при `[llm].timeout = 120s`, риск упереться в потолок ответа провайдера и
  сохранение главного источника отбраковки (одна опечатка в одном из 180 путей роняет
  весь план, дальше correction-ретрай целиком).
- *Индекс файла из qBittorrent.* Отвергнуто: `qbt.File` отдаёт только `name` и `size`
  (`internal/qbt/qbt.go:86`), собственного индекса у нас нет, а порядок ответа API как
  контракт нигде не зафиксирован. Номер строки собственного списка не зависит от чужого
  API вовсе.
- *Короткий хеш пути.* Отвергнуто: длиннее индекса в токенах и хуже читается человеком в
  логах и сыром ответе.

### Негодный элемент отбрасывается, план живёт

Номер вне диапазона, повторная адресация одного файла, элемент без номера и без пути —
всё это отбраковывает **элемент**, а не план: остальные файлы остаются, задача уходит в
`review` с причиной, называющей отброшенное. Первоначальный вариант «отклонять план
целиком» отвергнут: он воспроизводит ровно тот отказ, против которого затевается change
— одна ошибка в одном из 180 элементов роняет всю работу и запускает correction-ретрай.
Решение приведено к действующей норме `recognition` («Роли файлов на краях раздачи»):
неоднозначность нумерации эскалируется в `review`, а не разрешается молча и не роняет
разбор. Порог здравого смысла — план, где не осталось ни одного годного файла, считается
неразобранным.

При повторной адресации побеждает первый элемент: иначе два элемента претендуют на один
файл, а раскладка сделала бы два хардлинка с одного источника на две серии.

### Номер главенствует над путём, а расхождение — сигнал

Элемент, несущий и `i`, и `src`, резолвится по номеру. Несовпадение присланного пути с
резолвом даёт причину ухода в `review`, а не молчаливое затирание: модель, назвавшая обе
стороны, бесплатно предъявляет нам сверку против главного риска этого change — сдвига
индекса. Одна ветка в разборе покупает оракул, который иначе появился бы только в этапе B.

### Повторная попытка не переприсылает список файлов

Сегодня `Recognize` дописывает в диалог сырой ответ и `correctionMessage`, а тот печатает
список файлов заново (`recognize.go:243`, `prompt.go:180`). При зашитом лимите в 100
файлов это терпимо; со снятым лимитом четвёртая попытка несла бы четыре копии списка —
50–60k входных токенов, то есть изменение, чья цель «раздача на сотни файлов
распознаётся целиком», удорожало бы её неудачу. Индексная адресация это и снимает: номера
названы в первом сообщении диалога и сохраняют смысл на всех попытках, поэтому
correction-сообщение несёт только ошибку и схему.

### Порядок списка — свойство узла, а не вызывающего

`Recognize` приводит полученный список файлов к детерминированному порядку сам (сортировка
по пути), и печать промпта с резолвом индексов идут по одному и тому же срезу. Сортировка
у вызывающего отвергнута: сборка `recognize.Input` не единственная — кроме воркера
(`internal/worker/review.go:126`) её делает CLI `jellybit recognize --dry-run`
(`cmd/jellybit/recognize.go:101`), и путь, не получивший сортировки, печатал бы номера,
означающие другие файлы. Свойство нормировано на узле — значит и механизируется в узле, а
тест зовёт `Recognize`, а не его вызывающего.

Внутри торрента путь уникален, так что порядок воспроизводим между вызовами: повторное
распознавание из ревью не сдвинет привязку. Полагаться на порядок ответа qBittorrent
нельзя — он не обещан. Побочный эффект приятный: файлы одного сезона идут в промпте
подряд.

### Старый формат принимается как запасной

Пришёл `i` — резолвим; пришёл `src` — валидируем как сегодня. Модель, повторившая формат
из прежних примеров, не должна стоить нам correction-ретрая. Ветка с `src` остаётся и как
страховка на случай, если индексная разметка окажется хуже на каких-то раздачах: откат —
это смена схемы в промпте, без правки разбора.

### Обрыв генерации — отдельная причина, а не мусор

`llm.Response` доводит `finish_reason` до `recognize` (сейчас поле разбирается в
`internal/llm/openai.go:97` и выбрасывается). Обрыв по длине даёт review с причиной
«ответ модели обрезан» и не повторяется ни тем же промптом, ни его вариантом: обрыв
означает, что ответ не поместился, а не что модель ошиблась.

### Лимиты — в конфиг, дефолты соразмерны промпту

`[recognition].max_files` и `[recognition].max_tokens`, дефолты 500 и 8000. Прежний
`max_files` остаётся предохранителем от аномальной раздачи, а не рабочим ограничением, но
его значение обязано соответствовать той же арифметике, которой обоснована безопасность
изменения: 180 файлов — 12–15k входных токенов, значит 500 файлов — порядка 35k, что
модель принимает. Дефолт 1000 отвергнут именно поэтому: предохранитель, пропускающий
раздачу, которая упрётся в контекст, не предохраняет, а лишь меняет внятную причину
«список усечён» на 4xx с текстом провайдера. Отказ по размеру запроса называется
отдельной причиной.

### Покрытие плана показывается всегда, блокирует — только по видеофайлу

`Decision.Auto` — это `len(reasons) == 0` (`validate.go:124`), поэтому любая новая причина
автоматически становится блокирующей. Промпт при этом требует покрыть «каждый значимый
файл» (`prompt.go:55`): модель вправе опустить `.nfo`, скриншоты и `.txt`, и на типовой
фильмовой раздаче покрытие штатно меньше сотни процентов. Причина покрытия в общем виде
выключила бы авто-раскладку по всей системе — притом что её пересмотр объявлен Non-Goal.

Поэтому покрытие разделено: число «в плане N из M» показывается человеку всегда, а
блокирует только непокрытый **видеофайл** — он означает потерянную серию или фильм.
Файлы-спутники в блокирующую часть не входят. Отсюда требуется различать видео по
расширению — в проекте такого места сегодня нет (`grep` по `internal` не находит ни
одного упоминания `.srt`/`.mkv` как класса), поэтому перечень заводится один раз и рядом
с ролями файлов, а не расползается по вызывающим.

Альтернатива «потребовать от модели полного покрытия, мусор — ролью `ignore`» отвергнута:
она перекладывает на выход модели ещё сотню элементов на больших паках — ровно ту
стоимость, которую change снимает.

### Файлы вне плана показывает раскладка

`buildFileRows` (`internal/httpapi/files.go:25`) обходит `plan.Files`; файл, который
модель не включила в план, не отображается нигде. Обход разворачивается на файлы
торрента, план подмешивается по `src`. Файл без записи в плане получает явную строку «не
в плане». Порядок строк определён полностью: разложенные (сезон, серия, путь) → файлы
плана без цели (`extra`/`sample`/`ignore`, по пути) → файлы вне плана (по пути). Пустые
`season`/`episode` — указатели, и свёрнутые в ноль они поставили бы семплы и скриншоты
перед первым сезоном; поэтому место таких файлов задано явно, а не выводится из
умолчания.

Колонка `#` виджета сейчас печатает порядковый номер строки
(`web/templates/partials/layout_widget.html:8`). После изменения номер файла несёт
контракт: он попадает в сырой ответ модели и в логи, и человек, разбирающий «модель
адресовала файл 13», обязан увидеть в раскладке тот же файл. Значит колонка либо
показывает номер из списка распознавания, либо не показывается вовсе.

Отсюда зависимость по данным: странице нужен список файлов торрента, а не только
сохранённый план. Живой запрос в qBittorrent на рендере — лишний поход в чужой сервис на
каждый показ; список файлов приходит вместе с распознаванием и сохраняется рядом с
планом (миграция `0012`, колонка в `recognition`). Записи, созданные раньше, списка не
имеют — и виджет обязан это **сказать**, а не молча показать план как полный перечень:
иначе неполнота неотличима от честного «файлов вне плана нет». Раздача, ради которой
change делается, уже лежит в `review`, и полный список она получит при повторном
распознавании из ревью.

### Причины ревью сворачиваются

`seriesWarnings` (`validate.go:186`) даёт строку на каждый разрыв нумерации — на паке из
8 сезонов это 40+ строк. Вместо этого: одна строка на сезон с перечнем недостающих серий
и одна сводная строка покрытия. Смысл причин не меняется, меняется форма: причина должна
читаться человеком в ревью с одного взгляда.

## Risks / Trade-offs

- **Ошибка модели в индексе становится тихой.** Перепутанный путь сегодня чаще всего не
  совпадёт ни с одним файлом и ответ будет отбракован громко; сдвиг индекса на единицу
  даёт валидный, но не тот файл → серия уедет на соседнее место.
  *Смягчение:* отбраковка повторной адресации, сверка присланного `src` с резолвом номера,
  когда модель прислала оба, сводка покрытия в причинах и сверка числа серий с метабазой.
  Полное смягчение — перекрёстная проверка с разбором имени файла в этапе B, ради которой
  источники и держатся независимыми.
- **Разделение покрытия по типу файла держится на перечне расширений.** Незнакомое
  расширение видео попадёт в спутники, и потерянная серия не заблокирует авто.
  *Смягчение:* перечень заводится в одном месте и покрывается тестом; сверка числа серий
  с метабазой ловит потерю независимо от расширения.
- **Список файлов теперь хранится рядом с планом.** Рост объёма БД на больших раздачах и
  ещё одно место, которое может разойтись с реальностью: раздача, переименованная в
  qBittorrent после распознавания, даст раскладку по устаревшему снимку.
  *Смягчение:* хранится то, что и так получено при распознавании; это снимок момента
  распознавания, и реальная раскладка всё равно идёт от плана. Записи без снимка виджет
  называет явно.
- **Схема в промпте меняется — качество разметки может просесть.** Модель разметит 180
  файлов хуже, чем 100, просто потому что их больше.
  *Смягчение:* мерить нечем — размеченного корпуса нет и не будет (`tasks/REJECTED.md`,
  2026-08-06), поэтому проверка ручная на той самой раздаче, а откат дешёвый (ветка `src`
  сохранена).
- **Дефолт `max_tokens = 8000` может не поддержаться эндпоинтом.** Потолок ответа у
  провайдера ниже нашего дефолта — получим обрыв.
  *Смягчение:* обрыв теперь называется явной причиной, а лимит крутится в конфиге без
  пересборки.
- **Множитель стоимости попыток остаётся.** `correctionMessage` снял рост промпта
  *внутри* диалога, но полный промпт всё равно уходит заново на каждой **транспортной**
  попытке: `internal/llm` держит зашитые `maxAttempts = 3` (сетевой сбой, 429, 5xx), и
  они умножаются на бюджет переразбора `[llm].max_retries` (дефолт 3, то есть 1 + 3
  запроса). В худшем случае — до 12 отправок, а промпт после подъёма `max_files` со 100
  до 500 стал впятеро тяжелее. Плюс `[llm].timeout` (120 s) при удвоенном `max_tokens`
  (4000 → 8000) не пересматривался: генерация вдвое длиннее ответа может не уложиться в
  прежнее окно, и тогда таймаут читается как транспортный сбой и уходит в ретрай.
  *Смягчение:* оба предела в конфиге и крутятся без пересборки; согласование `timeout` с
  `max_tokens` проверяется на живом кейсе (задача 9.3), а не выводится расчётом.