jellybit/openspec/specs/ingest/spec.md

ingest Specification

Purpose

Приём загрузки — единый use-case для всех транспортов (HTTP, Telegram, CLI): парс источника (Ф1 — magnet), извлечение инфохэшей (download_infohash), дедупликация по активной задаче, атомарное заведение download и отдача источника в qBittorrent, а также вывод человекочитаемого отображаемого имени из контекста (через LLM или алгоритмический фолбек). Держит инвариант «не более одной активной загрузки на infohash» (атомарный возврат в активное состояние).

Requirements

Requirement: Отображаемое имя торрента из контекста

На шаге добавления пойманной загрузки в qBittorrent (worker) система SHALL выводить из контекста загрузки человекочитаемое отображаемое имя и передавать его в qBittorrent (параметр rename API /torrents/add), чтобы задача в списке qBit не показывалась безликим dn magnet-ссылки. Это же имя система SHALL сохранять у загрузки (download.display_name) для последующего показа заголовком в веб-UI.

Имя SHALL быть коротким читаемым ярлыком (название, опционально режиссёр и год; для сериала — номер сезона, если он определён), а не куском сырого контекста. Имя SHALL очищаться от управляющих символов и переводов строк и SHALL обрезаться по ограничению длины.

Вывод имени SHALL выполняться на шаге добавления, непосредственно перед вызовом add (параметр rename действует только в момент добавления), а НЕ в синхронном пути ответа приёма. В состоянии catched (до добавления) download.display_name ещё пуст — веб-UI берёт заголовок из фолбека.

Отображаемое имя SHALL влиять только на отображение (в qBittorrent и как заголовок в веб-UI) и SHALL NOT влиять на пути файлов на диске, распознавание или раскладку — реальные пути система по-прежнему читает из qBit API.

Scenario: Имя из контекста передаётся в qBittorrent

• WHEN на шаге добавления получен непустой контекст, из которого удалось вывести имя
• THEN система передаёт это имя в qBittorrent в параметре rename
• AND имя — короткий читаемый ярлык вида «название (режиссёр, год)», где режиссёр и год опциональны

Scenario: Имя сохраняется у загрузки

• WHEN на шаге добавления выведено непустое отображаемое имя
• THEN система сохраняет его в download.display_name (обновлением записи загрузки)
• AND веб-UI использует его заголовком карточки и страницы загрузки

Scenario: Контекст пуст или имя не получено

• WHEN контекста нет либо ни один способ вывода не дал непустого имени
• THEN система добавляет загрузку без параметра rename
• AND qBittorrent оставляет собственное имя (из dn/торрента)
• AND download.display_name остаётся пустым, а веб-UI берёт заголовок из фолбека (распознанное название или усечённый источник)

Requirement: Вывод имени через LLM со структурированным выводом

Система SHALL строить отображаемое имя с помощью LLM (структурированный JSON-вывод), извлекая из контекста тип (movie/series), название, год, режиссёра и (для сериала) номер сезона. Год и режиссёр — опциональные поля.

Если и контекст, и подсказка из полей источника (dn magnet / имя .torrent) пусты, система SHALL считать имя не выведенным и SHALL NOT вызывать LLM (выводить имя не из чего — вызов на пустом входе способен лишь галлюцинировать). В этом случае загрузка добавляется без rename, а download.display_name остаётся пустым.

Название SHALL быть на русском языке для российского контента и на английском (оригинальном) — для остального.

Система SHALL предпринять ограниченное число попыток получить от LLM валидный результат (корректный JSON с непустым названием); бюджет попыток — [llm].max_retries (по умолчанию 3). Транспортные ретраи провайдера LLM (сетевые сбои, 429, 5xx) в этот счёт не входят.

Недоступность или ошибка LLM SHALL NOT прерывать приём загрузки: система переходит к алгоритмическому фолбеку.

Scenario: LLM возвращает структурированное имя

• WHEN LLM по контексту возвращает валидный JSON с непустым названием
• THEN система формирует отображаемое имя из его полей (название, год, для сериала — сезон)

Scenario: Российский контент — название на русском

• WHEN контент распознан как российский
• THEN в отображаемом имени используется русское название

Scenario: Исчерпан бюджет попыток LLM

• WHEN LLM за отведённые попытки ([llm].max_retries) не вернул валидный результат либо недоступен
• THEN система не прерывает приём и переходит к алгоритмическому фолбеку

Scenario: Пустой вход — LLM не вызывается

• GIVEN пойманная загрузка без пользовательского контекста и без подсказки из полей источника (голый magnet без dn)
• WHEN система выводит отображаемое имя на шаге добавления
• THEN LLM не вызывается, имя считается не выведенным
• AND загрузка добавляется без rename, а download.display_name пуст (заголовок в веб-UI берётся из фолбека)

Requirement: Алгоритмический фолбек вывода имени без сети

При неудаче LLM система SHALL выводить имя алгоритмически, без сетевых запросов: брать первую содержательную строку контекста (без ссылок, команд бота и UI-мусора), отсекать технические характеристики, очищать и обрезать по длине.

Если и фолбек не дал непустого имени, система SHALL добавить загрузку без параметра rename.

Scenario: Фолбек извлекает имя из контекста

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

Scenario: Фолбек тоже пуст

• WHEN ни LLM, ни алгоритмический фолбек не дали непустого имени
• THEN система добавляет загрузку без параметра rename

Requirement: Обновление отображаемого имени по распознаванию

Система SHALL уметь обновлять отображаемое имя загрузки после того, как распознавание дало каноническое название, — переливая уже вычисленное имя (без нового вызова LLM) в download.display_name и в имя раздачи qBittorrent.

Источником имени SHALL быть эффективные поля имени, разрешённые по слоям сверху вниз (берётся первый непустой слой): (1) ручные правки override; (2) распознавание с вложенным подтверждённым матчем (recognition, куда матч метабазы уже вложил каноничные название/год/режиссёра); (3) сохранённая структура из контекста (download.parsed_context). Так каждое поле берётся из самого доверенного доступного источника, а данные из контекста (например режиссёр) не теряются, если распознавание/матч их не дали. Название из слоя распознавания SHALL совпадать с тем, что использует раскладка (эффективный title), чтобы отображаемое имя не расходилось с целевыми путями.

Формат SHALL быть тем же полным детерминированным ярлыком, что и на шаге добавления: «Название (режиссёр, год)», где режиссёр и год опциональны, а для сериала добавляется сводка сезонов («. Сезон N» для одного сезона; «. Сезоны …» для многосезонного пака; отметка спецвыпусков) — согласованная со сводкой сезонов на экране просмотра. Применяются та же очистка от управляющих символов и обрезка по ограничению длины. Пустой источник (нет ни распознавания, ни сохранённой структуры, дающих непустое название) SHALL приводить к отсутствию изменений (no-op).

Переименование раздачи в qBittorrent SHALL адресоваться по infohash своей раздачи и SHALL быть best-effort: сбой (раздача удалена, qBittorrent недоступен) SHALL NOT проваливать обновление — download.display_name обновляется в любом случае, ошибка внешнего вызова логируется. Как и на шаге добавления, отображаемое имя SHALL влиять только на отображение и SHALL NOT влиять на пути файлов, распознавание или раскладку.

Обновление имени SHALL иметь две точки входа: авто — при подтверждённом матче (см. capability review); ручную — по явному действию пользователя. Ручное действие SHALL перезаписывать текущее имя всегда; авто SHALL перезаписывать, когда выведенное имя непусто.

Scenario: Перелив имени в загрузку и раздачу

• GIVEN загрузка с распознанным непустым каноническим названием и известным режиссёром (из матча или из сохранённого контекста)
• WHEN запускается обновление отображаемого имени
• THEN download.display_name устанавливается в полный ярлык «Название (режиссёр, год)» (для сериала — со сводкой сезонов)
• AND раздача в qBittorrent переименовывается в то же имя (по infohash своей раздачи)

Scenario: Режиссёр из контекста переживает распознавание без матча

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

Scenario: Режиссёр из матча бьёт контекстного

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

Scenario: qBittorrent недоступен — имя у загрузки всё равно обновлено

• GIVEN обновление отображаемого имени с выведенным непустым именем
• WHEN переименование раздачи в qBittorrent завершается ошибкой (недоступен или раздача удалена)
• THEN download.display_name всё равно обновлён
• AND ошибка внешнего вызова qBittorrent логируется, операция не проваливается

Scenario: Нет источника имени — обновление ничего не делает

• GIVEN загрузка без распознанного названия и без сохранённой структуры (пустой источник имени)
• WHEN запускается обновление отображаемого имени
• THEN ни download.display_name, ни имя раздачи не меняются (no-op)

Requirement: Приём источника и заведение загрузки

Приём SHALL быть единым быстрым use-case, общим для всех транспортов (HTTP, Telegram, CLI): по источнику (Ф1 — magnet) и текстовому контексту система SHALL синхронно извлечь инфохэши, синтезировать контекст из полей ссылки (без сети), дедуплицировать по блокирующей повторный приём задаче (активной либо удерживающей источник ради незакрытого намерения — target_missing/orphaned; см. «Дедупликация приёма по любому из хешей») и при отсутствии дубля завести загрузку (download в состоянии catched + записи download_infohash), после чего сразу вернуть ответ транспорту. Заведение загрузки и запись её хешей SHALL выполняться атомарно (см. «Атомарность возврата загрузки в активное состояние»).

Синхронный путь приёма SHALL NOT обращаться к qBittorrent и SHALL NOT выводить отображаемое имя (потенциально медленный LLM): и добавление источника в qBittorrent, и вывод имени выполняются отдельным асинхронным шагом машины состояний (worker) — см. download-tracking «Добавление пойманной загрузки в qBittorrent».

catched — нетерминальное активное состояние: оно участвует в инварианте «не более одной активной загрузки на infohash» наравне с прочими активными.

Scenario: Быстрый приём magnet

• GIVEN валидная magnet-ссылка и контекст
• WHEN вызывается приём
• THEN создаётся download в состоянии catched с записями download_infohash
• AND ответ транспорту отдан без обращения к qBittorrent и без вывода имени

Scenario: Дубль по активной задаче на быстром пути

• GIVEN уже есть активная (в т.ч. catched) загрузка с тем же infohash
• WHEN вызывается приём
• THEN новая загрузка не создаётся, возвращается существующая

Requirement: Множество инфохэшей загрузки

Загрузка SHALL иметь одну или более записей инфохэша (download_infohash: infohash lowercase hex, kind ∈ v1|v2). При приёме magnet-ссылки SHALL записываться ВСЕ известные из неё хеши — гибридный magnet несёт и btih (v1), и btmh (v2); kind определяется по длине hex (40 — v1, 64 — v2). Когда qBittorrent сообщает для раздачи оба хеша (infohash_v1, infohash_v2), система SHALL дописывать недостающие записи загрузке; усечённый хеш v2-only раздачи (поле hash qBittorrent, 40 hex от v2) записываться SHALL NOT. Сопоставление раздачи qBittorrent с загрузкой (поллинг, discover) SHALL выполняться по любому из известных хешей. Один и тот же infohash MAY принадлежать нескольким загрузкам во времени (повторный приём после терминального состояния), но активной из них MUST быть не более одной.

Scenario: Гибридный торрент раскрывает оба хеша

• GIVEN загрузка принята по magnet с v1-хешем
• WHEN qBittorrent отдаёт раздачу с заполненными infohash_v1 и infohash_v2
• THEN у загрузки появляются обе записи (kind = v1 и v2)

Scenario: Сопоставление по v2-хешу

• GIVEN загрузка с записями v1- и v2-хешей
• WHEN поллинг находит раздачу, совпавшую только по v2-хешу
• THEN раздача сопоставляется с этой загрузкой

Requirement: Дедупликация приёма по любому из хешей

При приёме система SHALL искать загрузку, блокирующую повторный приём, по любому из известных хешей и, найдя, SHALL возвращать её вместо создания новой. Блокирующими SHALL считаться загрузки в активном (нетерминальном) состоянии либо удерживающие источник ради незакрытого намерения — target_missing (источник жив в qBittorrent, ждёт relink) и orphaned (источник пропал, запись держит претензию на последнюю копию). Прочие терминальные состояния (done, cancelled, failed, reverted, deleted) блокирующими быть SHALL NOT: повторный приём такого инфохэша — осознанное «хочу заново» и SHALL заводить новую загрузку.

Когда найденная блокирующая загрузка терминальна (target_missing/orphaned), приём SHALL возвращать её как существующую (Deduplicated) спящей: система SHALL NOT переводить её в активное состояние и SHALL NOT обращаться к qBittorrent (перепривязка — отдельное явное действие пользователя, а не побочный эффект приёма); ответ транспорту SHALL сообщать, что запись существует и требует перепривязки либо закрытия.

Атомарный инвариант касается активной составляющей: проверка отсутствия другой активной загрузки на любом из хешей и вставка новой загрузки с её хешами SHALL выполняться в одной write-транзакции, поддерживая «не более одной активной загрузки на infohash» (тот же общий active-гард, что у прочих путей активации). Расширение критерия на desync-состояния (target_missing/orphaned) SHALL быть устойчивым пред-ридом до создания, коротко замыкающим приём на возврат существующей записи; desync-состояния в общий active-гард заводиться SHALL NOT (их терминальность оставляет state-инвариант «активности» нетронутым). Отдельного снимаемого/восстанавливаемого ключа идемпотентности в схеме быть SHALL NOT — активность выводится только из state.

Scenario: Повторный приём при активной загрузке

• GIVEN активная загрузка с infohash h
• WHEN принимается magnet с тем же h
• THEN новая загрузка не создаётся, возвращается существующая

Scenario: Повторный приём при записи без цели

• GIVEN загрузка с infohash h в target_missing (источник жив, цель удалена)
• WHEN принимается magnet с тем же h
• THEN новая загрузка не создаётся, возвращается существующая запись как Deduplicated
• AND её состояние остаётся target_missing (в активное не переводится, к qBittorrent обращения нет)
• AND ответ транспорту указывает, что запись существует и её нужно привязать заново или закрыть

Scenario: Повторный приём при осиротевшей записи

• GIVEN загрузка с infohash h в orphaned (источник пропал)
• WHEN принимается magnet/torrent с тем же h
• THEN новая загрузка не создаётся, возвращается существующая запись как Deduplicated

Scenario: Повторный приём после завершения

• GIVEN загрузка с infohash h в терминальном состоянии done
• WHEN принимается magnet с тем же h
• THEN создаётся новая загрузка со своим ULID и записью h

Scenario: Повторный приём после закрытия записи

• GIVEN загрузка с infohash h в cancelled (в т.ч. закрытая из target_missing)
• WHEN принимается magnet с тем же h
• THEN создаётся новая загрузка со своим ULID и записью h

Scenario: Повторный приём при прочих терминальных состояниях

• GIVEN загрузка с infohash h в failed или reverted (не удерживает источник ради незакрытого намерения)
• WHEN принимается magnet/torrent с тем же h
• THEN создаётся новая загрузка со своим ULID и записью h (повторный приём — свежая попытка; старая терминальная запись хешем не владеет)

Requirement: Атомарность возврата загрузки в активное состояние

Система SHALL атомарно (в одной write-транзакции) проверять на каждом пути, возвращающем загрузку из терминального состояния в активное (ручной retry, воскрешение фоновой сверкой, повторная раскладка/relink) или создающем её (приём, adopt чужой раздачи), что никакая другая активная загрузка не владеет любым из хешей этой, и при владении SHALL отказывать в переходе, сохраняя инвариант «не более одной активной загрузки на infohash». Отказ SHALL происходить до побочных эффектов во внешних системах (повторного добавления торрента в qBittorrent).

Та же проверка SHALL применяться к дозаписи хешей загрузке (раскрытие гибридного торрента) на ВСЕХ путях дозаписи, включая дедуп-дозапись при приёме: хеш, которым владеет другая активная загрузка, дописан быть SHALL NOT — ни отдельным методом дозаписи, ни дедуп-веткой атомарного заведения, которая доносит недостающие хеши найденной активной задаче. Прямой перевод терминальной загрузки в активное состояние в обход этой проверки SHALL отклоняться хранилищем (механический бэкстоп вместо удалённого unique-индекса).

Scenario: Retry при занятом хеше

• GIVEN загрузка #1 в failed с хешем h, и другая активная загрузка #2 с тем же h
• WHEN пользователь вызывает retry для #1
• THEN переход отклоняется с пояснением, #1 остаётся в failed
• AND активной по h остаётся #2

Scenario: Дедуп-дозапись не крадёт чужой хеш

• GIVEN активная загрузка A владеет хешем v1, активная загрузка B владеет хешем v2 того же гибридного торрента
• WHEN принимается источник с обоими хешами {v1, v2} и дедупится на B
• THEN B получает только незанятые хеши, а v1 (в собственности A) B не дописывается
• AND инвариант «не более одной активной загрузки на infohash» сохраняется (по v1 активна только A)

Requirement: Синтез контекста распознавания из полей magnet

При приёме система SHALL извлекать из полей magnet-ссылки дополнительный контекст и дополнять им контекст, пришедший из транспорта: факты из полей SHALL добавляться к пользовательскому тексту (пользовательский текст — первым), а при пустом тексте SHALL становиться единственным контекстом. Синтез SHALL выполняться только из самой ссылки, без сетевых запросов.

В синтез SHALL включаться следующие поля, когда они присутствуют:

• dn (display name) — как строка названия релиза, если это содержательное имя, а не заглушка-идентификатор вида *-topic-<id> (например rutracker-topic-6514485); такие заглушки в контекст-название включаться SHALL NOT.
• xl (exact length) — как человекочитаемый размер (например «≈ 2.1 GiB»); нечисловое/некорректное значение игнорируется.
• tr/xs (трекеры / exact source) — как сигнал происхождения по домену (хост трекера/источника), помогающий определить язык и тип контента.
• kt (keyword topic) — как ключевые слова.

Обогащённый контекст система SHALL сохранять в download.Context — его читают recognition (LLM-промпт) и веб-UI (страница загрузки). Синтез и слияние SHALL выполняться до создания загрузки.

Синтезированные строки-факты (размер, домен трекера, ключевые слова) SHALL NOT влиять на вывод отображаемого имени (download.display_name / параметр rename qBittorrent): вход вывода имени остаётся прежним (пользовательский текст и подсказка dn), см. требование «Отображаемое имя торрента из контекста».

Приём только по magnet (пустой текст контекста) SHALL быть штатным сценарием во всех транспортах (HTTP, Telegram, CLI).

Scenario: dn — содержательное имя релиза

• WHEN magnet содержит dn с релиз-именем (например Dune.Part.Two.2024.2160p.BluRay)
• THEN это имя добавляется в download.Context
• AND становится доступно recognition

Scenario: dn — заглушка-идентификатор темы

• WHEN dn имеет вид *-topic-<id> (например rutracker-topic-6514485)
• THEN система не включает его как строку-название в контекст
• AND остальные поля magnet (размер, домен трекера) всё равно синтезируются

Scenario: Размер из xl

• WHEN magnet содержит корректный числовой xl
• THEN в download.Context добавляется человекочитаемый размер загрузки

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

• WHEN magnet содержит tr и/или xs с распознаваемым хостом
• THEN в download.Context добавляется сигнал происхождения (домен), пригодный как подсказка языка/типа контента

Scenario: Дополнение непустого пользовательского контекста

• WHEN транспорт передал непустой текст контекста, а magnet несёт поля
• THEN download.Context содержит и текст пользователя, и факты из полей magnet (текст пользователя не теряется)
• AND текст пользователя идёт первым

Scenario: Приём только по magnet

• WHEN magnet принят с пустым текстом контекста
• THEN приём проходит штатно
• AND download.Context синтезируется из полей magnet и сохраняется

Scenario: Строки-факты не становятся отображаемым именем

• GIVEN голый magnet с заглушкой dn=rutracker-topic-<id> и трекером, без пользовательского текста
• WHEN выполняется приём
• THEN download.display_name не выводится из строк-фактов (не равен Трекер: …/Размер: …)
• AND отображаемое имя определяется прежним путём (подсказка dn или его отсутствие → без rename)

Scenario: Синтез без сети

• WHEN выполняется извлечение контекста из полей magnet
• THEN не делается ни одного сетевого запроса (только разбор строки ссылки)

Scenario: Полей для контекста нет

• WHEN текст пользователя пуст и ни одно пригодное поле magnet не даёт содержательного контекста (нет dn-имени, xl, распознаваемого домена, kt)
• THEN download.Context остаётся пустым
• AND приём проходит штатно (пустой контекст допустим)

Requirement: Приём источника из .torrent-файла

Приём SHALL принимать источник в виде байтов .torrent-файла (наряду с magnet-ссылкой) — тем же быстрым use-case, общим для транспортов. Получив непустые байты торрента, система SHALL разобрать их локально (без сети), извлечь инфохэш(и) и завести загрузку с source_type = torrent, после чего сразу вернуть ответ транспорту (синхронный путь к qBittorrent не обращается — добавление делает воркер, см. download-tracking).

Инфохэши система SHALL извлекать такими, какими их сообщает qBittorrent, чтобы сопоставление раздач и дедупликация работали: v1-хеш (для v1/гибридного файла) SHALL вычисляться как SHA1 исходных байтов info-словаря (без переэнкода); v2-хеш (для v2/гибридного файла, BEP52) SHALL извлекаться как 64-hex infohash_v2. Для чистого v2-only файла система SHALL записывать v2-хеш (v1 у него нет). Извлечение всех известных хешей и дозапись недостающих подчиняются требованию «Множество инфохэшей загрузки».

Дедупликацию по активной задаче, атомарное заведение (download в состоянии catched + записи download_infohash) и инвариант «не более одной активной загрузки на infohash» torrent-приём SHALL проходить тем же атомарным путём, что и magnet (см. «Приём источника и заведение загрузки», «Дедупликация приёма по любому из хешей», «Атомарность возврата загрузки в активное состояние»).

Байты .torrent система SHALL сохранять персистентно, привязанными к загрузке, чтобы воркер мог добавить источник в qBittorrent именно файлом (не по magnet): раздачи закрытых трекеров и торренты без DHT по magnet-хешу метаданные не получат. Сохранение байтов SHALL выполняться в той же write-транзакции, что и заведение загрузки; при дедупликации (новая загрузка не создана) байты в общем случае сохраняться SHALL NOT.

Исключение — апгрейд пойманной magnet-задачи до torrent. Если входящий источник — байты .torrent, а дедуп попал на активную загрузку с source_type = magnet, ещё НЕ отданную в qBittorrent (состояние catched), система SHALL в одной write-транзакции сохранить байты .torrent, привязав их к этой загрузке, и сменить её source_type на torrent. Тем самым воркер добавит раздачу файлом, а не magnet-хешем (иначе на закрытом трекере без DHT метаданные не докачаются, а magnet застрянет в metaDL → failed). Апгрейд SHALL применяться ТОЛЬКО пока загрузка в catched (воркер источник ещё не добавил); для уже добавленной (downloading и далее) загрузки смена source_type при дедупе выполняться SHALL NOT — её судьба решается путями retry/сверки, а не приёмом. Апгрейд SHALL быть best-effort: его неуспех приём не прерывает.

Из полей .torrent система SHALL синтезировать контекст распознавания (имя раздачи, суммарный размер, сигнал по дереву файлов, домен трекера, комментарий) и дополнять им контекст транспорта — тем же правилом слияния, что и синтез из полей magnet (пользовательский текст первым; при пустом тексте — только синтез). Обогащённый контекст система SHALL сохранять в download.Context. Синтез SHALL выполняться без сетевых запросов.

source_ref у torrent-загрузки SHALL быть человекочитаемым референсом (имя раздачи или файла), а НЕ адресом добавления: добавление в qBittorrent идёт байтами, и трактовать source_ref как magnet/URL для добавления система SHALL NOT.

Scenario: Быстрый приём .torrent-файла

• GIVEN валидные байты .torrent-файла и (опц.) текст контекста
• WHEN вызывается приём
• THEN из файла извлекаются инфохэши и создаётся download в состоянии catched (source_type = torrent) с записями download_infohash
• AND байты файла сохраняются привязанными к загрузке
• AND ответ транспорту отдан без обращения к qBittorrent

Scenario: Инфохэш из исходных байтов info

• WHEN система разбирает v1/гибридный .torrent-файл
• THEN инфохэш v1 вычисляется как SHA1 исходных байтов info-словаря
• AND совпадает с хешем, по которому qBittorrent позже сопоставит раздачу

Scenario: v2-only файл записывается под v2-хешем

• WHEN система разбирает .torrent только с метаданными v2 (без v1)
• THEN у загрузки записывается v2-хеш (64-hex), совпадающий с infohash_v2 qBittorrent
• AND сопоставление раздачи работает по нему

Scenario: Дубль .torrent по активной torrent-задаче

• GIVEN уже есть активная (в т.ч. catched) загрузка с тем же infohash и source_type = torrent
• WHEN принимается .torrent с тем же инфохэшем
• THEN новая загрузка не создаётся, возвращается существующая
• AND байты торрента повторно не сохраняются (дубль)

Scenario: Апгрейд catched-magnet до torrent

• GIVEN активная загрузка в catched с source_type = magnet и хешем h (magnet-задача ещё не отдана в qBittorrent)
• WHEN принимается .torrent с тем же инфохэшем h
• THEN новая загрузка не создаётся, возвращается существующая
• AND байты .torrent сохраняются привязанными к ней, а её source_type становится torrent — в одной транзакции
• AND воркер добавит раздачу файлом (не по magnet)

Scenario: Magnet-задача уже добавлена — апгрейда нет

• GIVEN активная загрузка с source_type = magnet уже в downloading (отдана в qBittorrent)
• WHEN принимается .torrent с тем же инфохэшем
• THEN возвращается существующая загрузка, её source_type остаётся magnet, байты .torrent не сохраняются

Scenario: Контекст из полей файла

• WHEN принят .torrent с именем раздачи, деревом файлов и трекерами
• THEN в download.Context добавляется синтез (имя, размер, сигнал по файлам, домен трекера), дополняющий текст транспорта
• AND синтез выполнен без сетевых запросов

Scenario: Слишком большой .torrent отклоняется

• WHEN принимаемый .torrent-файл превышает ограничение размера
• THEN приём отклоняется с ошибкой, загрузка не создаётся

Requirement: Сохранение извлечённой из контекста структуры имени

Система SHALL сохранять структуру имени, извлечённую LLM со структурированным выводом на шаге добавления (тип, название, оригинальное название, год, режиссёр, сезон), у загрузки (download.parsed_context, JSON), чтобы её поля могли переиспользоваться при последующем выводе имени без повторного вызова LLM. Алгоритмический фолбек структуры не даёт (его выход — только строка имени), тогда parsed_context остаётся пустым — это штатно (нижний слой отсутствует). Сохранённая структура SHALL быть базовым (наименее доверенным) слоем источника полей имени: её значения берутся, только если более доверенный слой (распознавание/матч, ручные правки) соответствующего поля не дал.

Сохранение SHALL быть best-effort и косметическим: неудача записи parsed_context SHALL NOT проваливать добавление загрузки, а сама структура SHALL влиять только на отображаемое имя и SHALL NOT влиять на пути файлов, распознавание или раскладку. Пустая/невыведенная структура (нет контекста и подсказки) SHALL приводить к пустому parsed_context (нечего сохранять).

Scenario: Извлечённый режиссёр сохраняется у загрузки

• GIVEN контекст загрузки, из которого LLM извлёк режиссёра и год
• WHEN система выводит имя на шаге добавления
• THEN извлечённая структура (в т.ч. режиссёр) сохраняется в download.parsed_context
• AND отображаемое имя формируется как и прежде (полный ярлык)

Scenario: Сбой сохранения структуры не валит добавление

• GIVEN запись parsed_context завершается ошибкой
• WHEN идёт шаг добавления загрузки
• THEN загрузка всё равно добавляется в qBittorrent (с rename, если имя выведено)
• AND ошибка логируется, приём/добавление не проваливается

Scenario: Пустой вход — пустая структура

• GIVEN пойманная загрузка без контекста и без подсказки из полей источника
• WHEN выполняется шаг добавления
• THEN структура не выводится, download.parsed_context пуст