RAGRAF 0.10.0: каскад устаревания и след сбоя

RAGRAF 0.10.0 — релиз, которым закрывается план доработки: восемь блоков из девяти закрыты, девятый частичен по делу. Две новые возможности касаются того, что обычно остаётся за кадром: что делать, когда входной документ изменился (устаревание фактов расходится по цепочке) и что делать, когда сбой однажды подтвердили (он должен не потеряться). Поверхность выросла до 76 операций фасада, 83 инструментов MCP и 20 возможностей. Ниже — что именно добавилось, как проверить обновление и на чём спотыкаются те, кто ставит индекс поверх старого.

TL;DR: что в этом релизе

1. План закрыт. Восемь блоков из девяти; девятый — пин на живом корпусе — остаётся подтверждением человека.
2. provenance (Pro). Операция stale_cascade: каскад по рёбрам «факт → факт» от изменённых входов, отчёт «что пересчитать» с адресом, расстоянием и причиной.
3. quality-loop (Pro). Операция quality_trace: подтверждённый сбой сохраняется целиком и при повторе называет вердикт — still_failing, fixed, other_rev, not_reproducible.
4. Контракт операций (Enterprise). pin_break пишется и на ошибку аргументов (bad_arguments), причина — из закрытого списка.
5. Проверка обновления. ragraf --version → ragraf 0.10.0; ragraf edition → 20 возможностей, среди них provenance и quality-loop.

ragraf --version            # ragraf 0.10.0
ragraf edition              # возможностей: 20, в списке provenance и quality-loop
ragraf query stale_cascade --json   # отчёт «что пересчитать» (Pro)

Что нового

Релиз не про новую форму данных, а про два вопроса, которые до него решались вручную.

Первый: индекс описывает код, код меняется, а факты в индексе остаются. Раньше ответ на «что теперь пересчитать» давал сам инженер — глазами по графу. Теперь это делает stale_cascade: он идёт по рёбрам от изменённого входа и выдаёт список с адресом, расстоянием и причиной.

Второй: сбой, который однажды подтвердили и починили, жил в переписке. Через месяц никто не помнил, на какой ревизии он воспроизводился. quality_trace сохраняет кейс целиком: объявление, шаги сеанса, решения гейта, ревизию индекса и отпечаток содержимого. Повтор не «плодит записей» и не объявляет исправление на другой ревизии.

flowchart TB
  IDX["индексация корпуса"] --> HASH{"sha256 версии документа изменился?"}
  HASH -- да --> MARK["пометка в fact_stale"]
  HASH -- нет --> SKIP["факт остаётся свежим"]
  MARK --> CASC["stale_cascade: каскад по рёбрам факт в факт"]
  CASC --> REP["отчёт: адрес, расстояние, причина"]
  REP --> APPLY["apply ставит пометки, clear-marks закрывает после пересчёта"]

Ключевые изменения

Возможность provenance: каскад устаревания

Смысл в том, что пометки ставятся не «на глаз», а по доказательству: если версия документа в предыдущей ревизии отличается по sha256, факты, зависящие от него, помечаются автоматически при индексации. Дальше каскад расходится по рёбрам, а outside_cap честно говорит, что часть графа осталась за пределом обхода — вместо тихого умолчания.

Возможность quality-loop: след подтверждённого сбоя

flowchart LR
  FAIL["подтверждённый сбой"] --> SAVE["quality_trace сохраняет кейс"]
  SAVE --> SNAP["шаги сеанса, решения гейта, ревизия индекса, отпечаток"]
  SNAP --> AGAIN{"повтор на той же ревизии?"}
  AGAIN -- да --> STILL["still_failing или fixed"]
  AGAIN -- нет --> OTHER["other_rev"]
  SNAP --> NR["not_reproducible, если не воспроизвелось"]

Здесь ценна именно строгость вердикта. «Исправлено» на другой ревизии не заявляется: изменился индекс — значит, воспроизводить заново, а не переносить прежний вывод. Для агентской работы это ровно то, чего не хватало: след сбоя остаётся проверяемым, а не превращается в воспоминание.

Контракт операций (Enterprise)

Смысл изменения в том, что «неизвестное имя» и «неправильные аргументы» — разные причины отказа, и раньше вторая терялась. Теперь обе попадают в pin_break, а закрытый список причин не даёт написать произвольную строку.

Поверхность

flowchart TD
  CLI["CLI: 26 подкоманд"] --> FAC["фасад: 76 операций"]
  FAC --> MCP["MCP: 83 инструмента"]
  FAC --> CAP["20 возможностей, из них 14 в Pro"]
  CAP --> P1["provenance"]
  CAP --> P2["quality-loop"]
  CAP --> P3["shared-index, contract-pin, sso"]

Замеры и цифры

Проверено 10.11.2026: локальная установка и живые адреса.

Что замеры не показывают: числа «76 операций» и «83 инструмента MCP» я взял из заметок к релизу — прямого счётчика в CLI для них нет, а разбирать внутренние реестры ради цифры смысла мало. Проверено то, что проверяется одной командой: версия, число подкоманд, список возможностей и наличие модулей. Также не запускались сами stale_cascade и quality_trace: для них нужен корпус с историей ревизий, а это уже отдельная работа, а не проверка релиза.

Сильные стороны релиза

• План закрыт, а не «отложен». Восемь блоков из девяти, и это записано прямо, а не спрятано.
• Устаревание доказано, а не угадано. Пометка ставится по расхождению sha256 версии документа.
• Каскад говорит о своих пределах. outside_cap вместо тихого обрезания обхода.
• Вердикт повтора строгий. «Исправлено» — только на той же ревизии индекса.
• Записи не размножаются. Пройденный кейс не пишется, повтор не создаёт дубль.
• Отказ объясним. Причина pin_break берётся из закрытого списка.
• Тесты по свойствам. 66 и 42 свойства соответственно — не «пример работает», а утверждения о поведении.
• Поверхность не растёт вширь. 76 операций, 83 инструмента, 26 подкоманд — цифры названы и проверяемы.

Установка и обновление

pip install --upgrade ragraf
ragraf --version
ragraf edition
ragraf selftest

Отдельно про индекс: обновление версии не переиндексирует корпус само. Если в вашем корпусе документы менялись, разумно после обновления запустить ragraf ensure — именно на этом шаге ставятся пометки устаревания по sha256 предыдущей ревизии.

Проверка после обновления

Совместимость

Что стоит держать в голове при обновлении на Enterprise: если у вас есть разбор pin_break по коду причины, добавьте bad_arguments в обработку — иначе новый случай попадёт в «неизвестное».

Подводные камни

• Обновление не переиндексирует корпус. Пометки устаревания появляются только при индексации, а не от смены версии пакета.
• stale_cascade — возможность Pro. В Community команда ответит отказом, и это ограничение издания, а не ошибка установки.
• outside_cap — не ошибка. Он означает, что часть графа за пределом обхода; молчаливое «всё пересчитано» было бы хуже.
• «Исправлено» привязано к ревизии. После переиндексации прежний вердикт fixed не переносится — кейс надо воспроизвести заново.
• Пройденный кейс не сохраняется. Не удивляйтесь, что зелёный тест не оставил следа: так задумано, чтобы база не пухла.
• pin_break теперь пишется чаще. Это не шум: ошибки аргументов раньше просто терялись.
• Число возможностей зависит от издания. В установке видно enterprise при заявленном community — смотрите на фактический вывод edition, а не на бейдж.
• Часть поверхностей не измеряется из CLI. Числа 76 и 83 — из заметок к релизу; проверять их напрямую нечем.
• Пин на живом корпусе не автоматизирован. Девятый блок плана остаётся подтверждением человека — и это стоит планировать в работе, а не надеяться на автозакрытие.

FAQ

Итог

0.10.0 — релиз, который закрывает план и добавляет две вещи, которых в агентской работе не хватает больше всего: доказанное устаревание фактов и проверяемый след сбоя. Проверка на установке подтвердила главное: версия 0.10.0, 26 подкоманд, 20 возможностей с provenance и quality-loop, модули на месте. Числа 76 операций и 83 инструментов остаются на совести заметок к релизу — из CLI их не измерить, и об этом честнее сказать, чем приводить как проверенный факт.

Цитата: Индекс без доказательства устаревания — это не память, а слухи с адресами.

Связанные материалы

• RAGRAF: обзор продукта — большой разбор: корпуса, операции фасада, MCP, издания.
• Cert Unifier 3.1.1 — та же дисциплина «сначала проверка, потом запись».
• HTML.PHP: шаблонизатор PHP в одном файле — про поверхность API, которую можно прочитать целиком.
• github-agent 1.3.0 — проверка репозиториев по формальным признакам.
• Релиз v0.10.0 на GitHub — заметки и файлы.

LLM Summary

• Тема: RAGRAF 0.10.0 — релиз, закрывающий план доработки: восемь блоков из девяти, девятый (пин на живом корпусе) остаётся подтверждением человека.
• Поверхность: 76 операций фасада, 83 инструмента MCP, 26 подкоманд CLI, 20 возможностей (14 в Pro).
• Новое provenance (Pro): stale_cascade идёт каскадом по рёбрам «факт → факт» от изменённых входов,отчёт с адресом, расстоянием и причиной (cause_fact_id, input_fact_id); outside_cap за пределом глубины; apply и clear-marks; пометки ставятся при индексации по sha256 версии документа из предыдущей ревизии; 66 свойств в тестах.
• Новое quality-loop (Pro): quality_trace сохраняет подтверждённый сбой целиком (шаги сеанса, решения гейта, ревизия индекса, отпечаток содержимого); вердикты still_failing, fixed, other_rev, not_reproducible; «исправлено» только на той же ревизии; 42 свойства в тестах.
• Контракт (Enterprise): pin_break пишется и для bad_arguments, причина из закрытого списка, единая точка разбора аргументов.
• Проверено 10.11.2026: ragraf --version → ragraf 0.10.0; 26 подкоманд (совпало с заметками); ragraf edition → 20 возможностей с provenance и quality-loop; provenance.py 1 034 строки, quality_traces.py 244, facade.py 9 089, mcp_server.py 4 310; живые адреса обзора, ragraf.ru и страницы релиза — 200.
• Не проверялось: сами stale_cascade и quality_trace (нужен корпус с историей ревизий); числа 76 и 83 взяты из заметок к релизу — счётчика в CLI нет.
• Ссылки: https://github.com/paulmann/RAGRAF/releases/tag/v0.10.0, https://sysadministrator.ru/ragraf/

Промт для агента (установка и настройка)

Готовый промт: скопируйте блок целиком. Источник шагов — README.md репозитория и заметки к релизу 0.10.0, сверенные с локальной установкой; файла AGENTS.md в репозитории нет (проверено, HTTP 404).

Задача: обновить RAGRAF до 0.10.0, проверить поверхность и убедиться, что пометки устаревания появляются после индексации.

Материалы:
- репозиторий: https://github.com/paulmann/RAGRAF
- релиз: https://github.com/paulmann/RAGRAF/releases/tag/v0.10.0
- обзор продукта: https://sysadministrator.ru/ragraf/

Шаг 1. Обновить пакет и проверить версию:
pip install --upgrade ragraf
ragraf --version        # ожидается: ragraf 0.10.0

Шаг 2. Посмотреть издание и возможности:
ragraf edition          # ожидается 20 возможностей, среди них provenance и quality-loop

Шаг 3. Самопроверка окружения: ragraf selftest

Шаг 4. Обновить индекс корпуса: ragraf ensure <корпус>
            (без этого шага пометки устаревания не появятся: они ставятся при индексации)

Шаг 5. Проверить каскад устаревания: ragraf query stale_cascade --json
            Ожидается отчёт с адресами и причинами либо пустой список. Поле outside_cap означает предел глубины, а не ошибку.

Шаг 6. Проверить след сбоя: ragraf query quality_trace --name <кейс>
            Ожидаются вердикты still_failing, fixed, other_rev или not_reproducible.

Шаг 7. На Enterprise добавить причину bad_arguments в обработку pin_break.

Запрещено:
- считать, что обновление пакета переиндексирует корпус;
- трактовать outside_cap как сбой;
- объявлять сбой исправленным на другой ревизии индекса;
- ожидать stale_cascade в Community: это возможность Pro;
- приводить числа 76 операций и 83 инструмента как измеренные: счётчика в CLI нет, это данные заметок к релизу.

Что считать успехом: версия 0.10.0, edition показывает 20 возможностей, selftest чист, ensure дал actual или reindexed, stale_cascade отвечает отчётом, quality_trace возвращает вердикт.