docs: make project documentation self-contained

development/runtime-openapi-verification.md

@@ -2,55 +2,40 @@
 
 ## Назначение
 
-`npm run test:openapi-contract` в `backend/` строит configured Nest application,
-создаёт runtime OpenAPI document и сверяет его с committed snapshot
-`frontend/src/shared/api/spec/openapi.json` после детерминированной canonicalization.
+Проверка сравнивает OpenAPI, сформированный настроенным backend-приложением,
+с описанием API, на котором основан frontend. Backend остаётся единственным
+источником исполняемого HTTP-контракта; frontend-клиент является производным.
+Причины выбора описаны в [ADR 002](../adr/002-nest-generated-openapi-contract.md).
 
-Это отдельный контрактный gate, а не общий verifier всех репозиториев. Он обязателен перед завершением задачи, меняющей
-backend API или frontend transport contract и не заменяет
-локальные lint/typecheck команды приложений.
+Эта проверка подтверждает согласованность публичного контракта, но не заменяет
+проверки каждого приложения и наблюдаемого HTTP-поведения.
 
 ## Выбор и направление изменения
 
-1. Определите, меняется wire contract (route, request/response field, status, error shape) или только внутренний код/UI model. Во втором случае snapshot не меняется.
-2. Прочитайте [HTTP semantics](../architecture/http-api.md) и нужный feature/domain source. Backend Nest controllers/DTO/Swagger metadata — единственный editable источник OpenAPI; specs repo не является вторым OpenAPI source.
-3. Измените этот source и проверьте representative HTTP behavior. При изменении контракта скопируйте generated runtime OpenAPI в committed frontend snapshot, затем в frontend выполните `npm run openapi:generate`.
-4. Выполните frontend `npm run openapi:check` и backend `npm run test:openapi-contract`, а также verify affected repos. Эти команды проверяют разное: schema parity не доказывает validation/auth/error behavior.
+Изменением контракта считается изменение маршрута, входного или выходного поля,
+статуса либо формы ошибки. Внутреннее изменение представления без изменения
+API не требует нового описания контракта.
 
-Generated frontend TS и backend Prisma client вручную не редактируются.
-Frontend domain/UI type допустим, когда он отличается от transport DTO по смыслу.
-Перед compatibility-sensitive изменением оцените существующих consumers и
-rollback/data constraints; одного обновления snapshot недостаточно.
-
-## Запуск
-
-Из корня workspace:
-
-```bash
-cd backend
-nvm use --silent
-npm run test:openapi-contract
-```
-
-Перед первым запуском в backend выполняют `npm ci` под Node 22.
+Направление согласования: публичный API backend → OpenAPI → производное
+описание и типизированный клиент frontend. Две независимо редактируемые версии
+контракта создавали бы риск расхождения. Перед изменением, влияющим на
+совместимость, учитываются существующие потребители и сохранность данных.
+Семантика запросов и ошибок описана в [HTTP API](../architecture/http-api.md).
 
 ## Границы и результат
 
-Команда:
+Сравнение выполняется на границе настроенного приложения, нормализует порядок
+ключей JSON-объектов и сохраняет порядок массивов. Оно не обновляет сравниваемые
+описания и клиент автоматически и не обращается к T-Bank или другим внешним
+источникам. Несовпадение указывает на рассогласование контракта.
 
-- использует configured Nest application на integration boundary;
-- рекурсивно сортирует только ключи JSON objects и сохраняет порядок arrays;
-- не записывает snapshot или generated frontend types.
-
-Она не записывает committed snapshot или generated frontend types и не
-обращается к T-Bank либо другому внешнему сервису. Если контракт действительно
-изменён, snapshot обновляют явным копированием backend OpenAPI document в
-`frontend/src/shared/api/spec/openapi.json`, затем в `frontend` запускают
-`npm run openapi:generate` и снова выполняют эту проверку.
+Равенство схем не доказывает фактическую работу валидации, авторизации,
+статусов, cookie и обработки ошибок: для этого нужны наблюдения полного
+HTTP-потока. Согласованность описаний и функциональная корректность —
+разные доказательства.
 
 ## Ограничение e2e
 
-Проверка Swagger не запускает backend e2e tests. WL-P2-05 (runnable e2e) и
-WL-P2-13 (единый workspace verdict) отложены из-за нестабильного Prisma 7.9.1
-migration gate; дата, rationale и trigger пересмотра находятся в
-[audit remediation registry](audit-remediation.md).
+Сравнение OpenAPI не запускает сквозные проверки с миграциями базы.
+Известная ошибка движка миграций и условие пересмотра описаны в
+[проверке backend](backend-workflow.md#локальная-проверка).