Tesserae v0.25.1 — компиляция больше не зависает, деградировавшие документы восстанавливаются

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Español · Français · Deutsch

<!-- translations:end -->

Выпущено 2026-07-25 · PyPI · GitHub release · pip install --upgrade tesserae==0.25.1

Выпуск исправлений. Никаких изменений API — работает вместо v0.25.0 без переделок, только один параметр по умолчанию изменился (см. Обновление).

Каждое исправление вышло из одного расследования. Компиляция на реальном проекте зависала при 0% CPU в течение 5 часов 43 минут, за codex exec-дочерним процессом, который простаивал 4 часа 6 минут. Процесс уже создал 32 узла COMMUNITY_SUMMARY в памяти, но так и не сохранил их, поэтому graph.json закончилась с нулём. Потянув за эту нить, мы обнаружили три дополнительных дефекта.

Исправления

• Страховка от зависания при извлечении включена по умолчанию. v0.25.0 поставил таймаут на извлечение по файлам, но опционально — поэтому он остался выключен и ошибку, которую он предотвращает, продолжали видеть. killpg процесс-группы в _run_cli была проводится корректно всё время; просто никогда не срабатывала, потому что communicate(timeout=None) никогда не выбрасывает. Лимит теперь 1800 с на одну попытку по умолчанию. Убийство зависшего дочернего процесса позволило родительской компиляции возобновиться за секунды — она ждала в communicate() четыре часа.

Опечатка не должна молча разоружать предохранитель, поэтому непригодное значение (10m, 600s, отрицательное, inf) теперь выдаёт предупреждение и сохраняет умолчание вместо отката на "без ограничений". TESSERAE_EXTRACT_TIMEOUT=0 — явный люк спасения.

• compile --retry-fallbacks восстанавливает документы, деградировавшие до детерминированного. Когда извлечение не удаётся, документ раздаётся детерминированным базовым вариантом — но его запись в манифесте была байт-идентична чистому извлечению, так что --changed-only пропускала её при каждой следующей компиляции и деградация была постоянной, пока самое содержимое файла не изменилось. Восстановление горстки документов требовало ручного редактирования manifest.json, с постоянным риском вместо того заполнить весь корпус детерминированно и уничтожить часы типизированной работы. Такие записи теперь отмечаются и переопробуются по требованию, зеркалируя distill --retry-fallbacks.
• live_member_count на карточках graph_map. size и leaf_member_count оба идут из сайдкара hierarchy.json, который записывается в середине компиляции. Когда graph.json переписывается потом, эти две величины расходятся, и карточка может объявлять сотни участников, которые на деле ни на что не разрешаются — без способа для клиента отличить её от здоровой карточки, кроме как перечитать сам graph.json. Карточки, выведённые из графа (kind=community|node), теперь также сообщают, сколько участников носит текущий граф. 0 означает, что область мертва: пропустите её вместо спуска.

На одном реальном графе из 7,133 узлов это сразу вскрыло 2 мёртвые корневые карточки и 42 частично разрешённые, на которые никто не обратил внимания.

• Сыворотка тестов _CLIENT_FACTORY чтит таймаут вызывающего. build_default_json_client бросила его, отдав инжектированной подделке 30 с по умолчанию в любом случае — так что тест, привязывающий таймаут, молча ничего не доказывал. Только сыворотка; продакшн-сборка была уже правильна.

Обновление с v0.25.0

Работает вместо v0.25.0 без переделок, с одним замечанием: извлечение теперь ограничено по умолчанию (1800 с на одну попытку). Если вы специально хотите неограниченные прогоны, установите TESSERAE_EXTRACT_TIMEOUT=0.

Лимит за попытку, не за документ — на таймауте клиент ротирует на следующий CODEX_HOME / конфиг-каталог claude, поэтому худший случай документа — timeout × configured profiles.

Если прошлая компиляция оставила документы застрявшими на детерминированном извлечении, восстановите их с:

tesserae compile --changed-only --retry-fallbacks

Переопробуются только документы, чьё типизированное извлечение действительно не удалось; чистые остаются пропущены.