# Design

## Context

См. `proposal.md`, Why и What Changes. Это ретроспективная фиксация перехода, затронувшего два репозитория. Текущий arm-core больше не содержит встроенного `api/arm_statements/`, но его Python-импорты остаются прежними. Дистрибутив называется `pylib-ai-arm-statements`; запись с подчёркиваниями в requirements обозначает тот же нормализованный идентификатор Python-пакета.

На момент оформления обнаружены остатки прежней схемы: `api/pytest.ini` содержит `arm_statements/tests`, Ruff считает `arm_statements` first-party, mypy содержит overrides старого пакета. В Makefile из `lint` исчез не только аргумент `arm_statements`, но и весь вызов mypy. Эти факты фиксируются для проверки при apply, без изменения кода сейчас.

Основные спецификации ещё содержат формулировки «копия пакета» и `sync-statements --check`; дельты этого change уточняют источник библиотеки. Документирование перехода не означает, что дельты уже синхронизированы или change архивирован.

## Goals / Non-Goals

**Goals:** воспроизводимая установка кода и ресурсов, сохранение имени импорта, определение версии установленного пакета, документирование сделанного и оставшихся проверок.

**Non-Goals:** менять алгоритмы §7/§11 общих правил, DTO, обязательность версии, БД и денежные единицы. Decimal и существующие единицы формы сохраняются. Документы в `../docs` и выпуск внешней библиотеки не изменяются этим локальным workflow.

## Decisions

### Разделить имя дистрибутива и Python-модуля

`pylib-ai-arm-statements` устанавливается как `arm_statements`. Это сохраняет адаптер `StatementsEngine`, доменную сборку `StoredForm` и тесты. Выполненная ранее замена импортов на `pylib_ai_arm_statements` отменена вместе с временным override `follow_untyped_imports`; она не является итогом задачи.

Альтернатива — переименовать все импорты — отвергнута пользователем и не нужна для подключения дистрибутива.

### Использовать окружение backend и явную переустановку

`STATEMENTS_DIR ?= ../pylib_ai_arm_statements`; `uv venv --python 3.11 --allow-existing` создаёт или использует окружение; `uv pip install --python ... --reinstall-package pylib-ai-arm-statements ...` переустанавливает библиотеку. Обычная установка выбрана вместо editable: установленное дерево должно содержать весь необходимый код и YAML. Переустановка нужна и при неизменившемся номере локальной версии.

`make venv` фильтрует только основные requirements по `^(raisa_|pylib_ai)`, dev-файл обрабатывается прежним фильтром `^-r`. Текущий Makefile также устанавливает локальную библиотеку после requirements. Это уточняет первоначальное описание двух отдельных команд: `make install` остаётся доступным для обновления без полного запуска `venv`.

### Включать YAML в дистрибутив

В `../pylib_ai_arm_statements/MANIFEST.in` исправлены два пути на `arm_statements` и `arm_statements/rules`. Имеющийся `include_package_data = True` позволяет включать ресурсы. Ручное копирование YAML в site-packages не использовалось: оно не исправляет последующие установки. `make install` успешно переустановил исправленный пакет; загрузка правил проверена тестами движка.

### Сохранить маркер и добавить fallback на метаданные

В библиотеке `arm_statements/version.py` стандартный непустой `VERSION` имеет приоритет. При отсутствующем/пустом стандартном файле вызываются метаданные `pylib-ai-arm-statements`. При `PackageNotFoundError` возвращается `None`. Явно переданный отсутствующий/пустой файл сохраняет старое поведение `None`.

Альтернатива — ослабить валидацию `RecognitionResultV2` — отвергнута: для форм версия остаётся обязательной. Искусственный VERSION в site-packages также не решает поставку пакета.

### Уточнить документацию и границы изменений

В arm-core обновлены README, CLAUDE.md, комментарии `api/src/models/files.py`, `api/src/contract/result_v2.py`, `api/src/api/dependencies/files.py`, описание `api/contracts/recognition-result.schema.json`, комментарии конфигурации и dev requirements. В историческом плане и архивных change добавлены пометки о прежней схеме. Конкретные заголовки/сценарии доменных требований сохранены в дельтах.

В рабочем дереве также наблюдаются удаление встроенной копии, pin `0.1.1`, отключение `statements-check` и изменения Makefile пользователем. Они относятся к контексту перехода; изменения `.env.test` и `test_config.py`, случайные HTML/PDF/XML и служебные файлы не входят в этот change.

## Risks / Trade-offs

- [Локальная переустановка меняет содержимое без нового номера версии] → удобна для разработки; опубликованные артефакты требуют уникальных версий. Равенство номера не доказывает равенство исходников.
- [Другие сервисы ещё передают хеш копии вместо версии дистрибутива] → существующий `STATEMENTS_VERSION_MISMATCH` остаётся информационным; согласование выпуска выносится в отдельный change общих docs.
- [Ошибки пакета исправлены в соседнем репозитории] → нужен отдельный коммит/поставка библиотеки; один коммит arm-core не включает эти файлы.
- [Потеря проверки типов при удалении встроенного пакета] → отдельно проверить конфигурацию и восстановить проверку исходников arm-core при apply; анализировать библиотеку её собственными средствами.
- [Устаревшая pytest testpath и first-party-настройки] → проверить и убрать привязки к удалённому дереву в рамках завершения перехода.
- [Полный прогон не подтверждён] → повторить интеграционный тест с доступной инфраструктурой. Предыдущий запуск завис и был остановлен; успех не заявляется.

## Migration Plan

Сделано: исправлена и переустановлена локальная библиотека; проверены версия `0.1.1` и 11 тестов `tests/test_statements_engine.py`. Ранее 24 профильных теста проходили на промежуточном варианте с другими импортами; этот результат не считается проверкой окончательного состояния.

Осталось: проверки собранного дистрибутива и граничных вариантов VERSION, согласование pytest/Ruff/mypy, повтор теста `test_intake_statements_version_mismatch`, общий прогон подходящих проверок, отдельные коммиты по репозиториям. Сценарий поставки проверяется на установленном пакете; регрессия нормализации — на существующих реальных фикстурах, без введения искусственных форм ради упаковки.

Для отката установки используется предыдущий исправный дистрибутив в окружении backend. Возвращать синхронизируемую копию исходников ради частичного отката не требуется; миграций БД нет. Для возврата к схеме до перехода нужен согласованный откат зависимости и удаления копии отдельным изменением.