# Proposal

## Why

Нормализация форм должна подключаться к arm-core как устанавливаемая Python-библиотека, а не как синхронизируемая копия исходников. При переходе обнаружились две ошибки поставки: YAML-правила не попадали в пакет, а отсутствие внутреннего `VERSION` давало `None` и нарушало обязательность `service.statements_version` для форм.

Change ретроспективно фиксирует работу из этой задачи и оставшиеся проверки; он не объявляет весь переход завершённым.

## What Changes

- Добавлена цель `make install`: создание/использование `api/.venv`, установка или переустановка `pylib-ai-arm-statements` из `STATEMENTS_DIR` (по умолчанию `../pylib_ai_arm_statements`).
- `make venv` исключает `raisa_*` и `pylib_ai*` из `api/requirements.txt`. Обработка `requirements-dev.txt` сохранена: исключаются только вложенные `-r`. В текущем Makefile после requirements также устанавливается локальная библиотека.
- В текущем рабочем дереве закреплена зависимость `pylib_ai_arm_statements==0.1.1`, удалена копия `api/arm_statements/`, отключён `statements-check` в `check-full`. Это наблюдаемое состояние перехода, включая изменения пользователя.
- Импортируемое имя остаётся `arm_statements`. Пробная замена на `pylib_ai_arm_statements` и настройка mypy для этого имени отменены по просьбе пользователя.
- В соседней библиотеке исправлен `MANIFEST.in`: Python-файлы и YAML включаются из `arm_statements`, а не из прежнего каталога `pylib_ai_arm_statements`.
- В библиотеке `statements_version()` при отсутствии или пустом стандартном маркере `VERSION` использует метаданные дистрибутива. Явно переданный отсутствующий/пустой файл по-прежнему даёт `None`.
- Обновлены README, CLAUDE.md, комментарии, описание JSON-контракта и пометки в исторических планах/архивных OpenSpec-документах: теперь это отдельная библиотека; `statements_version` может быть версией дистрибутива.
- Сохранены расчёты, проверки §7, импортный API, схема результата и обязательность версии при наличии форм.

## Capabilities

### New Capabilities

- `statement-library`: поставка правил и кода как Python-библиотеки, локальная установка и определение версии.

### Modified Capabilities

- `documents-api`: использование установленной библиотеки при пересчёте и проверке словарей; сравнение версии задания с версией библиотеки вместо версии встроенной копии.
- `statement-checks`: источник правил §7 — установленная библиотека, без изменения арифметики и сценариев.

## Impact

- Срез 3b, сопровождение нормализации форм; контекст — `../docs/context/09-delivery-plan.md`, доменные алгоритмы — `../docs/context/05-domain-rules.md` §7 и §11. Алгоритмы не изменяются.
- Репозитории: arm-core (этот change); `../pylib_ai_arm_statements` (сделанные исправления поставки и версии описаны как внешняя зависимость, требуют отдельного коммита/поставки). Обновление общих инструкций и согласование с сервисами относятся к отдельному change в `../docs`, он здесь не создаётся.
- DBML: таблицы и поля не меняются, миграций нет. Существующие `recognition_job.statements_version` и `document_issue` используют уже имеющийся механизм версии и `STATEMENTS_VERSION_MISMATCH`.
- Полный интеграционный результат не подтверждён: `test_intake_statements_version_mismatch` был остановлен после зависания. Проверено: переустановка библиотеки, версия `0.1.1`, 11 тестов движка, Ruff и валидность JSON для изменённых описаний.

## Non-goals

- Переименование Python-импортов, изменения фронта, форматов денежных сумм, статусов, правил нормализации и схемы БД.
- Изменения портов БД в `.env.test`, `test_config.py` и посторонние файлы рабочего дерева: не входят в задачу.
- Публикация библиотеки в реестр, обновление других сервисов, запуск apply или архивирование этого change.