arm-ka-docs/openspec/changes/document-statements-library-contract/design.md

Design

Context

Код библиотеки, подключение в сервисах и их change — в PR задачи AURORA-1677 (arm-core #178, tabular-parser #70, scan-gateway #52, RSHB/pylib_ai_arm_statements). Этот change — сквозная часть в docs: контракт, спеки, контекст и инструменты docs, которые обслуживали копии. Первая версия change (23.10.2026) обновляла только описания контракта и добавляла заметки-баннеры; при ревью 27.10.2026 change расширен до полного перевода docs на библиотеку.

Goals / Non-Goals

Goals: docs не описывают копии api/arm_statements/ и sync-statements как действующие; сверки, которые делал sync-statements --check, не теряются; снимок для контура проходит на сервисах с библиотекой.

Non-Goals: алгоритмы §7/§11, структура контракта, DBML, перенос репозитория библиотеки в контур.

Decisions

1. Что делал sync-statements --check и куда это ушло. Равенство копии источнику и «копия отстала» — больше не нужны (копий нет, версия закреплена в requirements.txt). Зависимости пакета в зависимостях хоста — проверяет установщик pip. Коды словаря имён ядра в перечне — тест ядра test_name_dictionary_codes_in_code_orders (был и раньше, работает с установленной библиотекой). Перечень кодов docs против копии в библиотеке — новая цель statements-orders-check в make -C docs check.
2. statements-orders-check — предупреждение, не ошибка. Как и код 10 прежнего --check: порядок правки «docs → библиотека → версия в сервисах», и docs законно бывает впереди до выпуска библиотеки. Нет checkout библиотеки рядом — тоже предупреждение (docs проверяется и без соседей).
3. Снимок для контура вырезает цель install. Цель ставит библиотеку из соседнего checkout через uv; в контуре библиотека приходит из Nexus по requirements.txt через цель venv снимка. Без этого проверка снимка «нет uv» падает на всех трёх сервисах (проверено на ветках PR 27.10.2026).
4. Требования спек — REMOVED + ADDED, а не MODIFIED. OpenSpec не даёт убрать сценарий через MODIFIED, а сценарии про копии (прямая правка копии, тесты копии) больше не верны. Старые требования удалены с Reason/Migration, новые — под новыми именами.
5. STATEMENTS_VERSION_MISMATCH на заданиях до перехода не исправляется (решение владельца 26.10.2026): у таких заданий statements_version — хэш коммита копии, у ядра — версия библиотеки; запись info ожидаема и на статус не влияет. Записано в спеку statement-normalization и в §9.5 05-domain-rules.

Decisions made without discussion

• 27.10.2026 — statements-orders-check не валит make check при расхождении перечня с библиотекой (решение 2). Обоснование — прежняя семантика кода 10. Цена ошибки — расхождение перечня docs и библиотеки может жить до следующего выпуска незамеченным, если предупреждение не читать.
• 27.10.2026 — шапка contracts/statement-code-orders.yaml (упоминала sync-statements) поправлена в docs сейчас, байтовая копия уходит в библиотеку выпуском 0.1.2. До него statements-orders-check предупреждает о расхождении с v0.1.1 — это ожидаемо (данные перечня не менялись, только комментарий). Цена ошибки — предупреждение в make check docs до выпуска 0.1.2.
• 27.10.2026 — комментарий recognition_job.statements_version в DBML v5.23 и entities-v5.23.md («коммит копии») не правится: правка DBML требует новой версии модели. Цена ошибки — устаревшее описание поля до следующей версии DBML.
• 27.10.2026 — описание service.statements_version в контракте оставлено как в первой версии change («маркер VERSION, если есть, иначе версия дистрибутива»), хотя в установленном пакете маркера нет: оно совпадает с кодом arm_statements/version.py библиотеки v0.1.1. Цена ошибки — описание сложнее фактического поведения.

Risks / Trade-offs

• [Репозиторий библиотеки не переносится в контур скриптом снимка] → выкладка требует, чтобы нужная версия уже была в Nexus; процедура переноса — вопрос владельцу, в этом change не решается.
• [Старые change в архиве ссылаются на sync-statements] → архив — история, не правится.