AURORA-1677: arm_statements теперь библиотека

context/03-architecture.md

@@ -1,5 +1,8 @@
 # 03. Архитектура (целевая, по решениям DECISION-1…5 и ARCH-* в DBML v5.22)
 
+> Актуализация 23.10.2026: arm-core подключает `arm_statements` как устанавливаемую библиотеку `pylib-ai-arm-statements`; локальная установка — `make venv`, переустановка — `make install`. Версия — непустой VERSION, иначе метаданные дистрибутива. Ниже описана также прежняя схема копирования для сервисов; завершение их перехода здесь не утверждается. Change: `document-statements-library-contract`, дочерний arm-core `use-installed-statements-library`.
+
+
 ## Компоненты (= репозитории, см. `00-workspace-layout.md`)
 
 ```

context/07-open-questions.md

@@ -1,5 +1,8 @@
 # 07. Открытые вопросы (реестр)
 
+> Примечание 23.10.2026: change `document-statements-library-contract` актуализирует только описания библиотеки в JSON-контракте. Согласование идентификаторов версий библиотеки между сервисами остаётся отдельной работой; новые решения и номера OQ этим обновлением не вводятся.
+
+
 Правило: агент **не закрывает** вопросы сам. Если решение нужно для текущего среза — делает явное допущение, помечает его
 в коде `# ASSUMPTION(OQ-nn)` и в OpenSpec-change, и переносит вопрос в статус «допущение принято». Пользователь закрывает
 вопросы с аналитиками/методологами и обновляет этот файл.

context/09-delivery-plan.md

@@ -1,5 +1,8 @@
 # 09. План работ вертикальными срезами
 
+> Сопровождение среза 3b, 23.10.2026: `document-statements-library-contract` согласует описания общей схемы с переходом arm-core на библиотеку (дочерний change `use-installed-statements-library`). Формат остаётся 2.0; статус поставки других сервисов этим обновлением не меняется.
+
+
 Принцип: каждый срез — рабочий end-to-end кусок (миграции + API + минимальный UI + тесты на реальных фикстурах),
 который можно показать аналитику. Порядок выбран так, чтобы самое рискованное (парсер ОСВ, матчинг ВГО) проверялось
 на реальных данных как можно раньше, а внешние зависимости (ИС Сканирование, РАИСА, NATS платформы) не блокировали.

contracts/recognition-result.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "arm-ka/recognition-result/v2",
   "title": "Результат распознавания файла (tabular-parser / scan-gateway), контракт v2.0",
-  "description": "Один файл (stored_file) → один job → N документов. Сервисы не знают БД: только структура файла. Формы ББ/ОФР нормализуются общим кодом arm_statements (05-domain-rules.md §11): статусы строк, needs_review, проверки §7, статус документа и структурные предупреждения приходят готовыми; ядро хранит их как пришли и пересчитывает тем же кодом только после правок аналитика. Нормализация счетов ОСВ, резолв контрагентов, сверка ИНН и периода — в arm-core.",
+  "description": "Один файл (stored_file) → один job → N документов. Сервисы не знают БД: только структура файла. Формы ББ/ОФР нормализуются библиотекой arm_statements (05-domain-rules.md §11): статусы строк, needs_review, проверки §7, статус документа и структурные предупреждения приходят готовыми; ядро хранит их как пришли и пересчитывает тем же кодом только после правок аналитика. Нормализация счетов ОСВ, резолв контрагентов, сверка ИНН и периода — в arm-core.",
   "$comment": "Версионирование: schema_version = MAJOR.MINOR. MINOR (2.1, 2.2, …) — необязательные поля и новые значения enum; MAJOR (3.0) — удаление/переименование полей, смена типов или семантики. Потребитель принимает известный MAJOR и любой MINOR. Новый MINOR раскатывается сначала на потребителей (ядро и сервисы обновляют копии схем раньше, чем производитель начнёт слать новый MINOR), потому что закрытые enum отвергают незнакомые значения. Новый MAJOR — порядок «сначала ядро»: ядро на время перехода принимает и прежний, и новый MAJOR (два маппера), сервисы переходят после выкладки ядра. Changelog: 1.0 — исходный контракт; 1.1 — osvDocument.rows[].extra; 1.2 — DISCLOSURE, statementDocument.checks, границы периода ОСВ; 2.0 (RSHB/arm-ka-docs#116, change unified-statement-normalization) — line_code nullable и line_status (ok | unreadable | missing | detail), row_index, ref, parent_ref, line_code_text, needs_review у значения и строки, values[].text, header.<поле>_text и <поле>_confidence у всех полей шапки, header.needs_review_fields, columns[].period_kind и label_confidence, document.status и document.warnings у всех документов (включая ОСВ), statementDocument.form_variant, metrics.warnings и warnings — структуры с уровнем и привязкой, checks обязателен у BALANCE/INCOME со строками, нарушения с codes, удалён checks.duplicate_line_codes, service.statements_version, header.okei (+ _text, _confidence), смысл is_recognized у OCR отвязан от confidence, statementDocument.form_variant обязателен, OTHER удалён из statementDocument.document_type. Схема 1.2 на окне перехода лежит рядом — recognition-result.v1.schema.json (примеры — examples/v1/); удаляется вместе с маппером 1.x ядра после перехода обоих сервисов.",
   "type": "object",
   "required": ["schema_version", "job_id", "file_id", "service", "status", "documents"],
@@ -16,7 +16,7 @@
       "properties": {
         "name": { "enum": ["tabular-parser", "scan-gateway"] },
         "version": { "type": "string" },
-        "statements_version": { "type": "string", "minLength": 1, "description": "коммит репозитория arm-statements, из которого разложена копия общего кода; обязателен, если в documents есть statementDocument" }
+        "statements_version": { "type": "string", "minLength": 1, "description": "маркер VERSION библиотеки arm_statements, если он есть, иначе версия установленного дистрибутива pylib-ai-arm-statements; обязателен, если в documents есть statementDocument" }
       }
     },
     "status": { "enum": ["done", "needs_check", "error"], "description": "done ⇔ все документы done и нет предупреждений файла уровня error; error — документов нет" },

openspec/changes/document-statements-library-contract/.openspec.yaml

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-10-23
+skip_specs: true

openspec/changes/document-statements-library-contract/design.md

@@ -0,0 +1,25 @@
+# Design
+
+## Context
+
+Связанный change arm-core — `use-installed-statements-library`; обновление аннотаций общей схемы одобрено пользователем 23.10.2026. Файл схемы в docs — источник истины для побайтовых копий сервисов.
+
+## Goals / Non-Goals
+
+**Goals:** согласовать descriptions и явно подтвердить отсутствие изменений валидируемой структуры.
+
+**Non-Goals:** изменение версии/ограничений контракта, правка docs/source, запуск миграций, обновление runtime других сервисов.
+
+## Decisions
+
+Обновить только корневой description и description поля service.statements_version по согласованному тексту arm-core. Проверить глубокое равенство JSON до/после без этих двух аннотаций и точное совпадение файлов docs/arm-core. Использовать существующий валидатор примеров и тест сверки копий. Отдельные дельты требований не нужны (`skip_specs: true`), поскольку нормативный формат не меняется.
+
+Контекст получает короткие заметки о переходе arm-core; они не объявляют переход остальных сервисов завершённым.
+
+## Decisions made without discussion
+
+23.10.2026: сохранить schema_version 2.0 при изменении только descriptions. Обоснование — множество валидных входов и структура результата неизменны. Цена ошибки — неверная маркировка релиза; проверяется сравнением JSON без двух изменённых аннотаций. Обновление общей схемы вместо отката локальной копии выбрано пользователем.
+
+## Risks / Trade-offs
+
+[Другие копии схем ещё содержат прежний текст] → перечислить производителей и потребителя в proposal; их копии могут быть синхронизированы отдельными изменениями. [Контекст по другим сервисам не проверялся] → заметки ограничены arm-core.

openspec/changes/document-statements-library-contract/proposal.md

@@ -0,0 +1,29 @@
+# Proposal
+
+## Why
+
+Описание общей нормализации и `service.statements_version` ещё говорит о копировании исходников. После перехода arm-core на устанавливаемую библиотеку локальные описания актуализированы, но перестали побайтово совпадать с источником в docs.
+
+## What Changes
+
+- В `contracts/recognition-result.schema.json` актуализируются только два `description`: нормализация библиотекой `arm_statements` и источник версии (непустой VERSION, иначе метаданные дистрибутива `pylib-ai-arm-statements`).
+- Текст синхронизируется с `../arm-core/api/contracts/recognition-result.schema.json`; структура, обязательность полей и ограничения JSON Schema сохраняются.
+- `schema_version` остаётся 2.0: меняются только аннотации документации, а не формат, проверка данных или семантика обработки результата. Правило повышения версии контракта применяется к изменениям поведения/формата, которых здесь нет.
+
+## Capabilities
+
+### New Capabilities
+
+Нет.
+
+### Modified Capabilities
+
+Нет изменений нормативных требований: documentation-only, `skip_specs: true`.
+
+## Impact
+
+Сопровождение среза 3b. Связанный дочерний change: `../arm-core/openspec/changes/use-installed-statements-library`. Читатель результата — arm-core, производители — tabular-parser и scan-gateway; runtime-код этих сервисов не меняется. Их обновление текстовых копий схем можно выполнять отдельно; этот change подтверждает совпадение docs и arm-core.
+
+## Non-goals
+
+Новые поля, типы, enum, изменение MAJOR/MINOR, изменение алгоритмов §7/§11, миграции БД, массовое редактирование исходников сервисов и закрытие вопросов общего выпуска библиотеки. Контекстные документы получают только точечную заметку о статусе arm-core, без объявления миграции других сервисов завершённой.

openspec/changes/document-statements-library-contract/tasks.md

@@ -0,0 +1,10 @@
+# Tasks
+
+## 1. Аннотации контракта
+
+- [x] 1.1 docs, contracts/recognition-result.schema.json: обновить два description по согласованной копии arm-core; проверить, что остальные JSON-значения не изменены, и выполнить scripts/validate_contracts.py.
+- [x] 1.2 arm-core, api/contracts и tests/test_contract.py: подтвердить побайтовое совпадение общей и локальной схемы существующим тестом идентичности.
+
+## 2. Контекст
+
+- [x] 2.1 docs, context/03-architecture.md, 07-open-questions.md, 09-delivery-plan.md: добавить точечные заметки о библиотеке arm-core и связанном change, не менять статус других сервисов и не вводить новые доменные решения; проверить diff и openspec validate.