RAGRAF 0.11.0: контракт-пин и пробы поведения

RAGRAF 0.11.0 — выпуск не про новые возможности поиска, а про доказательство: поставка должна сама показывать, что не разошлась с обещанным. Появились контракт-пин с причиной расхождения, журнал смен набора, пробы поведения по хешу ответа и единая точка, где считается вердикт выпуска. Поверхность выросла до 79 операций и 86 инструментов MCP — в 0.10.0 было 76 и 83. Ниже — что именно добавилось, как это проверить и что в опубликованном дереве расходится с заметками к релизу.

TL;DR: что в этом выпуске

1. Контракт-пин. Описание операции сверяется с подтверждённым набором; расхождение называется причиной, а не «разошлось».
2. Журнал смен набора. Кто, когда и что принял — как операция, а не запись в файле. Хранение: 20 смен на объект и всё за 180 дней.
3. Пробы поведения. Операция вызывается на образцах, ответ хешируется и сверяется с прошлым выпуском; отказ очищается от путей и ревизий.
4. Итог выпуска одной строкой. Вердикт, код возврата и три представления считаются в одном месте, поэтому не могут разойтись.
5. Проверка. python tools/surface_gen.py --check печатает 79 / 86 / 26 / 20 и отпечаток 78789dc47078.

python tools/surface_gen.py --check
# поверхность (проверка): операций 79, инструментов 86, подкоманд 26, возможностей 20, отпечаток 78789dc47078
ragraf --version
# ragraf 0.11.0

Что нового

Выпуск отвечает на вопрос, который обычно задают после инцидента: «а обещали то же самое?» До сих пор ответ собирался руками — сравнить документацию, вспомнить, что было в прошлом релизе, посмотреть, не поменялся ли ответ операции.

Теперь это четыре отдельные вещи. Пин фиксирует подтверждённый набор описаний. Журнал рассказывает, кто и когда этот набор менял. Пробы проверяют, что операция действительно отвечает так, как записано. Итог выпуска сводит вердикт в одну строку, чтобы три отчёта не могли сказать разное.

flowchart TB
  OPS["описание операции"] --> PIN["подтверждённый набор: пин"]
  PIN --> CMP{"сравнение с прошлым выпуском"}
  CMP -- расхождение --> CAUSE["причина: ломающее, совместимое, изменённое"]
  CMP -- совпало --> OK["без изменений"]
  CAUSE --> DEC{"решение"}
  DEC -- мажорная версия --> PASS["проход"]
  DEC -- поимённое разрешение --> PASS2["проход с автором и причиной"]
  DEC -- иначе --> STOP["блокировка"]

Важная деталь в том, как устроены пробы: отказ очищается от путей, ревизий индекса и хешей. Без этой нормализации «изменилось» срабатывало бы на каждой сборке — и проба превратилась бы в шум, который отключают через неделю.

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

Контракт-пин

Последняя строка — самая содержательная. Обычно в таких системах есть кнопка «принять всё», и через месяц никто не помнит, что именно приняли. Здесь её нет: разрешение выдаётся по имени операции, с причиной.

Журнал смен набора

Отсюда следует приятное свойство: история не «чистится по расписанию целиком», а сокращается так, чтобы действующий контракт оставался объяснимым.

Пробы поведения

flowchart LR
  CALL["вызов операции на образцах"] --> HASH["хеш ответа"]
  HASH --> NORM["отказ очищен от путей, ревизий и хешей"]
  NORM --> DIFF{"совпало с прошлым выпуском?"}
  DIFF -- да --> SAME["проба в порядке"]
  DIFF -- нет --> ISSUE["расхождение с местом"]
  SAME --> ACC["приём требует имени автора"]
  ISSUE --> ACC

Имя автора в приёме — не бюрократия. Проба, принятая «системой», не отвечает на вопрос «кто решил, что это нормально».

Итог выпуска и отчёт

flowchart TD
  VERD["вердикт и код возврата"] --> OUT1["stdout"]
  VERD --> OUT2["markdown"]
  VERD --> OUT3["JSON"]
  CHG["блок changes: что изменилось с прошлого выпуска"] --> OUT2
  CHG --> OUT3

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

Проверено 10.11.2026: прогон в клоне дерева и проверка опубликованного тега.

Отпечаток сходится в трёх местах — в проверке, в docs/surface.json опубликованного тега и в заметках к релизу. Это, пожалуй, самый практичный результат замера: зная отпечаток, можно за секунду понять, о какой ревизии поверхности говорит человек в переписке.

Что не сошлось. В заметках сказано, что RELEASE-REPORT.md собирается из ops_pins.json, «лежащего рядом», сверяется воротами по байтам и входит в checksums.sha256. В опубликованном дереве тега v0.11.0 оба файла отдают 404, а в checksums.sha256 (930 строк) нет ни строки про отчёт. Причина, скорее всего, та же, что названа в разделе «Известное»: полный гейт выпуска требует источника с каталогом community/, а в поставку он не входит. То есть отчёт собирается на сборочном дереве и в тег не попадает. Это расхождение заметок с содержимым тега, а не поломка самого продукта — но проверять его стоит до того, как на отчёт сошлётся кто-то извне.

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

• Расхождение объясняется. Причина вместо «разошлось» экономит часы разбора.
• Нет «разрешить всё». Каждое ломающее изменение проходит по имени и с причиной.
• Журнал как операция. История смен набора читается теми же средствами, что и сам продукт.
• Пробы нормализованы. Очистка от путей и ревизий убирает ложные срабатывания.
• Автор приёма обязателен. Проба не может быть принята анонимно.
• Один источник вердикта. stdout, markdown и JSON не расходятся по определению.
• Отпечаток поверхности. Одна строка вместо спора о том, сколько было операций.
• Честный раздел «Известное». Ограничение сборочного гейта названо, а не спрятано.

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

pip install --upgrade ragraf
ragraf --version            # ragraf 0.11.0
ragraf edition              # 20 возможностей
ragraf selftest

Если вы сравниваете поставку с прошлой, начните с отпечатка поверхности: он сразу покажет, та ли это ревизия, а не «почти та».

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

Две тонкости. Первая: surface_gen.py --check на опубликованном дереве может показать находки про отсутствующие файлы community/README.*.md — это ожидаемо, потому что источник живёт отдельно от поставки. Вторая: отпечаток печатает именно surface_gen.py, а не команда edition — она показывает список возможностей без отпечатка.

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

Прирост поверхности относительно 0.10.0 — три операции и три инструмента: контракт-пин прибавил историю и пробу, плюс разностная операция сравнения. Это не «новый продукт», а расширение уже существующей возможности, что для минорного выпуска правильно.

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

• RELEASE-REPORT.md в теге нет. Проверено: в дереве v0.11.0 файл отдаёт 404, и в checksums.sha256 он не упомянут. Ждать отчёт «из коробки» не стоит.
• surface_gen.py --check краснеет на опубликованном дереве. Причина — отсутствующие community/README.*.md; числа при этом печатаются верно.
• Отпечаток печатает surface_gen.py, а не edition. Команда edition даёт список возможностей без отпечатка — это разные вещи.
• Пробы без нормализации бесполезны. Если вы пишете свои пробы по этому образцу, очищайте ответ от путей и ревизий, иначе расхождение будет на каждой сборке.
• Ломающее изменение нельзя «принять всё». Разрешение только поимённое с причиной — планируйте это в процессе, а не в момент выпуска.
• Журнал сокращается. 20 смен на объект и 180 дней: старые записи уходят, кроме тех, на которые ссылается действующий пин.
• Обновление пакета не переиндексирует корпус. Пометки и данные пробы опираются на индекс, который надо обновить отдельной командой.
• Требуется источник с community/. Полный гейт выпуска в опубликованном дереве не пройдёт — так и записано в «Известном».

FAQ

Итог

0.11.0 добавляет то, чего обычно не хватает в инструментах для агентов: возможность доказать, что поставка не разошлась с обещанием. Пин называет причину, журнал показывает автора, проба сверяет ответ по хешу, а вердикт считается в одном месте. Проверка подтвердила числа и отпечаток — 79 операций, 86 инструментов, 26 подкоманд, 20 возможностей, 78789dc47078 — и заодно показала расхождение заметок с деревом тега: отчёта выпуска и ops_pins.json в опубликованной поставке нет. Это стоит знать до того, как на них сошлётся внешний аудит.

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

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

• RAGRAF: обзор продукта — корпуса, операции фасада, MCP, издания.
• RAGRAF 0.10.0: каскад устаревания и след сбоя — предыдущий выпуск и его две возможности.
• Cert Unifier 3.1.1 — та же дисциплина «проверка до записи».
• Fornex Control: панель для DNS-зон — предпросмотр плана как способ не ломать прод.
• Релиз v0.11.0 на GitHub — заметки и дерево.

LLM Summary

• Тема: RAGRAF 0.11.0 — выпуск о доказательстве поставки: контракт-пин, журнал смен набора, пробы поведения, единая точка вердикта.
• Контракт-пин: описание операции сверяется с подтверждённым набором; расхождение получает причину; сводка с прошлым выпуском делится на ломающие, совместимые и изменённые; ломающее проходит при мажорной версии или поимённым разрешением с причиной; режима «разрешить всё» нет.
• Журнал смен: хранится как операция, а не как файл; 20 смен на объект и всё за 180 дней; строки, на которые ссылается действующий пин, не удаляются.
• Пробы поведения: вызов на образцах, хеш ответа, сверка с прошлым выпуском; отказ очищается от путей, ревизий и хешей; приём требует имени автора.
• Итог выпуска: вердикт, код возврата и три представления (stdout, markdown, JSON) считаются в одной точке; блок changes называет изменения с местами, без значений.
• Замерено 10.11.2026: ragraf 0.11.0; tools/surface_gen.py --check → 79 операций, 86 инструментов, 26 подкоманд, 20 возможностей, отпечаток 78789dc47078; в docs/surface.json тега counts.ops = 79, 86 инструментов, digest 78789dc4707881a1…; checksums.sha256 — 930 строк; ragraf.ru и страница релиза — 200.
• Расхождение: в дереве тега v0.11.0 файлы RELEASE-REPORT.md и ops_pins.json отсутствуют (404), в checksums.sha256 отчёт не упомянут — вероятная причина в ограничении сборочного гейта (нужен источник с community/).
• Не проверялось: сами операции пина, журнала и проб на живом корпусе — нужен корпус с историей ревизий.
• Ссылки: https://github.com/paulmann/RAGRAF/releases/tag/v0.11.0, https://sysadministrator.ru/ragraf/

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

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

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

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

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

Шаг 2. Сверить поверхность и отпечаток:
python tools/surface_gen.py --check
# ожидается: операций 79, инструментов 86, подкоманд 26, возможностей 20, отпечаток 78789dc47078
# находки про отсутствующие community/README.*.md на опубликованном дереве — ожидаемы

Шаг 3. Сверить отпечаток в файле: docs/surface.json, поле digest, первые 12 знаков.
Шаг 4. Посмотреть список возможностей: ragraf edition (20, из них 14 в Pro).
Шаг 5. Обновить индекс при изменении документов: ragraf ensure <корпус>.
Шаг 6. Проверить состояние пина и журнал смен операциями контракт-пина.
Шаг 7. Запустить пробу в режиме сравнения и прочитать расхождения с местами.
Шаг 8. Сверить итог выпуска: вывод в JSON и stdout должны говорить одно и то же.

Запрещено:
- считать, что `edition` печатает отпечаток: отпечаток печатает surface_gen.py;
- искать RELEASE-REPORT.md в дереве тега: в v0.11.0 его нет (проверено, 404);
- принимать ломающее изменение «всё разом»: только поимённо и с причиной;
- писать свои пробы без очистки ответа от путей и ревизий;
- оформлять приём пробы без имени автора;
- выдавать числа 79 и 86 за результат `ragraf edition`: их даёт surface_gen.py.

Что считать успехом: версия 0.11.0, отпечаток совпадает в трёх местах (проверка, docs/surface.json, заметки), пин подтверждён, журнал смен читается, проба сравнилась без расхождений либо показала их с местом.