jellybit/openspec/changes/archive/2026-08-10-metadata-title-sanitize/design.md

Context

Распознавание строит план в два приёма. Сперва разбирается ответ LLM: parsePlan вызывает sanitizePlan, и три человекочитаемых поля — title, original_title, provider_hint — чистятся как недоверенный вход. Потом идёт сверка с метабазой, и при подтверждённом матче recognize.go подменяет поля плана каноническими значениями:

match, candidates := r.matchMetadata(ctx, plan)
if match != nil {
    plan.Title = match.Title      // ← значение внешнего сервиса, мимо чистки
    ...
}
dec := decide(plan, pre, match, ...)

Подстановка стоит после чистки, поэтому очищено ровно то, что чисткой потом и перезаписывается. Дальше plan.Title уходит в layout.titleYear и становится именем каталога библиотеки.

Ниже по потоку layout.sanitizeComponent снимает разделители пути, символы, недопустимые в SMB/NTFS, и байты < 0x20. Категорию Cf (zero-width, BOM, мягкий перенос) он не трогает и гомоглифы не сворачивает — они не мешают файловой системе и потому там не при чём.

Гейт авто-раскладки от этого не спасает: metadata.go сверяет normalize(c.Title) || normalize(c.OriginalTitle), то есть кандидат проходит по любому из двух полей, а в план и в путь уезжает только первое.

Инвариант «целевой путь строго под библиотекой» при этом держится — ревью проверило Dune/../../etc, " .. ", "..." и 400 символов, выхода из песочницы нет. Речь о предсказуемости имени, а не о песочнице.

Goals / Non-Goals

Goals:

• Название из метабазы получает ту же чистку, что и название от LLM, до того как попадёт в план.
• Название, схлопнувшееся чисткой в пустое, не порождает каталог с пустым именем и не роняет раскладку.
• У чистки названий остаётся один дом: второй реализации не заводится.
• Поведение TMDB на нормальных названиях не меняется — регресс на работающем провайдере дороже самого дефекта.

Non-Goals:

• Полная нормализация Unicode (NFC/NFKC, конфузаблы по таблице Unicode). Рамка задачи это прямо исключает: цель — предсказуемое и сверяемое значение, а не исчерпывающая защита от визуального совпадения.
• Расширение состава layout.sanitizeComponent. Он чистит компонент пути под требования файловой системы, и категория Cf ему не мешает.
• Чистка director в плане. Действующее требование metadata-match относит её к рендеру отображаемого имени, и трогать это изменение не будет.
• Пересмотр гейта матча (normalize(c.Title) || normalize(c.OriginalTitle)). Расхождение «сверяем по двум полям, подставляем одно» после этой правки перестаёт быть опасным: подставляется очищенное значение.

Decisions

Решение 1. Чистить на подстановке, в recognize

Санитайзинг применяется к match.Title в месте подстановки — там же, где сегодня стоит plan.Title = match.Title. Используется существующая sanitizeTitle, без новых функций.

Почему здесь. Место подстановки — единственная точка, где значение метабазы входит в план; всё, что ниже, работает уже с планом. Чистка здесь означает инвариант, который можно сформулировать одной фразой и проверить: план после матча не содержит несанитизированных человекочитаемых полей.

Рассмотрено и отвергнуто:

• Закрыть категорию Cf и гомоглифы в layout.sanitizeComponent. Дало бы второй дом чистке названий и разошлось бы с первым: sanitizeTitle сворачивает гомоглифы потокенно по доминирующему скрипту — правило нетривиальное, и две его реализации разъедутся молча. Плюс sanitizeComponent работает и на FolderBase, прочитанной с диска, — там свёртка гомоглифов сломала бы сходимость к существующей папке.
• Чистить в клиентах метабаз (internal/metadata/*.go). Пришлось бы повторить в трёх клиентах и повторять в каждом следующем; проверка «в плане нет грязных полей» перестала бы читаться в одном месте.
• Прогнать sanitizePlan ещё раз после матча. Внешне дешевле всего, но вторым проходом чистит и то, что уже чисто, а главное — молчит о случае, когда название базы схлопнулось в пустое: p.Title стал бы пустым, и раскладка упала бы на layout: empty title after sanitization.

Решение 1a. Точек входа две, и закрываются обе

Ревью дизайна показало, что подстановка при авто-матче — не единственный вход значения метабазы в план. Второй: человек выбирает кандидата на ревью, его название закрепляется как override и попадает в план мимо распознавания. Спека metadata-match при этом сама называет ручной выбор основным путём подтверждения матча — закрыть только авто-путь значило бы починить менее употребимую половину и записать в спеку свойство, которого нет.

Закрываются обе одной и той же чисткой, но в трёх местах — по одному на каждую точку, где значение метабазы входит в домен:

1. каноническое название матча — в buildMatch, единственной точке сборки Match. Дальше по потоку значение считается чистым: и подстановка в план, и решение auto/review, и диагностика сухого прогона берут его как есть. Ревью кода показало, чем плоха чистка на подстановке: условие пригодности пересчитывалось независимо в двух файлах, и первая же правка одного из них дала бы молчаливую авто-раскладку;
2. названия кандидатов — в момент, когда кандидат копируется в список для ревью (matchMetadata, накопление candidates). Оттуда чистое значение уезжает разом в хранилище, на экран ревью и в карточку Telegram;
3. набор пинов источника — sourcePins в worker. Это не дубль пункта 2, а ответ на два разных вопроса. Во-первых, через sourcePins идут и превью источника, и его закрепление, поэтому свойство «превью = применение» держится конструкцией: без чистки здесь экран показывал бы одно название, а раскладка делала другое. Во-вторых, пункт 2 чистит на записи, то есть гарантия держалась бы на времени записи строки — все кандидаты, сохранённые до этой правки и стоящие в очереди ревью, обошли бы её. Чистка идемпотентна, поэтому на новых строках пункт 3 не делает ничего.

Почему это не двигает гейт матча. Сильный матч ищется по cands — срезу, как его отдал провайдер, — а в ревью уходит копия в candidates. Чистка на копировании до сравнения не доходит. Проверять это пришлось отдельно: сравнение идёт через normalize, и она не эквивалентна санитайзингу — zero-width внутри слова normalize превращает в пробел (Du␀ne → du ne), а санитайзинг удаляет (dune). То есть чистка всего списка cands до сравнения превратила бы часть нынешних «в review» в «авто», и это был бы сдвиг гейта, которого задача не заказывала.

Рассмотрено и отвергнуто: звать санитайзер прямо в chooseCandidateLocked — это закрыло бы закрепление и оставило превью считаться по сырому значению, то есть развело бы показанное и применённое. Правило живёт в sourcePins, потому что это единственный общий дом набора пинов; запланированный review-mapping-editor придёт туда же, а не заведёт четвёртый вызов.

Что при этом экспортируется: recognize.SanitizeTitle и recognize.UsableTitle — пара «почисти и проверь пригодность». Экспортировать пришлось обе: предикат без санитайзера обязывал бы вызывающего помнить порядок, а порядок прозой не проверяется.

Решение 2. Пустой результат чистки — прежнее название и уход в review

Если sanitizeTitle(match.Title) даёт пустую строку, подстановка не выполняется: в плане остаётся название от LLM (оно уже прошло чистку и непустое — иначе validateSchema отклонил бы план), а в причины решения добавляется строка, из-за которой раздача уходит в ревью.

Почему так. Из трёх исходов — упасть, подставить пустое, оставить прежнее — только третий сохраняет работоспособность и при этом не скрывает происшествие. Название из одних невидимых символов означает, что с записью базы что-то не так, и это ровно тот случай, ради которого ревью и существует: система не уверена — зовёт человека, а не заминает.

Рассмотрено и отвергнуто: отклонять матч целиком (терялись бы provider_id, год и режиссёр — а они верны); подставлять пустое и ловить это раскладкой (отказ приходит поздно, терминальным состоянием и текстом чужого слоя — ровно та боль, которую чинит соседняя задача long-title-to-review).

Решение 3. Год, режиссёр и провайдер не трогаются

match.Year — число, чистить нечего. match.Director в путь на диске не попадает, и его очистка по действующему требованию делается при рендере имени (naming.sanitize). provider/provider_id — идентификаторы, у них своя валидация.

original_title в план из матча не подставляется вовсе — сегодня recognize.go берёт из Match только название, год и режиссёра. Чистить там нечего, и требование про «поля плана после матча» это учитывает: значение original_title осталось тем, что пришло от LLM, то есть уже санитизированным.

Решение 4. Решение auto/review остаётся с одним производителем

Decision{Auto, Reasons} для разобранного плана рождается ровно в одном месте — decide в validate.go, и её доккомментарий утверждает исчерпывающий перечень условий авто. Новая причина появляется внутри decide, а не дописывается к готовому решению со сбросом Auto: иначе у того же решения появляется второй производитель, и следующая правка гейта (соседняя задача long-title-to-review заводит причину того же класса) будет выбирать между двумя местами.

Дополнительного входа у decide при этом не появилось, хотя сперва предполагался: раз Match.Title санитизируется в buildMatch (Решение 1a), decide отвечает на вопрос пригодности по уже чистому значению — match у неё и так на руках. Условие считается один раз и читается из одного поля.

Решение 5. Общая форма «название непригодно как компонент пути» отложена

Пустое-или-вырожденное название и название длиннее лимита файловой системы — один класс: значение не годится как компонент пути, исход один — review с названной причиной вместо отказа из слоя раскладки. Общее место для этого класса здесь не заводится: второй его случай — предмет соседней задачи long-title-to-review, и собирать общую форму из одного случая рано. Это записано, чтобы второй автор не изобретал её параллельно, а достроил.

Risks / Trade-offs

• Правка меняет работающий путь TMDB. → Значение проходит через идемпотентную чистку, которая на нормальном названии не меняет ничего; критерий приёмки требует зелёных существующих тестов internal/recognize и internal/metadata без правки ожиданий — расхождение сразу видно.
• Свёртка гомоглифов может тронуть честное название. → Правило потокенное: одно-скриптовый токен не трогается, и кириллические названия проходят как есть. Правило уже работает на выводе LLM и покрыто сценариями спеки; изменение лишь распространяет его на второй источник.
• Гомоглифы сворачиваются, а конфузаблы шире таблицы — остаются. → Осознанный trade-off, названный в рамках задачи. Курируемая кирилло-латинская таблица закрывает реальный случай (русскоклавиатурные двойники); полная нормализация Unicode — отдельный разговор.
• Название базы схлопнулось в пустое — пользователь видит название от LLM. → Раздача при этом в ревью, где название правится подсказкой, а причина названа словами.
• Уже созданные «грязные» каталоги правкой не чинятся. → Правило сходимости базы папки (file-layout, «Сходимость базы папки при подтверждённом матче») наследует имя от живой папки-якоря и не печатает его заново из распознавания. Каталог с невидимыми символами, созданный до этой правки, останется якорем, и следующий сезон ляжет в него. Лечение — переименовать папку руками, после чего сходимость подхватит новое имя. Изменение закрывает появление новых таких каталогов, а не существующие.