docs(specs): archive local verification remediation

2026-08-23 21:21:22 +03:00
parent 51344d4988
commit 72444dbbb1
11 changed files with 441 additions and 4 deletions
@@ -10,6 +10,7 @@
 openspec validate <change> --type change --store wealth-ledger-specs
 openspec instructions apply --change <change> --json --store wealth-ledger-specs
 bash scripts/verify-openspec-authority.sh
 bash scripts/verify-runtime-openapi.sh
 ```
 ## Границы
@@ -0,0 +1,3 @@
 schema: spec-driven
 created: 2026-08-23
 goal: Закрыть WL-P1-05 и WL-P2-06, WL-P2-09, WL-P2-11; явно отложить WL-P2-05 и WL-P2-13 до стабильного Prisma migration gate.
@@ -0,0 +1,5 @@
 # make-local-verification-agent-safe
 Сделать конкретные локальные backend и runtime OpenAPI проверки
 детерминированными и безопасными для агента; не маскировать заблокированный
 Prisma e2e migration gate общим verdict.
@@ -0,0 +1,103 @@
 ## Context
 Корень workspace — coordination directory, а не package-manager workspace и не
 Git-репозиторий. `frontend`, `backend`, `specs` и `docs` — независимые Git
 roots. `specs/scripts/verify-openspec-authority.sh` уже показывает правильное
 место для versioned cross-repository tooling: script определяет workspace
 относительно себя, а не доверяет текущей директории.
 Frontend закрепляет Node 22 и имеет offline `npm run verify`. Для backend нет
 эквивалентных runtime policy и отдельных quality gates: `lint` запускает ESLint
 с `--fix`, base tsconfig включает тесты, а build tsconfig исключает их.
 Существующие e2e tests создают in-memory Nest application, но их script сначала
 запускает Prisma на фиксированной `/tmp` DB и сейчас падает до Jest. Swagger
 доступен по `/api/docs-json` при `NODE_ENV=development`;
 `frontend/scripts/openapi:sync.mjs` — единственный намеренный writer committed
 snapshot и generated types.
 ## Goals / Non-Goals
 **Цели:**
 - Восстановить исполнимые backend gates для lint и TypeScript приложения и
  тестов с понятной диагностикой failures.
 - Доказать отдельной read-only командой, что полный runtime OpenAPI document
  совпадает с committed frontend snapshot.
 - Сделать Node/npm bootstrap и конкретные verification commands discoverable
  для агентов.
 - Сохранить pre-existing working-tree state пользователя; не создавать
  versioned writes во время проверок.
 **Не входит в scope:**
 - CI/CD, remote verification, Docker, новый task runner, package-manager
  workspace или общий workspace verifier.
 - Изоляция backend e2e DB, обновление Prisma packages и восстановление
  migration gate: WL-P2-05 и зависимый WL-P2-13 отложены из-за нестабильности
  Prisma 7.9.1 на Node 22.
 - JSON report format, cached results, plug-in architecture, arbitrary diff
  bases, сохранённые hashes либо fixture/unit-test harness для process scripts.
 - Изменение OpenAPI sync writer, generated frontend types, пользовательских API
  statuses, T-Bank integration, application features, перенос business glossary
  `CONTEXT.md` или удаление существующего OpenSpec authority fixture test.
 ## Decisions
 ### Backend check и fix — разные операции
 Backend предоставляет `lint:check` без `--fix`, `lint:fix` с явным write intent
 и сохраняет `lint` как совместимый alias для `lint:check`. Он предоставляет
 отдельные команды `typecheck:app` и `typecheck:test` на основе выделенных
 tsconfig files. Эти команды не создают repository artifacts; build и e2e не
 объявляются частью нового общего verdict.
 ### Runtime OpenAPI сверяется отдельной read-only командой
 `specs/scripts/verify-runtime-openapi.sh` определяет workspace из собственного
 пути, поднимает backend с детерминированным development environment, ждёт local
 readiness, получает `/api/docs-json` и всегда завершает child process. Команда
 рекурсивно упорядочивает JSON object keys, сохраняя array order, записывает
 canonical runtime и snapshot documents во временную директорию, сравнивает их
 SHA-256 и выводит unified diff при различии.
 Она никогда не вызывает `openapi:sync`, не записывает frontend snapshot и не
 обновляет generated types. Это узкий контрактный gate, а не orchestration
 interface для всех репозиториев.
 ### Bootstrap и документация задают один contract
 Оба приложения требуют Node 22 и `npm ci`. Scoped `AGENTS.md` перечисляют
 только реально существующие non-mutating verification commands и явно отделяют
 писатели `lint:fix` и `openapi:sync`. Durable development documentation
 показывает prerequisites и границы отдельной runtime-contract команды.
 ### Prisma findings явно отложены, а не маскируются обходом
 `prisma migrate deploy` 7.9.1 воспроизводимо возвращает пустой schema-engine
 error как на фиксированной, так и на уникальной временной SQLite DB; включение
 engine diagnostics меняет результат. На 2026-08-23 опубликованная latest
 stable version также 7.9.1. Не вводится второй migration mechanism и не
 обновляются зависимости без подтверждённого stable candidate. Реестр фиксирует
 дату, причину и trigger review: следующая stable Prisma должна трижды применить
 existing migrations к чистой DB на Node 22.
 ## Risks / Trade-offs
 - [Runtime backend не стартует или child process остаётся после ошибки] →
  command создаёт cleanup trap до запуска backend и сохраняет фактический exit
  status.
 - [Canonicalization скрывает различие контрактов] → нормализуется только
  порядок object keys; arrays и каждое JSON field остаются частью SHA-256 input.
 - [Prisma schema engine остаётся недоступным на supported runtime] → WL-P2-05
  и WL-P2-13 остаются `deferred` до опубликованной stable версии, прошедшей
  оговорённый reproduction gate.
 - [Ignored artifacts путаются с versioned writes] → отдельные команды не
  считают `build` или e2e своим успехом и документируют свои временные ресурсы.
 ## Migration Plan
 Не нужны migration production data или deployment sequence. Разработчики
 запускают `npm ci` под Node 22 в каждом application repository, используют
 `npm run lint:fix` только осознанно и запускают runtime OpenAPI check отдельно
 из workspace. Rollback — обычный revert independently versioned changes; он не
 меняет committed API artifacts или persistent user data.
@@ -0,0 +1,42 @@
 ## Why
 В workspace четыре независимых Git-репозитория, но нет единого
 воспроизводимого verdict локальной проверки. Backend `lint` изменяет исходные
 файлы, backend e2e останавливается на настройке Prisma до Jest, для тестового
 TypeScript нет исполнимого gate, а committed frontend OpenAPI snapshot не
 сверяется с runtime-документом. Из-за этого агент может получить зелёный либо
 неполный результат, не узнав об изменении исходников или дрейфе
 межрепозиторного контракта.
 ## What Changes
 - Разделить backend lint-проверку и явный auto-fix, добавить отдельные
  TypeScript gates для приложения и тестов.
 - Добавить сверку runtime OpenAPI с committed snapshot: она поднимает
  детерминированный локальный backend, canonicalize оба полных документа во
  временном хранилище, сравнивает SHA-256 и показывает diff при дрейфе, не
  вызывая `openapi:sync`.
 - Унифицировать local bootstrap frontend и backend на Node 22 и `npm ci`,
  документировать конкретные gates и обновить scoped agent instructions.
 - Обновить audit remediation registry: этот change станет единственным active
  remediation для WL-P1-05, WL-P2-06, WL-P2-09 и WL-P2-11; WL-P2-05 и
  WL-P2-13 будут явно отложены до стабильного Prisma migration gate.
 ## Capabilities
 ### Modified Capabilities
 - `project-foundation`: Выравнивает требования к runtime/bootstrap приложений и
  локальные agent verification instructions frontend и backend.
 - `api-contract-generation`: Требует явной локальной runtime сверки между
  backend OpenAPI и committed frontend snapshot.
 ## Impact
 Затронуты `backend`, `frontend`, `specs` и `docs`. Изменятся backend package
 scripts, TypeScript-конфигурации, local runtime metadata и документация;
 generated frontend snapshot и offline-поведение `npm run verify` не изменятся.
 Небольшая read-only runtime-contract команда в `specs/scripts` не имеет
 manifest, сохранённых hashes, кэша, plug-in system или fixture test harness.
 Не вводятся изменения пользовательского HTTP-контракта, persisted production
 data, внешний сетевой доступ или T-Bank credentials.
@@ -0,0 +1,38 @@
 ## MODIFIED Requirements
 ### Requirement: Frontend не зависит от OpenAPI во время работы
 Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot и отдельной read-only runtime-contract command.
 #### Scenario: OpenAPI endpoint недоступен после сборки frontend
 - **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
 - **THEN** frontend продолжает использовать сгенерированный код для запросов к API
 #### Scenario: Локальная проверка выполняется без backend
 - **WHEN** разработчик запускает локальный frontend quality gate
 - **THEN** проверка актуальности generated artifact использует сохранённый snapshot и не обращается к OpenAPI endpoint
 #### Scenario: Разработчик проверяет runtime-контракт
 - **WHEN** разработчик запускает отдельную runtime-contract command
 - **THEN** command может поднять изолированный local backend только для сравнения
  его полного runtime OpenAPI document с committed frontend snapshot и не
  обновляет ни один из артефактов
 ### Requirement: Отдельная команда обнаруживает runtime drift OpenAPI
 Runtime-contract command MUST получать полный OpenAPI document от изолированного
 local backend по `/api/docs-json`, рекурсивно canonicalize порядок JSON object
 keys, сохраняя каждое field и array order, и сравнивать его SHA-256 с canonical
 committed frontend snapshot. При любом content mismatch она MUST завершаться
 ошибкой и показывать diff. Verification MUST NOT вызывать snapshot
 synchronization command или записывать committed OpenAPI либо generated type
 artifacts.
 #### Scenario: Runtime success status отличается от committed snapshot
 - **WHEN** backend runtime OpenAPI описывает response status, отличный от
  committed frontend snapshot
 - **THEN** runtime-contract command завершается ошибкой с diff и оставляет
  snapshot и generated types без изменений
 #### Scenario: Runtime OpenAPI совпадает с committed snapshot
 - **WHEN** каждое field canonical runtime document совпадает с canonical
  committed frontend snapshot
 - **THEN** runtime-contract stage завершается успешно без изменения frontend files
@@ -0,0 +1,27 @@
 ## MODIFIED Requirements
 ### Requirement: Репозитории содержат локальные инструкции для AI-агентов
 Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами. Каждая инструкция MUST объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых OpenSpec операций и запрещать versioned framework-specific planning artifacts вне canonical store. Локальные инструкции MUST направлять агента к durable remediation registry, когда задача связана с findings технического аудита. Backend instructions MUST различать non-mutating verification commands и явные auto-fix commands.
 #### Scenario: Агент начинает работу в отдельном репозитории
 - **WHEN** агент открывает любой из репозиториев frontend, backend, specs или docs
 - **THEN** он может определить локальные правила работы, canonical OpenSpec authority и источник связанных спецификаций из `AGENTS.md` этого репозитория
 #### Scenario: Агент получает audit-derived задачу из отдельного репозитория
 - **WHEN** задача ссылается на finding технического аудита
 - **THEN** локальный `AGENTS.md` указывает на remediation registry и canonical OpenSpec workflow с явным store selection до начала изменения кода
 #### Scenario: Агент выбирает backend quality gate
 - **WHEN** агент читает backend instructions перед локальной проверкой
 - **THEN** он запускает документированные non-mutating lint/typecheck commands и не получает auto-fix как неявный quality gate
 ### Requirement: Локальный план MVP не является источником спецификации
 Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs. Frontend и backend MUST требовать Node 22 и документировать lockfile-safe bootstrap через `npm ci`.
 #### Scenario: Решение уточняется во время SDD-изменения
 - **WHEN** изменение уточняет наблюдаемое поведение системы
 - **THEN** оно фиксируется в OpenSpec и соответствующей документации, а `MVP.md` остается компактной картой поставки
 #### Scenario: Агент bootstrap-ит application repository
 - **WHEN** агент начинает локальную проверку frontend или backend на чистой машине
 - **THEN** он может определить Node 22 и выполнить `npm ci` без угадывания runtime policy
@@ -0,0 +1,58 @@
 ## 1. Зафиксировать активный и отложенный audit scope
 - [x] 1.1 Обновить `docs/development/audit-remediation.md`: пометить только
  WL-P1-05, WL-P2-06, WL-P2-09 и WL-P2-11 как `active` с
  `make-local-verification-agent-safe`; записать WL-P2-05 и WL-P2-13 как
  `deferred` с датой, наблюдаемой причиной Prisma 7.9.1 и trigger review;
  не помечать finding как `done`.
 - [x] 1.2 Обновить durable development documentation и scoped `AGENTS.md`,
  чтобы они называли только реально существующие non-mutating gates, Node 22 и
  `npm ci`, а writers `lint:fix` и `openapi:sync` были явными.
 ## 2. Восстановить non-mutating local gates backend
 - [x] 2.1 Добавить backend Node 22 runtime metadata и lockfile-safe bootstrap
  guidance; разделить `lint:check`, `lint:fix` и совместимый non-mutating alias
  `lint` в `backend/package.json`.
 - [x] 2.2 Добавить отдельные backend TypeScript configurations и scripts для
  приложения и тестов; application compilation исключает test sources, test
  compilation включает test surface, оба выполняются без repository artifacts.
 - [x] 2.3 Исправить существующий неполный `TbankClient` test double или
  заменить его typed test adapter, чтобы test TypeScript gate проходил без
  ослабления production client contract.
 - [x] 2.4 Документировать, что текущие `test:e2e` и общий workspace verdict не
  являются частью этого change, пока WL-P2-05/P2-13 отложены; не добавлять
  обходной Prisma runner или ложный `npm run verify`.
 ## 3. Проверить runtime API contract без writers
 - [x] 3.1 Реализовать минимальный runtime OpenAPI comparison helper, который
  запускает backend с deterministic development test environment, ждёт local
  readiness, получает `/api/docs-json`, canonicalizes object keys во временных
  files, сравнивает SHA-256 полного document, выводит diff при mismatch и всегда
  завершает child process.
 - [x] 3.2 Подтвердить, что helper никогда не вызывает
  `frontend/scripts/openapi-sync.mjs`, не обращается к external service, не
  требует T-Bank credentials и не записывает committed snapshot/generated
  types; запустить его для текущего contract и устранить каждый content mismatch
  через согласованный contract workflow, а не скрытым переписыванием.
 ## 4. Completion evidence и audit tracking
 - [x] 4.1 Запустить `openspec validate make-local-verification-agent-safe
  --type change --strict --store wealth-ledger-specs`, `openspec validate
  --specs --strict --store wealth-ledger-specs`, authority verifier, отдельный
  runtime OpenAPI check и relevant per-repository checks; зафиксировать точные
  commands и observed results.
 - [x] 4.2 Выполнить independent read-only review diff, OpenSpec deltas,
  temporary-resource behavior, runtime-contract comparison и точности
  документации; устранить каждую confirmed issue и подтвердить, что этот task
  list не содержит post-archive bookkeeping, commit или registry-completion
  checkbox.
 - [x] 4.3 Выполнить applicable pre-archive `opsx-verify` procedure и устранить
  каждый blocking result. Эта задача завершается до archive. Только после
  завершения каждого checkbox change может быть archived и synced; только после
  этого remediation registry вне task list получает actual archive path,
  commits, terminal evidence, четыре статуса `done` и ровно одну следующую
  рекомендуемую задачу. WL-P2-05 и WL-P2-13 остаются `deferred` до своего
  отдельного change.
@@ -29,16 +29,42 @@ Frontend SHALL хранить в репозитории версионируем
 - **THEN** команда завершается с ошибкой и существующие snapshot и сгенерированные transport types не изменяются
 ### Requirement: Frontend не зависит от OpenAPI во время работы
-Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot.
+Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot и отдельной read-only runtime-contract command.
 #### Scenario: OpenAPI endpoint недоступен после сборки frontend
 - **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
 - **THEN** frontend продолжает использовать сгенерированный код для запросов к API
 #### Scenario: Локальная проверка выполняется без backend
- **WHEN** разработчик запускает локальный quality gate без доступного backend
+- **WHEN** разработчик запускает локальный frontend quality gate
 - **THEN** проверка актуальности generated artifact использует сохранённый snapshot и не обращается к OpenAPI endpoint
 #### Scenario: Разработчик проверяет runtime-контракт
 - **WHEN** разработчик запускает отдельную runtime-contract command
 - **THEN** command может поднять изолированный local backend только для сравнения
  его полного runtime OpenAPI document с committed frontend snapshot и не
  обновляет ни один из артефактов
 ### Requirement: Отдельная команда обнаруживает runtime drift OpenAPI
 Runtime-contract command MUST получать полный OpenAPI document от изолированного
 local backend по `/api/docs-json`, рекурсивно canonicalize порядок JSON object
 keys, сохраняя каждое field и array order, и сравнивать его SHA-256 с canonical
 committed frontend snapshot. При любом content mismatch она MUST завершаться
 ошибкой и показывать diff. Verification MUST NOT вызывать snapshot
 synchronization command или записывать committed OpenAPI либо generated type
 artifacts.
 #### Scenario: Runtime success status отличается от committed snapshot
 - **WHEN** backend runtime OpenAPI описывает response status, отличный от
  committed frontend snapshot
 - **THEN** runtime-contract command завершается ошибкой с diff и оставляет
  snapshot и generated types без изменений
 #### Scenario: Runtime OpenAPI совпадает с committed snapshot
 - **WHEN** каждое field canonical runtime document совпадает с canonical
  committed frontend snapshot
 - **THEN** runtime-contract stage завершается успешно без изменения frontend files
 ### Requirement: Frontend обнаруживает дрейф сгенерированного контракта
 Frontend SHALL проверять, что committed generated transport types соответствуют versioned OpenAPI snapshot, и MUST завершать quality gate с ошибкой при расхождении.
@@ -7,7 +7,7 @@
 ## Requirements
 ### Requirement: Репозитории содержат локальные инструкции для AI-агентов
-Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами. Каждая инструкция MUST объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых OpenSpec операций и запрещать versioned framework-specific planning artifacts вне canonical store. Локальные инструкции MUST направлять агента к durable remediation registry, когда задача связана с findings технического аудита.
+Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами. Каждая инструкция MUST объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых OpenSpec операций и запрещать versioned framework-specific planning artifacts вне canonical store. Локальные инструкции MUST направлять агента к durable remediation registry, когда задача связана с findings технического аудита. Backend instructions MUST различать non-mutating verification commands и явные auto-fix commands.
 #### Scenario: Агент начинает работу в отдельном репозитории
 - **WHEN** агент открывает любой из репозиториев frontend, backend, specs или docs
@@ -17,13 +17,21 @@
 - **WHEN** задача ссылается на finding технического аудита
 - **THEN** локальный `AGENTS.md` указывает на remediation registry и canonical OpenSpec workflow с явным store selection до начала изменения кода
 #### Scenario: Агент выбирает backend quality gate
 - **WHEN** агент читает backend instructions перед локальной проверкой
 - **THEN** он запускает документированные non-mutating lint/typecheck commands и не получает auto-fix как неявный quality gate
 ### Requirement: Локальный план MVP не является источником спецификации
-Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs.
+Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs. Frontend и backend MUST требовать Node 22 и документировать lockfile-safe bootstrap через `npm ci`.
 #### Scenario: Решение уточняется во время SDD-изменения
 - **WHEN** изменение уточняет наблюдаемое поведение системы
 - **THEN** оно фиксируется в OpenSpec и соответствующей документации, а `MVP.md` остается компактной картой поставки
 #### Scenario: Агент bootstrap-ит application repository
 - **WHEN** агент начинает локальную проверку frontend или backend на чистой машине
 - **THEN** он может определить Node 22 и выполнить `npm ci` без угадывания runtime policy
 ### Requirement: Frontend предоставляет минимальный каркас приложения
 Frontend SHALL предоставлять русскоязычный адаптивный каркас приложения с маршрутами `/login`, `/register`, `/accounts`, `/accounts/:accountId` и `/settings`, светлой финансовой темой и навигацией для счетов и настроек. Каркас MUST содержать состояния загрузки, ошибки и пустых данных без реализации доменных сценариев.
@@ -0,0 +1,126 @@
 #!/usr/bin/env bash
 set -euo pipefail
 script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 workspace_dir="$(cd -- "$script_dir/../.." && pwd)"
 backend_dir="$workspace_dir/backend"
 snapshot_path="$workspace_dir/frontend/src/shared/api/spec/openapi.json"
 if [[ ! -f "$snapshot_path" ]]; then
  echo "Missing committed OpenAPI snapshot: $snapshot_path" >&2
  exit 1
 fi
 node_major="$(node -p "process.versions.node.split('.')[0]")"
 if [[ "$node_major" != "22" ]]; then
  echo "Node 22 is required; found $(node --version)." >&2
  exit 1
 fi
 temporary_dir="$(mktemp -d "${TMPDIR:-/tmp}/wealth-ledger-runtime-openapi.XXXXXX")"
 backend_pid=""
 cleanup() {
  if [[ -n "$backend_pid" ]] && kill -0 "$backend_pid" 2>/dev/null; then
    kill "$backend_pid" 2>/dev/null || true
    wait "$backend_pid" 2>/dev/null || true
  fi
  rm -rf "$temporary_dir"
 }
 trap cleanup EXIT INT TERM
 port="$(node -e "const server = require('node:net').createServer(); server.listen(0, '127.0.0.1', () => { console.log(server.address().port); server.close(); });")"
 runtime_path="$temporary_dir/runtime.json"
 canonical_runtime_path="$temporary_dir/runtime.canonical.json"
 canonical_snapshot_path="$temporary_dir/snapshot.canonical.json"
 backend_log="$temporary_dir/backend.log"
 compile_log="$temporary_dir/compile.log"
 if ! (
  cd "$backend_dir"
  ./node_modules/.bin/tsc --project tsconfig.build.json --outDir "$temporary_dir/dist"
 ) >"$compile_log" 2>&1; then
  echo "Temporary backend compilation failed:" >&2
  sed -n '1,160p' "$compile_log" >&2
  exit 1
 fi
 ln -s "$backend_dir/node_modules" "$temporary_dir/dist/node_modules"
 (
  cd "$backend_dir"
  NODE_ENV=development \
  PORT="$port" \
  DATABASE_URL="file:$temporary_dir/runtime.db" \
  FRONTEND_ORIGIN="http://localhost:5173" \
  JWT_SECRET="runtime-openapi-check-secret-at-least-32" \
  TOKEN_ENCRYPTION_KEY="MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=" \
  TBANK_GRPC_ENDPOINT="127.0.0.1:1" \
  TBANK_RATE_LIMIT_PER_SECOND=5 \
  LOG_LEVEL=error \
  node "$temporary_dir/dist/src/main.js"
 ) >"$backend_log" 2>&1 &
 backend_pid="$!"
 for _ in $(seq 1 60); do
  if node -e "fetch(process.argv[1]).then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))" "http://127.0.0.1:$port/api/docs-json"; then
    break
  fi
  if ! kill -0 "$backend_pid" 2>/dev/null; then
    echo "Backend stopped before exposing /api/docs-json:" >&2
    sed -n '1,160p' "$backend_log" >&2
    exit 1
  fi
  sleep 0.25
 done
 if ! node -e 'fetch(process.argv[1]).then(async (response) => { if (!response.ok) throw new Error(`${response.status} ${response.statusText}`); require("node:fs").writeFileSync(process.argv[2], await response.text()); }).catch((error) => { console.error(`OpenAPI fetch failed: ${error.message}`); process.exit(1); })' "http://127.0.0.1:$port/api/docs-json" "$runtime_path"; then
  echo "Backend did not expose /api/docs-json within 15 seconds:" >&2
  sed -n '1,160p' "$backend_log" >&2
  exit 1
 fi
 if node - "$runtime_path" "$snapshot_path" "$canonical_runtime_path" "$canonical_snapshot_path" <<'NODE'
 const { createHash } = require('node:crypto');
 const { readFileSync, writeFileSync } = require('node:fs');
 function canonicalize(value) {
  if (Array.isArray(value)) return value.map(canonicalize);
  if (value && typeof value === 'object') {
    return Object.fromEntries(
      Object.keys(value)
        .sort()
        .map((key) => [key, canonicalize(value[key])]),
    );
  }
  return value;
 }
 const [runtimePath, snapshotPath, canonicalRuntimePath, canonicalSnapshotPath] =
  process.argv.slice(2);
 const documents = [runtimePath, snapshotPath].map((path) =>
  canonicalize(JSON.parse(readFileSync(path, 'utf8'))),
 );
 const serialized = documents.map((document) => `${JSON.stringify(document, null, 2)}\n`);
 writeFileSync(canonicalRuntimePath, serialized[0]);
 writeFileSync(canonicalSnapshotPath, serialized[1]);
 const hashes = serialized.map((value) =>
  createHash('sha256').update(value).digest('hex'),
 );
 console.log(`runtime SHA-256:  ${hashes[0]}`);
 console.log(`snapshot SHA-256: ${hashes[1]}`);
 process.exitCode = hashes[0] === hashes[1] ? 0 : 1;
 NODE
 then
  comparison_status=0
 else
  comparison_status=$?
 fi
 if [[ "$comparison_status" -ne 0 ]]; then
  echo "Runtime OpenAPI differs from the committed frontend snapshot:" >&2
  diff -u "$canonical_snapshot_path" "$canonical_runtime_path" || true
  exit 1
 fi
 echo "Runtime OpenAPI matches the committed frontend snapshot."