12ae96ba6e
- спеки statement-normalization, quality-checks, arm-core, recognition-contract — дельты под библиотеку - удалены sync-statements, statements-check, test-sync-statements; новая statements-orders-check в make check - снимок для контура: без шага 0a, цель install вырезается (иначе проверка «нет uv» падает) - 03-architecture, 05-domain-rules, 00-workspace-layout, dev/checks.md, contour-transfer-guide; баннеры убраны Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
56 lines
6.1 KiB
Markdown
56 lines
6.1 KiB
Markdown
# 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`) не правится в этом
|
||
change: файл байтово копируется в библиотеку, правка дала бы расхождение с `v0.1.1`. Обоснование — комментарий не
|
||
влияет на данные. Цена ошибки — устаревший комментарий до следующего выпуска библиотеки.
|
||
- 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`] → архив — история, не правится.
|