# 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`] → архив — история, не правится.