jellybit/openspec/changes/archive/2026-08-07-tvdb-title-locale/review/report.md

# Ревью изменения `tvdb-title-locale` — отчёт триажа

Сформирован проходом `review-triage`; записан оркестратором (у прохода запись файлов
заблокирована). В конце добавлена секция «Что сделано по находкам».

## Сводка

**Размер:** малое (один содержательный узел `internal/metadata/tvdb.go` + тривиальная проводка в
`cmd/jellybit/serve.go`, комментарий в `internal/config/config.go`, два документных артефакта).
**Сложность:** незнакомое (дословно сработал проектный триггер `docs/review.md` → «Незнакомое
здесь»: новый источник в слиянии кандидата метабазы — `OriginalTitle` у TVDB становится непустым
и входит новой осью сравнения в `strongMatches`; внешний контракт живым прогоном не подтверждён).
**Метка:** `large` (малое × незнакомое), не спорный случай.
**Режим прогона:** по графу. **Гейт:** зелёный (`BASE=master task gate`, `-race` реально гонялся —
gcc есть; `gitleaks` no leaks; `govulncheck` 0 достижимых).

**Сигнал о заниженной метке:** пришёл от `code` — «сигнала нет, метка `large` адекватна».
`basics` не запускался по плану, второго провенанса нет.

### План разметки с исходом по каждой теме

| тема | дом | глубина | кто закрывает | исход |
|---|---|---|---|---|
| requirements | `openspec/specs/metadata-match/spec.md` + дельта | разбор | `specs` | закрыта, 4 находки (S1–S4) |
| autotests | `CLAUDE.md` → «Гейт» | — | `autotests` | закрыта, 1 находка (A1), отработана до опиниативных проходов |
| conventions | `docs/conventions/README.md` + `config.md` + `logging.md` | разбор | `code` | закрыта, 3 находки (C1–C3) |
| architecture | `docs/architecture.md` → «Единые точки» (+ `docs/passport.md`) | доказательство | `architecture` | закрыта, 3 находки (R1–R3) + 4 пункта «дешевле переделать до мерджа» |
| security | `docs/security.md` | доказательство | `adversary` | закрыта, 4 находки (AD1–AD4); три вопроса темы — вне диффа, не разбирались |
| operations | `docs/architecture.md` → «Эксплуатация» (+ `docs/database.md`) | доказательство | `ops` | закрыта, 1 находка (O1) + 5 снятых замерами гипотез |
| тема проекта | своих тем проекта нет | — | `basics` не запускается | дома у темы нет; отсутствие отчёта согласовано планом |

**Тем без отчёта нет.**

Находок на входе — 17. Различных причин после дедупликации — 10. Крупнейшее слияние: «след не
срабатывает» — пять независимых обнаружений (S1, C1, R1, AD2, O1) плюс S2 как отсутствующий на
него тест. Это не подтверждение: под всеми проходами одна модель с одними априорными; согласие
подняло приоритет, `Confidence` — нет. Оракул добыт триажом отдельно. В основном списке 6
(2 блокирующих + 4 «сейчас»), потолок 3+4 не выбран.

**A1 (закрыта до опиниативных проходов):** гейт краснел по шагу `canon` — задача в спринте с
непустым разделом «Вопросы». Вопрос вынесен задачей-разведкой
`docs/tasks/items/tvdb-search-response-live-check.md`, раздел убран, гейт перегнан.

## Блокирует мердж

### 1. Единственный компенсирующий контроль изменения нем ровно на том риске, ради которого заведён

- Файл: `internal/metadata/tvdb.go:191-205,247-252`; дельта, сценарий «Блок переводов отсутствует
  или пришёл негодной формой»
- Severity: major · Confidence: high
- Оракул: падающий тест на настоящем `TVDB.Search` (httptest-стенд, буфер логгера):
  `translations={"ru":…,"en":…}` → след false FAIL; `null` → false FAIL; `{}` → false FAIL;
  `{"rus":{"name":…}}` → true PASS; `["Дюна"]` → true PASS; поля нет → true PASS.
  Плюс `docs/conventions/logging.md` — «`DEBUG` … в проде выключен», и дефолт `[log].level = "info"`.
- Последствие: два независимых компаундирующих отказа одного механизма. **Предикат:**
  `json.Unmarshal("null", &map[string]string{})` возвращает `err == nil` и `nil`-карту, поэтому для
  `null`, `{}` и **двухбуквенных кодов** признак «разобралось» истинен — а двухбуквенные коды
  `design.md` называет главным риском поимённо. **Уровень:** даже сработавший след при штатном
  деплое не виден. Итог: все названия тихо уедут в фолбэк на английский primary name, и
  единственный заведённый способ это заметить не сработает.
- Найдено проходами: `specs` (S1), `code` (C1), `architecture` (R1), `adversary` (AD2), `ops` (O1)
- Действие: **развилка**. (а) починить предикат и поднять уровень до `WARN`, закрепить тестом, в
  спеке заказывать наблюдаемость, а не уровень; (б) признать детектор нерабочим и снять;
  (в) оставить код, переписать дельту под фактическое поведение. Рекомендация — (а).

### 2. Название из метабазы уезжает в имя каталога Jellyfin дословно, мимо санитайзинга, авто-раскладкой

- Файлы: `internal/metadata/tvdb.go:233-245`; `internal/recognize/recognize.go:261-270`;
  `design.md` → Risks
- Severity: major · Confidence: high
- Оракул: падающий тест на реальном `Recognizer`: `plan.Title` из трёх ZWSP — `auto=true`, тогда как
  `sanitizeTitle` дал бы пустую строку; `"Dune<RLO>gnp.mkv"`, `"Dune\nHACK"`, `"Dunа"` с кириллической
  `а` — все с `auto=true` и все отличаются от того, что дал бы санитайзер. Плюс чтение кода:
  `plan.Title = match.Title` стоит **после** `sanitizePlan`, а гейт сверяет
  `normalize(c.Title) || normalize(c.OriginalTitle)` — проходит по `OriginalTitle`, и значение,
  уезжающее в план, не сверяется ни с чем.
- Последствие: `layout.sanitizeComponent` снимает `/\:*?"<>|` и `< 0x20`, но не трогает категорию
  Cf и не сворачивает гомоглифы. `adversary` показал два визуально неотличимых каталога.
  Инвариант «целевой путь строго под библиотекой» **держится** (проверено на `Dune/../../etc`,
  `" .. "`, `"..."`, 400 символов) — поэтому не `critical`. Класс **пре-существующий**: у TMDB тот
  же путь. Дифф распространяет его на второго провайдера и впервые для TVDB делает поле,
  уезжающее в путь, несверяемым. Отдельно: именно ложной фразой в `design.md` обоснован вывод
  «новой недоверенной границы не появляется», и она архивируется вместе с change.
- Найдено проходами: `adversary` (AD1), независимо — `architecture`
- Действие: **развилка**. Прямой ответ на вопрос задания: **починка кода — урожай, а не дефект
  этой задачи; починка `design.md` — дефект этой задачи и делается инлайн.** Вариант с
  `sanitizeTitle` к `match.Title` меняет поведение уже работающего TMDB и выходит за рамку задачи.
  Рекомендация — поправить документ, завести задачу.

## Стоит исправить сейчас

### 3. Один и тот же байт-в-байт ответ TVDB даёт разное имя каталога от прогона к прогону
- Файл: `internal/metadata/tvdb.go:199-203` · minor · medium (механизм доказан, достижимость нет)
- Оракул: 500 разборов одного тела — `{"rus":"Дюна","RUS":"HACK"}` дал `map[HACK:59 Дюна:441]`;
  `{"rus":"Дюна","ruſ":"HACK"}` → `map[HACK:63 Дюна:437]`.
- Последствие: `for k := range m` по карте (порядок рандомизирован) + `EqualFold`, совпадающий с
  несколькими ключами. Две задачи по одной раздаче в разное время получат разные имена каталогов.
- Сопутствующая правка спеки (провенанс `specs`/S3): регистронезависимый поиск дельтой не заказан
  вовсе — живёт только в `design.md` и строке теста, а `design.md` архивируется.
- Действие: **инлайн**

### 4. Сдвиг границы авто-review подтверждён только рассуждением
- Файл: дельта, сценарий про двух сильных кандидатов; механизм — `internal/recognize/metadata.go`
  · minor · high
- Оракул: в `internal/recognize/metadata_test.go` нет теста, где два кандидата в пределах года и
  один совпадает по `Title`, а другой по `OriginalTitle`.
- Последствие: на счётчике сильных кандидатов держится инвариант «авто-раскладка только при
  подтверждённом матче» (`major`). Регрессия в `strongMatches` гейт не покраснит.
- Действие: **инлайн**

### 5. Поле `language` в логах несёт два разных словаря
- Файлы: `internal/metadata/tvdb.go:251` в паре с `cmd/jellybit/serve.go:109` · nit · high
- Оракул: `docs/conventions/logging.md` → «Поля: словарь имён» — «одно поле — одно имя по всему
  коду». `serve.go` кладёт абстрактный код (`ru`), новая строка — диалект (`rus`).
- Действие: **инлайн**

### 6. Образец конфига после этого изменения говорит про локаль TVDB неправду
- Файл: `config.example.toml`, секция `[metadata.tvdb]` · nit · high
- Оракул: `docs/conventions/config.md` → самодокументируемый образец; у `[metadata.tmdb]` хвост
  про `[general].language` есть, у `[metadata.tvdb]` нет — до change асимметрия была верна.
- Действие: **инлайн**

## Гипотезы без доказательства

1. Достижимость находки 3 (два EqualFold-равных ключа от живого TVDB) не проверена и в рамке
   прогона проверена быть не может.
2. **Основание всего изменения — форма блока `translations` — живым прогоном не подтверждено.**
   Все находки про перевод условны на этом. Единственный оракул — `TestIntegration_TVDB` за
   `TVDB_API_KEY`, прогоняет человек. Отдельно от `specs`: **интеграционный тест печатает
   результат по `Ne Zha`, но ничего не утверждает** — `PASS` с пустым выводом неотличим от
   подтверждения.
3. AD4 (название длиннее ~237 байт уводит задачу в `failed` вместо review) понижено не по
   доказательности (оракул есть: `n=250` → `Apply err=… file name too long`, `results=0`), а по
   принадлежности к диффу: путь не тронут изменением.
4. Согласие пяти проходов по находке 1 — не подтверждение. `Confidence: high` стоит из-за
   падающего теста, добытого триажом, и ни по какой другой причине.

## Promote candidates

1. **Правило `internal/archrules`, связывающее множество кодов языка с мапперами** (провенанс
   `architecture`/R2). Язык вывода живёт в пяти местах четырёх пакетов; тестов, связывающих
   множество с мапперами, нет — забытая ветка молча даст английский вывод. Дешёвый паллиатив:
   строка «язык вывода» в `docs/architecture.md` → «Единые точки проекта».
2. **Один стенд чужого API на пакет** (провенанс `architecture`/R3). В `tvdb_test.go` два фейка
   одного API; когда форма ответа поменяется по факту разведки, забытый `fakeTVDB` останется
   зелёным и продолжит подтверждать опровергнутое предположение.
3. **Интеграционный тест обязан утверждать, а не печатать** (провенанс `specs`).

**Отсеяно как вкусовщина:** переименование `translatedName` (поведения не меняет, записанной
конвенции нет); асимметрия «primary name едет без `TrimSpace`» (последствия нет); `searches` как
дубль `len(queries)` — часть promote-кандидата 2. Раздел «Типовые ложноположительные»
`docs/review.md` прочитан; ни одна находка под них не подпала.

## Границы покрытия

**План:** все семь строк имеют исход; тем без дома одна и она объявлена планом заранее; тем без
отчёта — ноль.

**Запускались** шесть проходов. **Не запускался `basics`** — по плану разметки; пропуска темы это
не даёт, но означает, что второго провенанса у сигнала о заниженной метке нет.
**Не существует в конвейере** проход независимой реализации — снят по стоимости; на задаче,
целиком построенной на неподтверждённом внешнем контракте, это самый дорогой пробел прогона.

**Чего не мог проверить каждый проход:**
- `autotests` — качество распознавания гейтом не проверяется вовсе (решение проекта); diff-coverage
  91%, 4 непокрытых строки — wiring в `cmd/jellybit/serve.go` внутри уже непокрытой функции.
- `specs` — границы спеки: пустой primary name при непустом переводе; локализация расширенных
  данных (объявленный Non-Goal).
- `code` — правило про `ident` линтером не проверяется; форма кода вне механизированного перечня.
- `architecture` — завязка внешних потребителей на текущее поведение; «нужна ли функциональность».
- `adversary` — **три из четырёх вопросов темы `security` не разбирались** (крафт-магнет, снятие
  последней копии, асимметрия признака владения): вне диффа, бюджет ушёл на построение пути.
- `ops` — реальный профиль нагрузки на umbar; замеры сняты в одиночку.
- Триаж — ничего нового не находит по определению.

**Рамка соблюдена:** живых обращений к TheTVDB ноль; `TVDB_API_KEY` не задавался;
`TestIntegration_TVDB` не запускался. Оракулы триажа добыты на `httptest`-стенде в копии дерева
под `tmp/triage/repo`; рабочее дерево не менялось.

**Целиком на человеке:** история инцидентов на umbar; поведение SQLite под реальным объёмом;
завязка внешних потребителей; «нужна ли функциональность»; качество распознавания.
**Перестали проверять сознательно:** идиоматичность Go (проход `idiom` упразднён 2026-08-04).

**Четыре строки, которые не принесёт ни один проход:** решения проекта (`docs/adr/`) не
сверялись — процессный документ; записанные наблюдения (`docs/research/`) как оракул не
использовались, и оракул находки 1 заменён на исполненный тест именно поэтому; поимённая сверка с
руководствами по стилю Go не задавалась; альтернативной реализации для диффа решений нет.

**Потолки:** `code` сообщил свой (2 из 4, срез не сработал); `adversary` объявил срез по бюджету;
`autotests`, `specs`, `architecture`, `ops` свой потолок не сообщили — это находка о прогоне.
Триаж: 6 из 7, потолок не выбран.

## Что сделано по находкам (записано оркестратором после отработки)

| № | Действие | Исход |
|---|---|---|
| 1 | развилка, выбран вариант (а) | Предикат разведён: признаком служит наличие хотя бы одного трёхбуквенного ключа во всей выдаче, а не удача разбора; `null` и `{}` считаются неразобранными. Уровень поднят до `WARN`. Закреплено тестом `TestTVDB_SignalOnUnexpectedTranslationForm` (8 случаев, включая штатный «перевода нет» с ожиданием **отсутствия** следа). В дельте заказана наблюдаемость, уровень отдан конвенциям; добавлены два сценария. |
| 2 | развилка, выбран вариант (а) | Утверждение в `design.md` → Risks переписано: сказано, что `plan.Title = match.Title` подставляется после `sanitizePlan`, санитайзинг не применяется, класс пре-существующий, инвариант целевого пути держится. Починка кода **не делалась** — отдана урожаем. |
| 3 | инлайн | Выбор ключа детерминирован: точное совпадение сильнее, иначе лексикографически меньший. Тест `TestTVDB_TranslationKeyPickIsDeterministic` (200 прогонов на случай). В дельту добавлено требование о регистронезависимости и детерминизме плюс сценарий «Ключ перевода в другом регистре». |
| 4 | инлайн | Добавлен `TestMatchMetadata_TranslationMakesTwoStrong` в `internal/recognize/metadata_test.go`. |
| 5 | инлайн | Поле лога переименовано в `tvdb_locale`. |
| 6 | инлайн | В `config.example.toml` у `[metadata.tvdb]` дописан хвост про `[general].language` с указанием отличия от TMDB. |

**Урожай, переданный владельцу задач** (пайплайн задач из него не заводит):

1. Санитайзинг `match.Title`/`match.Director` при подстановке в план либо категория Cf в
   `layout.sanitizeComponent` — находка 2, класс общий для TMDB и TVDB, оракул в отчёте.
2. Название длиннее ~237 байт уводит задачу в `failed` с текстом системной ошибки вместо review
   (AD4) — пре-существующее, оракул в отчёте.
3. Три promote-кандидата выше: правило синхронности кодов языка, один стенд чужого API на пакет,
   интеграционный тест обязан утверждать.
4. Наблюдение о прогоне: четыре прохода не сообщили свой потолок.
5. Наблюдение об окружении: кэш `golangci-lint` в worktree, вложенном в основной репозиторий,
   нёс результаты чужого прогона с путями `../../internal/…` и красил шаг `lint` находками вне
   диффа. Лечится `golangci-lint cache clean`. На каждом worktree это ложный красный гейт.