jellybit/openspec/changes/archive/2026-08-06-ingest-nits/design.md

## Context

Ревью приёма 2026-07-08 (Fable) оставило четыре нити — N1, N3, N4, N5. Они не
связаны причиной, но связаны местом: все четыре живут на пути «источник →
загрузка → добавление в qBittorrent» и все четыре читаются одним заходом.
Изменение косметическое по последствиям и трогает пять пакетов, поэтому решения
о **месте** правки важнее самих правок.

Текущее состояние, проверенное по коду:

- `internal/torrent/torrent.go:72` — `DisplayName: meta.BestName()`.
  **Постановка задачи и первая редакция этого дизайна исходили из неверного
  факта** — будто библиотека сама подставляет `-` безымянной раздаче. Проверено
  по исходникам `anacrolix/torrent@v1.61.0`: `BestName()`
  (`metainfo/info.go:200-205`) возвращает `NameUtf8`, иначе `Name`, иначе пустую
  строку; `NoName = "-"` (`info.go:44`) присваивается только в
  `BuildFromFilePath` при **авторинге** раздачи из вырожденного пути. Значит
  `-` доходит до нас лишь тогда, когда раздача объявила его полем `name` сама
  (та самая конвенция «имени нет», ради совместимости с которой библиотека
  константу и экспортирует). Раздача **без** поля `name` даёт пустое имя, и этот
  случай код уже отрабатывает верно. Потребителей `DisplayName` три:
  `Info.Context()` (строка названия), `ingest.parse` (`source_ref`,
  единственный, кто про `-` знает) и `worker.sourceAddParts` (подсказка имени
  для `namer`, то есть вход LLM).
- `internal/ingest/ingest.go` — все выходы с ошибкой возвращают `Result{}`
  (строки 74–75, 86, 106–107 на момент ревью). Комментарии
  `internal/httpapi/httpapi.go:574` и `internal/tgbot/bot.go:256` описывают
  прежний контракт «сбой после создания задачи → непустой `DownloadID`».
- `internal/qbt/qbt.go:246` — ветка `Fails.` пишет `call.Failure` со счётчиками
  `urls`/`torrents`. Логгер клиент берёт из `ctx` (`logctx.FromOr`). Из двух
  вызовов `qbt.Add` фоновый (`worker.go:511`) идёт со scoped-логгером
  (`cctx`, `worker.go:415`), а `Retry` (`worker.go:1084`) — с сырым `ctx`
  транспорта: `Retry` не присваивает `ctx = w.scoped(…)`, в отличие от `Delete`
  (`review.go:619`), и трижды строит scoped-логгер одноразово прямо в аргументе
  записи. **Первая редакция этого дизайна считала `Retry` единственной такой
  командой — ревью изменения показало, что их семь** (см. «Что изменилось после
  ревью изменения»).
- `anacrolix/torrent v1.61.0`: `bencode/decode.go:17` задаёт
  `DefaultDecodeMaxStrLen = 1<<27-1`; `parseStringLength` (там же, `:211`)
  сверяет объявленную длину с этим потолком, а `parseString` (`:250`, `:258`)
  делает `make([]byte, length)` **до** чтения байтов. `metainfo.Load`
  (`metainfo/metainfo.go:35-37`) создаёт декодер без переопределения
  `MaxStrLen`, то есть с потолком по умолчанию.

## Goals / Non-Goals

**Goals:**

- Сентинел «без имени» не покидает пакет разбора — ни одному потребителю ниже
  по потоку не нужно про него знать.
- Комментарии транспортов описывают контракт `Ingest`, который есть, и контракт
  подтверждён тестом, а не только чтением.
- Запись о неуспешном добавлении в qBittorrent коррелируется с загрузкой на
  **обоих** путях добавления.
- Знание о пределе аллокации bencode записано с провенансом и замером.

**Non-Goals:**

- Не чиним поведение `anacrolix/torrent` — форк, `replace` и собственный
  разборщик bencode вне объёма и вне границы домена.
- Не добавляем клиенту `qbt` знание о доменных сущностях (инфохэш, id загрузки)
  — см. решение 3.
- Не трогаем `files()` и его фолбек на `meta.BestName()` для пути файла: это
  вырожденный случай (файл без пути **и** раздача без имени), к контексту
  распознавания отношения не имеющий.
- Не переписываем `Cancel`/`Dismiss` под ту же форму, что `Retry`: внешних
  вызовов у них нет, требование `identity` их не касается, правка была бы
  churn'ом (записано в «Открытые вопросы»).

## Decisions

### 1. N1 — нормализация имени стоит в `torrent.Parse`, а не в `Context()`

Задача формулировала фикс как «фильтровать `-` и в `Context()`». Это лечит
симптом: `DisplayName` остаётся заражённым, а знание о вырожденном имени
копируется в третье место. Потребителей у поля три, и третий
(`worker.sourceAddParts` → подсказка имени для LLM) в постановке не назван, хотя
страдает так же: `-` уезжает во вход вывода отображаемого имени.

Решение: нормализовать в `Parse` — `DisplayName` пуст, если разобранное имя
равно `metainfo.NoName`. Тогда `Context()` уже имеет проверку `name != ""` и не
меняется вовсе, `ingest.parse` теряет ветку `|| ref == "-"`, а подсказка имени
чинится без единой строки в `worker`.

Альтернатива «фильтровать в трёх местах» отвергнута: три копии знания об одном
вырожденном значении — ровно то, что архитектурный проход называет вторым
способом делать одно и то же. Альтернатива «оставить `-` и научить каждого
потребителя» хуже: потребители появляются, а значение одно.

Сравнение делаем с `metainfo.NoName`, а не со строковым литералом, по одной
причине — библиотека экспортирует константу **именно** затем, чтобы на неё
ссылались («By exposing it in the API we can check for references to this
behaviour», `metainfo/info.go:41-44`). Аргумент «сломается компиляция, а не
поведение» здесь **неверен** и снят: константа строковая, смена её значения
компиляцию не ломает.

Тем же местом закрывается и вторая грязь в строке названия: имя — недоверенный
вход, а контекст читается построчно, поэтому имя со встроенным переводом строки
добавляет в контекст строку, выглядящую как синтезированный нами факт.
Схлопывание разделителей строк уже применяется к комментарию торрента
(`oneLine`), и распространить его на имя — одна строка. **Инъекцией в промпт это
не управляет и управлять не может:** пользовательский текст контекста
многострочен по замыслу и идёт в промпт как есть; правило устраняет
несогласованность (комментарий схлопываем, имя нет), а не заводит защиту.

### 1а. Что изменилось после ревью предложения

Проход `specs` опроверг фактическое основание N1 оракулом — прогоном
крафт-входов через `metainfo.Load`. Из этого следует три правки, уже внесённые
выше и в дельта-спеку:

- формулировка требования говорит про **объявленное раздачей** вырожденное имя,
  а не про сентинел, подставляемый библиотекой;
- случай «раздача без поля `name`» назван отдельно и признан уже работающим —
  под него заводится сценарий и тест, потому что раньше он путался с первым
  (комментарий `internal/torrent/torrent_test.go:224` «info без имени
  (NoName-сентинел)» и есть источник исходной ошибки ревью 2026-07-08);
- критерий приёмки постановки «для безымянного торрента `Context()` не отдаёт
  `-`» выполняется **до** изменения. Это дефект критерия, а не задачи:
  проверяемое им поведение уже верно, а чинится соседнее. В докладе исход
  критерия назван честно, и заодно проверено то, что критерий имел в виду.

### 2. N3 — контракт объявляется в `ingest`, транспорты его не пересказывают

Комментарии в `httpapi` и `tgbot` разошлись с кодом потому, что каждый держал
**свою** копию контракта. Правка «переписать оба комментария» повторяет ту же
конструкцию и разойдётся снова.

Решение: контракт («на любом пути ошибки возвращается нулевой результат»)
объявляется один раз — в доке `ingest.Ingest` и `ingest.Result` — и
подтверждается тестом в пакете `ingest`. Транспорты получают короткий
комментарий-ссылку и передают в диагностику **пустой** идентификатор, а не
заведомо пустой `res.DownloadID`: значение, которое доказуемо всегда пусто,
прочитанное как «а вдруг непусто», и породило исходную нить.

Альтернатива «оставить `res.DownloadID`, поправить только текст» отвергнута:
код продолжит утверждать обратное тому, что говорит комментарий.

**Контракт держится структурой, а не перечнем веток** (найдено проходом
`rubric`): `Ingest` получает именованный возврат и один `defer`, обнуляющий
результат при ненулевой ошибке. Иначе лекарство повторяет болезнь — сегодня три
ветки возврата аккуратны, а завтра четвёртая вернёт полузаполненный результат,
и тест, перечисляющий три известных класса отказа, этого не заметит. Тест
сравнивает результат с нулевым значением **целиком**, а не по полю
`DownloadID`.

Вызовов приёма на транспортах **три**, а не два (найдено проходом `specs`):
REST `handleAPIAdd`, веб-форма `handleUIAdd` и `tgbot.ingestAndReply`. Третий в
первой редакции задач отсутствовал — добавлен, иначе требование «транспорты не
обещают идентификатора, которого нет» оказалось бы выполненным на две трети.

Корреляционный ключ у отказа приёма **разный по транспортам**, и требование
называет это прямо: HTTP и веб-UI дают `request_id`, Telegram не даёт ничего
(`opErr` при пустом идентификаторе возвращает текст без ключа). Это не
регрессия — сегодня `res.DownloadID` уже всегда пуст, и наблюдаемое поведение
Telegram не меняется. Но пробел реален, и заводить ли Telegram-транспорту
собственный ключ — записанный вопрос, а не молчаливое «потом».

### 3. N4 — корреляция приходит из `ctx`, полей клиенту не добавляем

Задача предлагала «логировать хеши/первые байты». Клиент `qbt` инфохэша не
знает: на magnet-ветке у него ссылка, на torrent-ветке — байты, и вычислить хеш
он мог бы только собственным разбором источника, а разбор источника — единая
точка проекта (`internal/magnet`, `internal/torrent`). Поле `Infohash` в
`AddRequest` завело бы второй канал корреляции рядом со scoped-логгером и жило
бы только ради лога.

Настоящая причина того, что оператор не находит запись: `Retry` не кладёт
scoped-логгер загрузки в `ctx`. Фоновый путь добавления это делает и запись
`Fails.` там уже несёт `download_id` и `infohash`; путь retry — нет. То есть N4
— не «клиент мало пишет», а «один вызывающий не выполнил обязанность, которую
выполняют остальные».

Решение: `Retry` присваивает `ctx = w.scoped(ctx, capReview, id,
d.PrimaryInfohash())` сразу после чтения загрузки, а одноразовые `w.scoped(…)`
и ручные `w.log.…` внутри него схлопываются в `logctx.From(ctx)`. Обязанность
вызывающего закрепляется требованием в `identity` — **ограниченным вызовом
внешнего сервиса**, а не «первым вызовом, способным что-либо записать» (найдено
проходами `architecture` и `specs`): в широкой формулировке требование объявляло
бы нарушителями `Cancel` и `Dismiss`, которые этот же change сознательно не
трогает, и нормативная спека стала бы ложной в момент архивации.

Побочный эффект присвоения назван заранее, чтобы на чекпоинте 2 он не читался
регрессией: поля `capability`/`download_id`/`infohash` появятся также у
`qbt.Torrents` из `torrentByInfohash`, у `logCmd` и у предупреждений внутри
метода. Это и есть цель. Двойной `download_id` в `logCmd` (из логгера и явным
аргументом) — существующее поведение пути `Delete`, прецедент есть, чистить его
здесь не будем.

Тест записи о `Fails.` проверяет не только наличие полей, но и **отсутствие
лишнего**: значение отправленного magnet с узнаваемым `passkey` в записи не
встречается ни в одном поле (найдено проходом `rubric`). Инвариант «секреты не
попадают в логи» — `major`, а `add` — единственный вызов `qbt`, через который
magnet-URI приватного трекера физически проходит.

«Первые байты источника» в лог не идут: для magnet это часть URI (шум, а на
приватном трекере — потенциально чувствительный passkey), для torrent — начало
bencode, диагностической ценности не несущее.

Причину отказа qBittorrent мы при этом не получаем и не выдумываем: `Fails.`
причины не несёт, и никакого «это был дубль» из него не выводится. Запись честно
остаётся «отказ без причины», но становится привязанной к загрузке.

### 4. N5 — исход пункта запись, а не код

Пункт про аллокации bencode правке не подлежит: это чужая библиотека, поведение
ограничено (потолок ~128 MiB) и завершается ошибкой, а не порчей данных.
Записываем наблюдение в `docs/research/` с провенансом (версия, файл:строка) и
**замером**, снятым воспроизводимой командой во временном каталоге, а не
оценкой из головы. Требование каталога разведки — «каждый вывод с числами и
командой, которой получен» — выполняется буквально.

Порог, ниже которого пункт стал бы дефектом: если бы аллокация не была
ограничена или не завершалась ошибкой. Это проверяется замером, а не
рассуждением, — потому замер и делается.

Записка получает **условие устаревания** («перепроверить при обновлении
`anacrolix/torrent`»): наблюдение о коде зависимости протухает от бампа
`go.mod`, в отличие от наблюдения о формате провода, которое живёт своей жизнью.
Вводная `docs/research/README.md` расширяется на полстроки, чтобы каталог честно
включал и такие наблюдения (найдено проходом `architecture`). Туда же уезжает
второе наблюдение о той же библиотеке — про `BestName`/`NoName`: цена нити N1
ровно в том, что этого наблюдения не было записано нигде.

## Risks / Trade-offs

- **Нормализация `DisplayName` меняет вход `namer` для безымянных раздач** →
  раньше в подсказку уходил `-`, теперь пусто. Это улучшение (вход LLM чище), но
  формально смена поведения. Митигация: путь покрыт тестом приёма на безымянной
  раздаче; `namer` пустую подсказку и так обрабатывает (magnet без `dn` даёт то
  же самое).
- **Scoped-логгер в `Retry` добавляет поля к записям, которых там раньше не
  было** → тесты, сверяющие записи журнала на пути retry, могут разойтись.
  Митигация: гейт (`test`, `flaky`) ловит это детерминированно.
- **Замер аллокаций bencode делается на синтетическом входе** → он показывает
  поведение декодера, а не профиль реального `.torrent`. Митигация: в записке
  прямо сказано, что число получено на крафт-входе, и приведена команда.
- **Пустой идентификатор в диагностике транспорта** → если контракт `Ingest`
  когда-нибудь начнёт возвращать id на ошибке, транспорты его не покажут.
  Митигация: контракт закреплён спекой и тестом, менять его придётся осознанно
  и вместе с транспортами.

## Migration Plan

Миграции нет: схема БД, конфигурация, HTTP-контракт и тексты Telegram не
меняются. Нумерованных артефактов изменение не добавляет. Откат — обычный
revert коммита.

## Что изменилось после ревью изменения (чекпоинт 2)

Профиль `deep`, семь проходов. Отработано инлайн:

- **Порядок в `displayName` был неверен** — сравнение с сентинелом стояло до
  схлопывания, и имя `" - "` превращалось в `-` уже после проверки. Три прохода
  (`specs`, `adversary`, `reimpl`) нашли это независимо, два принесли падающий
  тест; `adversary` показал, что это **регрессия против `master`**, где фолбек
  `source_ref` на имя файла срабатывал. Порядок исправлен и закреплён в спеке.
- **Команд без scoped-логгера оказалось семь, а не одна.** Кроме `Retry`,
  внешний сервис до постановки логгера зовут `Relink`, `Rerecognize`, `Refine`
  (qBittorrent через `ensureSourceReady`) и `ChooseCandidate`,
  `AddManualSource`, `SetProviderID` (метабаза через `recognizer.Director`).
  Развилка разрешена в пользу починки всех семи: узкая альтернатива требовала
  сузить требование `identity` до одного пути, и тогда нормативная спека
  фиксировала бы слепоту как норму. Конструкция, снимающая класс целиком
  (обёртка входа команд), — записанный вопрос ниже.
- Добавлены недостающие оракулы: отказ приёма на обоих HTTP-транспортах
  коррелируется по `request_id`; best-effort ветки `Retry` исполняются тестами.
- Записка разведки получила текст программы замера и **разграничение
  `TotalAlloc` против RSS**: замер `ops` показал, что физическая память при
  деградационном пути не расходуется вовсе, и вывод записки от этого становится
  сильнее, а не слабее.

## Open Questions

- **Заводить ли обёртку входа команд воркера, делающую пропуск scoped-логгера
  невозможным?** Пролог всех ~18 публичных команд однороден: `defer logCmd` →
  `w.mu.Lock` → чтение загрузки → проверка состояния → `ctx = w.scoped(…)`.
  Последний шаг держится дисциплиной, и дисциплина уже дала семь промахов из
  ~дюжины — то есть это не гипотеза, а измеренная частота. Варианты:
  (а) обёртка `w.withDownload(ctx, op, capability, id, allowedStates, fn)` —
  пропуск невозможен по построению, цена: правка всех команд разом и потеря
  гибкости там, где capability меняется по ходу метода (`review.go` дважды
  пере-скопливает под `capFileLayout`); (б) тест-перебор публичных команд,
  краснеющий на команде без scope, — дешевле и не трогает продовый код, но
  ловит только известную форму нарушения; (в) оставить дисциплину. Пока
  решения нет, стоит (в) — все известные нарушения починены. Рекомендация —
  (б) отдельной задачей: механизация без переписывания, ровно по процедуре
  промоута «находка → конвенция → правило».
- **Нужен ли Telegram-транспорту собственный корреляционный ключ у отказа
  приёма?** Сегодня `opErr` при пустом идентификаторе возвращает текст без
  ключа, а конвенция (`docs/conventions/errors.md`, «Граница и трансляция»)
  требует к сообщению **корреляционный ключ** — `download_id` либо
  `request_id`. На пути приёма из Telegram нет ни того, ни другого, и это
  главный сценарий паспорта. Варианты: (а) завести идентификатор запроса на
  входе обработчика апдейта (или взять `update_id`) и класть его в scoped-логгер
  и в текст отказа — цена в том, что рядом с существующей корреляцией по
  `download_id`/`infohash` появляется второй канал, ровно тот класс, который
  решение 3 отвергло для `qbt`; (б) не заводить ключ, а поднять запись отказа
  разбора с `DEBUG` до `INFO` с `infohash`, и тогда искать по инфохэшу — дешевле,
  но у пользователя в руках всё равно ничего нет; (в) оставить как есть.
  Пока решения нет, стоит (в): изменение поведения Telegram не меняет и
  регрессии не вносит. Рекомендация — (б) отдельной задачей: она закрывает
  наблюдаемость, не заводя второго канала корреляции. Пробел существует до этого
  изменения и им не создан.
- **Приводить ли `Cancel` и `Dismiss` к той же форме, что `Retry` и `Delete`
  (присвоение `ctx = w.scoped(…)` в начале команды вместо одноразового
  построения логгера в аргументе записи)?** Варианты: (а) привести — правило
  «команда воркера скопливает `ctx` один раз» становится однородным, цена —
  правка двух методов без наблюдаемого эффекта, риск разойтись с тестами
  журнала; (б) не трогать — у этих команд нет внешних вызовов, поэтому
  наблюдаемой разницы нет, цена — форма остаётся неоднородной, и следующий
  вызывающий скопирует ту из двух, что попалась. Пока решения нет, стоит (б):
  изменение закрывает N4 и не расширяется. Рекомендация — (а) отдельной
  задачей-гигиеной, когда в `Cancel`/`Dismiss` появится первый внешний вызов;
  раньше этого момента правка не окупается.