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

Proposal

Why

AURORA-1677: общий код нормализации ББ/ОФР arm_statements переведён из копий в сервисах (api/arm_statements/, скрипт sync-statements) в Python-библиотеку pylib-ai-arm-statements (репозиторий RSHB/pylib_ai_arm_statements, тег v0.1.1), которую сервисы ставят зависимостью. Сквозная документация, спеки docs и скрипты docs ещё описывают копии: sync-statements, statements-check, шаг 0a снимка для контура, маркер версии «коммит копии».

What Changes

• Контракт recognition-result.schema.json: два description — нормализация библиотекой и источник service.statements_version; структура, обязательность и ограничения не меняются, schema_version остаётся 2.0. Копии схемы в arm-core, tabular-parser и scan-gateway обновляются в их PR той же задачи.
• BREAKING (инструменты docs): удалены scripts/sync-statements.sh, scripts/test_sync_statements.sh, scripts/statements_check.py и цели sync-statements, statements-check, test-sync-statements. Вместо сверки перечня кодов в копиях — цель statements-orders-check (в make check): contracts/statement-code-orders.yaml против байтовой копии в библиотеке, расхождение — предупреждение.
• scripts/prepare-contour-snapshot.sh: убран шаг 0a (свежесть копии); в снимке вырезается цель install (ставит библиотеку из соседнего checkout через uv) — без этого снимок сервисов на библиотеке не проходит проверку «нет uv».
• Спеки docs: statement-normalization — библиотека и её поставка вместо копий; quality-checks — make check и make check-full сервисов без копии и statements-check; arm-core и recognition-contract — формулировки «копия» → «библиотека».
• Контекст: 03-architecture, 05-domain-rules (§7 «Ядро», §9.5, §11), 00-workspace-layout, dev/checks.md, dev/contour-transfer-guide.md.

Capabilities

New Capabilities

Нет.

Modified Capabilities

• statement-normalization: библиотека вместо пакета с копиями; поставка, версия, порядок правки перечня кодов.
• quality-checks: проверки сервисов без копии arm_statements и statements-check.
• arm-core: перечень кодов и версия — библиотеки, сверка словаря имён — тестом ядра.
• recognition-contract: service.statements_version — версия установленной библиотеки.

Impact

Связанные PR задачи AURORA-1677: arm-core #178, tabular-parser #70, scan-gateway #52, библиотека RSHB/pylib_ai_arm_statements (PR #1, тег v0.1.1). Дочерние change: arm-core use-installed-statements-library, tabular-parser use-arm-statements-library, scan-gateway use-statements-library. Выкладка — одной поставкой ядра и обоих сервисов. Миграций БД нет.

Non-goals

Изменение алгоритмов §7/§11, контракта (кроме описаний), DBML; перенос репозитория библиотеки в контур (скрипт снимка его не обрабатывает).