jellybit/openspec/specs/file-layout/spec.md

file-layout Specification

Purpose

Раскладка распознанных файлов хардлинками под библиотеку Jellyfin: целевые имена фильмов и сериалов (папка/файл, provider-id, сезоны), сопоставление источник→цель, санитизация пути и запрет выхода за библиотеку, never-overwrite (коллизия → review) и copy-fallback при невозможности хардлинка. Владение целевым путём (superseded) и безопасный Undo (nlink<=1) — в state-reconciliation.

Requirements

Requirement: Целевые имена фильмов

Фильм система SHALL раскладывать в папку и файл вида Название (Год), помещённые под paths.movies. При подтверждённом матче в базе имя папки SHALL нести provider-id ([tmdbid-…]/[tvdbid-…]) — он снимает неоднозначность русских названий для Jellyfin. Внешние субтитры SHALL именоваться Имя.<lang>[.flag].srt (флаги forced/sdh/default/hi), с базой имени, совпадающей с именем видеофайла; пары VobSub — .idx + .sub.

Scenario: Фильм с provider-id

• GIVEN распознанный фильм «Дюна Часть вторая» (2024) с матчем TMDB 693134
• WHEN строится целевой путь
• THEN папка = movies/Дюна Часть вторая (2024) [tmdbid-693134]/
• AND видеофайл = Дюна Часть вторая (2024).mkv

Requirement: Целевые имена сериалов

Сериал система SHALL раскладывать под paths.series в папку Название (Год) с provider-id на папке сериала, сезонными подпапками Season xx и файлами вида Название (Год) SxxEyy.

Scenario: Серия сезона

• GIVEN распознанный сериал «Фарго» (2024) с матчем TVDB 123456, серия S01E02
• WHEN строится целевой путь
• THEN путь = series/Фарго (2024) [tvdbid-123456]/Season 01/Фарго (2024) S01E02.mkv

Requirement: Сопоставление источник → цель хардлинками

Для каждого распознанного файла (не каталога) система SHALL создавать хардлинк в paths.movies/paths.series; исходный путь берётся из qBittorrent (save_path + относительное имя файла из /torrents/files, уже включающее корневую папку многофайловой раздачи). Целевые каталоги SHALL создаваться mkdir (0755, 1000:1000). Исходный файл система НЕ SHALL трогать — раздача продолжается, inode общий, диск не дублируется.

Scenario: Хардлинк не дублирует данные

• GIVEN видеофайл раздачи под paths.downloads
• WHEN файл раскладывается
• THEN в библиотеке создаётся хардлинк на тот же inode
• AND исходный файл остаётся на месте

Requirement: Санитизация целевого пути и запрет выхода за библиотеку

Целевое имя система SHALL санитизировать (без разделителей пути, .., управляющих символов), а финальный путь SHALL проверять на строгое нахождение под paths.movies/paths.series. Путь, выходящий за пределы библиотеки, система НЕ SHALL создавать. Безопасность SHALL держаться на валидации пути, а не на доверии к выходу LLM.

Scenario: Traversal отклоняется

• GIVEN распознанное имя, содержащее ../
• WHEN строится и проверяется целевой путь
• THEN путь отклоняется как выходящий за пределы библиотеки, хардлинк не создаётся

Requirement: Существующую цель не перезаписываем

Существующий целевой файл система НЕ SHALL перезаписывать. Если по целевому пути уже лежит тот же inode — операция идемпотентна (готово); если другой файл — это коллизия, и задача SHALL уходить в review.

Scenario: Коллизия уходит в review

• GIVEN по целевому пути уже лежит другой файл
• WHEN выполняется раскладка
• THEN файл не перезаписывается, задача переходит в review с причиной коллизии

Requirement: Copy-fallback при невозможности хардлинка

Система SHALL при невозможности хардлинка (разные ФС или ФС без поддержки жёстких ссылок) НЕ падать, а копировать файл с предупреждением в лог, помечая ссылку статусом copied.

Scenario: Разные ФС — копирование

• GIVEN целевой и исходный каталоги на разных ФС
• WHEN выполняется раскладка файла
• THEN файл копируется, ссылка получает статус copied, в лог пишется предупреждение

Requirement: Запись размера разложенного файла

При линковке файла раскладка SHALL сохранять его размер в байтах вместе с записью о созданной ссылке (file_link). Сохранённый размер SHALL позволять вычислить суммарный размер разложенных файлов загрузки — он служит фолбэком размера раздачи, когда торрента нет в qBittorrent (например, состояние orphaned, где файлы библиотеки — последняя копия данных). Запись размера MUST NOT влиять на инвариант неприкосновенности источника (по-прежнему только mkdir/link/копия в цель).

Scenario: Размер сохраняется при линковке

• WHEN раскладка создаёт хардлинк (или копию при copy-fallback) файла
• THEN размер этого файла в байтах сохраняется в записи ссылки file_link

Scenario: Суммарный размер доступен без торрента

• WHEN у загрузки есть разложенные файлы, а её торрента нет в qBittorrent
• THEN суммарный размер разложенных файлов доступен как размер раздачи для показа в карточке

Requirement: Claim раскладки коммитится до хардлинков и устойчив к сбою учёта

Раскладка — «claim-then-side-effect»: система SHALL сперва зафиксировать переход задачи в linking (claim шага раскладки), и только затем создавать хардлинки. Если запись claim перехода в linking провалилась, система НЕ SHALL создавать хардлинки и SHALL прервать раскладку, оставив задачу в исходном состоянии (review/deferred при ручном применении; recognizing при авто-раскладке) — чтобы у шага сохранился владелец, а хардлинки не легли при незакоммиченном claim (иначе финальный переход linking → done из фактического состояния был бы отклонён графом, и задача застряла бы со stale-планом).

Если хардлинки уже созданы, но запись их учёта (file_link) провалилась (транзиентная ошибка хранилища), задача НЕ SHALL оставаться в linking: система SHALL перевести её в review с причиной. Повторное применение SHALL быть идемпотентным — уже созданные хардлинки распознаются как существующие (StatusExists), а их учёт дописывается.

Scenario: Провал claim не создаёт хардлинков

• GIVEN задача в review с готовым источником и валидным планом
• WHEN запись перехода в linking проваливается
• THEN хардлинки не создаются, учёт file_link не пишется
• AND задача остаётся в review, а команда отказывает с ошибкой

Scenario: Провал учёта уводит в review, не оставляя в linking

• GIVEN хардлинки по плану уже созданы на файловой системе
• WHEN запись строк file_link проваливается транзиентной ошибкой
• THEN задача переходит в review с причиной (код persist), а не остаётся в linking
• AND созданные хардлинки остаются на диске
• AND повторное «Применить» идемпотентно дописывает учёт и доводит до done

Requirement: Сходимость базы папки при подтверждённом матче

Система SHALL при построении плана раскладки для загрузки с подтверждённым матчем (заданы provider и provider_id) наследовать базу имени (Название (Год) — строку без provider-тега) от существующей на диске папки-якоря того же тайтла, а НЕ печатать её заново из выхода распознавания. Кандидаты в якорь — целевые пути (dst_path) ссылок со статусом linked/copied/exists других загрузок (не текущей), чей current recognition имеет тот же (provider, provider_id).

Истина — папка на диске, а не запись в БД: кандидат SHALL считаться живым якорем, только если его папка тайтла реально существует на файловой системе. Статус ссылки в БД недостаточен — при ручном/Jellyfin-переименовании папки запись file_link какое-то время остаётся linked (загрузка лишь позже уходит в target_missing по сверке), а dst_path указывает на уже несуществующий путь. Поэтому кандидат, чья папка тайтла отсутствует на диске, в якоря НЕ берётся; если живых якорей не осталось, следующая загрузка снова печатает базу из распознавания.

Унаследованная база SHALL применяться и к папке сериала/фильма, и к именам файлов внутри (episode/movie stem), чтобы серии разных сезонов совпадали по базе (Fargo (2014) S02E01 рядом с Fargo (2014) S01E01). Provider-тег на папке ([tvdbid-…]) по-прежнему SHALL строиться из текущего (provider, provider_id).

База тайтла извлекается из папки-якоря снятием хвостового provider-тега [...]; извлечённая база прогоняется через ту же санитизацию, что и печатаемая. Если папку-якорь нельзя разобрать (сегмент не под корнем библиотеки, база пуста), кандидат в якоря НЕ берётся (безопасный fallback на печать из распознавания), а не даёт искажённую базу.

Наследование SHALL происходить только при подтверждённом матче. Нет живого якоря (первая загрузка тайтла) → база печатается из распознавания, как прежде. Нет матча (provider пуст / none) → авто-раскладки нет (инвариант), база не наследуется — папку на ревью выбирает человек. Правило не вводит новых сущностей и не меняет схему БД: это выборка по существующим file_link → download → recognition(is_current) плюс проверка существования папки на диске. Безопасность по-прежнему держится на санитизации и проверке пути под библиотекой, а не на доверии к выходу распознавания.

Разрешение базы SHALL быть единым для авто-раскладки и ручного «Применить», а также для предпросмотра раскладки на ревью — чтобы превью показывало ту же папку/имена, что даст применение (инвариант «превью = применение»). В предпросмотре разрешение выполняется без побочных эффектов (в review из-за рассинхрона переводит только применение, не показ).

Scenario: Второй сезон ложится в папку первого

• GIVEN первый сезон уже разложен в series/Фарго (2014) [tvdbid-269613]/Season 01/… (ссылки живые)
• AND новая загрузка со вторым сезоном имеет матч TVDB 269613, но распознавание дало название «Fargo» и год 2017
• WHEN строится план раскладки второго сезона
• THEN база наследуется от живого якоря: папка = series/Фарго (2014) [tvdbid-269613]/
• AND серия ложится как Season 02/Фарго (2014) S02E01.mkv (база в имени файла — унаследованная, а не из выхода LLM)

Scenario: Нет живого якоря — печатаем из распознавания

• GIVEN ни у одной загрузки нет живых ссылок с тем же (provider, provider_id)
• WHEN строится план раскладки при подтверждённом матче
• THEN база берётся из распознавания (название+год), как прежде — первая загрузка «печатает» имя папки

Scenario: Нет матча — сходимость не применяется

• GIVEN у загрузки нет подтверждённого матча (provider пуст / none)
• WHEN обрабатывается раскладка
• THEN авто-наследования базы не происходит, загрузка идёт через review (папку выбирает человек)

Scenario: Папка-якорь переименована на диске — печатаем заново

• GIVEN у загрузки-кандидата статус ссылок ещё linked, но её папка тайтла на диске переименована/удалена (по dst_path папки нет)
• WHEN строится план раскладки новой загрузки с тем же матчем
• THEN отсутствующая на диске папка в якоря не берётся
• AND при отсутствии других живых якорей база печатается из распознавания

Scenario: Превью на ревью совпадает с применением

• GIVEN есть живой якорь тайтла, а распознавание текущей загрузки дало иную базу
• WHEN на ревью открывается предпросмотр целевой раскладки
• THEN превью показывает папку/имена с унаследованной базой якоря — те же, что даст «Применить»

Requirement: Рассинхрон живых папок тайтла уходит в review

Система MUST NOT молча выбирать якорь при обнаружении нескольких РАЗНЫХ живых целевых папок с одним (provider, provider_id) (рассинхрон, случившийся до внедрения правила сходимости): такая загрузка SHALL уходить в review с явной причиной «рассинхрон папок тайтла», чтобы человек выбрал/свёл папку вручную (по прецеденту коллизии, которая тоже уводит в review из раскладки).

Scenario: Две живые папки одного матча → review

• GIVEN для матча TVDB 269613 существуют две разные живые папки (Фарго (2014) … и Fargo (2017) …)
• WHEN строится план раскладки новой загрузки с этим матчем
• THEN раскладка не выполняется, задача переходит в review с причиной рассинхрона папок тайтла

Requirement: Пересканирование Jellyfin после изменения библиотечных ссылок

При сконфигурированном пересканировании Jellyfin (секция [jellyfin] включена) система SHALL при входе задачи в одно из состояний множества {done, reverted, deleted} неблокирующе просить Jellyfin пересканировать медиатеку (POST /Library/Refresh, скан всех библиотек). Эти три состояния — точки, где раскладка задачи улеглась так, что видимый Jellyfin каталог мог рассинхронизироваться с диском: done — наши хардлинки разложены (или восстановлены сверкой); reverted — Undo снял наши ссылки; deleted — ссылки сняты (Delete) либо констатировано их отсутствие (сверка), задача терминальна.

Условие срабатывания система SHALL проверять по состоянию-цели перехода в едином чекпоинте записи состояния. Такой гейт SHALL естественно покрывать как пользовательские команды (Undo → reverted, Delete → deleted), так и reconcile-производный deleted — инициатор перехода роли не играет; повторный/ лишний скан безвреден (инкрементальный скан дёшев, операция идемпотентна).

Состояния вне этого множества система сканировать SHALL NOT. Сюда входят как входы, не меняющие наши ссылки (review, linking, cancelled через Dismiss), так и промежуточные состояния рассинхрона target_missing и orphaned: там раскладка ещё не улеглась — задача ждёт relink/восстановления и может «залечиться» обратно в done, поэтому скан на них система откладывает, а не шлёт на каждое колебание сверки. target_missing система не сканирует сознательно, хотя цель там пропала: это внешняя пропажа при живом источнике, не наше снятие.

Скан система SHALL выполнять вне блокировки воркера, в фоновом контексте и в отдельной горутине, со scoped-логгером задачи для корреляции. Недоступность Jellyfin на состояние задачи влиять SHALL NOT — ошибка вызова лишь логируется (её пишет клиент Jellyfin как запись внешнего вызова). Если пересканирование не сконфигурировано ([jellyfin] выключено), скан не дёргается ни в одном из этих переходов.

Scenario: Скан после раскладки

• GIVEN пересканирование Jellyfin включено
• WHEN задача входит в done после успешной раскладки хардлинков
• THEN система неблокирующе дёргает POST /Library/Refresh

Scenario: Скан после отката (Undo)

• GIVEN пересканирование Jellyfin включено, задача в done с разложенными ссылками
• WHEN пользователь выполняет Undo и задача входит в reverted (наши ссылки сняты)
• THEN система неблокирующе дёргает POST /Library/Refresh

Scenario: Скан после удаления (Delete)

• GIVEN пересканирование Jellyfin включено, задача в done
• WHEN пользователь выполняет Delete и задача входит в deleted (наши ссылки сняты)
• THEN система неблокирующе дёргает POST /Library/Refresh

Scenario: Без конфигурации Jellyfin скан не дёргается

• GIVEN пересканирование Jellyfin выключено ([jellyfin] не сконфигурировано)
• WHEN задача входит в done, reverted или deleted
• THEN система скан не дёргает

Scenario: Вход вне множества не сканирует

• GIVEN пересканирование Jellyfin включено
• WHEN задача входит в состояние вне {done, reverted, deleted} (например, review или промежуточный target_missing)
• THEN система скан не дёргает