From ab35d671771176d70bc79bdec739f4cd28e7879b Mon Sep 17 00:00:00 2001 From: bsodfather Date: Sat, 3 Oct 2026 15:04:15 +0300 Subject: [PATCH] story 2-12-preview-partial-mode: implemented and reviewed via bmad-loop --- .../implementation-artifacts/deferred-work.md | 106 ++ .../spec-2-12-preview-partial-mode.md | 230 ++++ ...tdd-checklist-2-12-preview-partial-mode.md | 256 ++++ apps/admin-api/src/app.rs | 6 +- apps/admin-api/src/dto.rs | 13 + apps/admin-api/src/routes/imports.rs | 14 + apps/admin-api/src/service/imports.rs | 179 ++- .../src/service/imports/import_plan.rs | 190 +-- .../service/imports/import_plan/validation.rs | 128 ++ .../src/service/imports/plan_apply.rs | 161 +++ .../src/service/imports/verified_preview.rs | 1 + .../tests/integration/openapi_import.rs | 3 + .../openapi_import/http_contract.rs | 15 +- .../openapi_import/import_plan_apply.rs | 1 + .../import_plan_apply/support_matrix.rs | 106 ++ .../import_plan_create/creation.rs | 168 ++- .../openapi_import/import_plan_create/mod.rs | 1 + .../import_plan_create/route_get.rs | 87 ++ .../import_plan_create/security_binding.rs | 44 +- .../import_plan_create/validation.rs | 75 ++ .../openapi_import/large_preview.rs | 142 ++ .../openapi_import/upload_outcomes.rs | 140 ++ .../integration/openapi_import/v5_replay.rs | 93 ++ apps/ui/css/openapi-import.css | 110 ++ apps/ui/index.html | 18 + apps/ui/js/api.js | 7 + apps/ui/js/i18n.js | 46 +- apps/ui/js/openapi-import.js | 760 ++++++++--- apps/ui/tests/e2e/openapi-import-plan.spec.js | 1 + .../tests/e2e/openapi-preview-partial.spec.js | 1184 +++++++++++++++++ .../e2e/openapi-preview-reference.spec.js | 273 ++++ apps/ui/tests/e2e/operations.spec.js | 11 +- crates/crank-import/src/rest/http_methods.rs | 1 + .../crank-import/src/rest/legacy_payload.rs | 2 + crates/crank-import/src/rest/mod.rs | 8 +- crates/crank-import/src/rest/model.rs | 28 +- .../src/rest/normalize_projection.rs | 4 + crates/crank-import/src/rest/openapi3.rs | 2 + crates/crank-import/src/rest/payload.rs | 2 + .../crank-import/src/rest/recommendations.rs | 18 +- crates/crank-import/src/rest/swagger2.rs | 2 + crates/crank-import/tests/corpus.rs | 26 +- crates/crank-import/tests/preview.rs | 40 + crates/crank-metrics/src/schema.rs | 9 +- crates/crank-metrics/tests/schema_v1.rs | 16 +- .../crank-registry/src/postgres/import_job.rs | 61 +- .../src/postgres/import_job/catalog.rs | 68 + .../src/postgres/import_job/plan_apply.rs | 47 +- .../import_job/plan_apply/material.rs | 80 +- .../import_job/plan_apply/mutations.rs | 8 +- .../import_job/plan_apply/revalidate.rs | 114 ++ .../src/postgres/import_job/semantic.rs | 230 ++++ .../tests/integration/import_plan.rs | 1 + .../integration/import_plan/preview_v2.rs | 787 +++++++++++ docs/openapi-import.md | 48 +- docs/schemas/metrics-registry-v1.json | 6 +- 56 files changed, 5801 insertions(+), 376 deletions(-) create mode 100644 _bmad-output/implementation-artifacts/deferred-work.md create mode 100644 _bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md create mode 100644 _bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md create mode 100644 apps/admin-api/src/service/imports/import_plan/validation.rs create mode 100644 apps/admin-api/tests/integration/openapi_import/import_plan_apply/support_matrix.rs create mode 100644 apps/admin-api/tests/integration/openapi_import/import_plan_create/route_get.rs create mode 100644 apps/admin-api/tests/integration/openapi_import/large_preview.rs create mode 100644 apps/admin-api/tests/integration/openapi_import/upload_outcomes.rs create mode 100644 apps/admin-api/tests/integration/openapi_import/v5_replay.rs create mode 100644 apps/ui/tests/e2e/openapi-preview-partial.spec.js create mode 100644 apps/ui/tests/e2e/openapi-preview-reference.spec.js create mode 100644 crates/crank-registry/src/postgres/import_job/catalog.rs create mode 100644 crates/crank-registry/src/postgres/import_job/plan_apply/revalidate.rs create mode 100644 crates/crank-registry/src/postgres/import_job/semantic.rs create mode 100644 crates/crank-registry/tests/integration/import_plan/preview_v2.rs diff --git a/_bmad-output/implementation-artifacts/deferred-work.md b/_bmad-output/implementation-artifacts/deferred-work.md new file mode 100644 index 0000000..e0971d8 --- /dev/null +++ b/_bmad-output/implementation-artifacts/deferred-work.md @@ -0,0 +1,106 @@ +# Deferred Work + +## Deferred from: verification of 2-7-openapi-normalizedir (2026-08-29) + +- `just rust-code-health` остаётся красным только из-за двух файлов baseline Story 2.1, не изменённых Story 2.7: `crates/crank-artifacts/src/housekeeping.rs` (1119 строк) и `crates/crank-artifacts/tests/artifact_store.rs` (1103 строки). Все production/test-файлы Story 2.7 меньше лимита 1000 строк; требуется отдельный механический split artifact-store модулей без смешивания с NormalizedIR diff. + +## Deferred from: code review of 1-1-capability-inventory.md (2026-08-08) + +- RESOLVED 2026-08-08 — `event-listener` обновлён с 5.4.1 до 5.4.2 в рамках review remediation после уточнения владельца; RUSTSEC-2026-0221 устранён, полный `just verify` прошёл. + +## Deferred from: code review of 1-4-versioned-migration-authority.md (2026-08-09) + +- Изменение `Cargo.lock` для `event-listener` не относится к Story 1.4: это ранее одобренная и уже закрытая security remediation Story 1.1. В evidence Story 1.4 нужно явно атрибутировать этот baseline, а не повторно менять lockfile. + +## Deferred from: code review of 1-10-lifecycle-auth-profiles-machine-keys.md (2026-08-21) + +- Auth Profiles have no lifecycle status for retired/disabled profiles (`crates/crank-community-mcp/src/app.rs:1007`). Deferred because current Story 1.10 can enforce Secret/key terminal state, while AuthProfile status/tombstone semantics require a broader domain/storage lifecycle change and migration. + +## Deferred from: code review of 1-10-lifecycle-auth-profiles-machine-keys.md (2026-08-24) + +- Secret deletion currently hard-deletes encrypted versions and the Admin API has no explicit disable/tombstone operation (`crates/crank-registry/src/postgres/secret.rs:315`). Durable Secret tombstones, disable/restore transitions and retention policy require a broader schema lifecycle change. +- Credential lifecycle mutations commit before the best-effort audit sink is called (`apps/admin-api/src/service.rs:317`). Atomic audit delivery requires a durable transactional outbox and cross-cutting persistence/worker design. + +- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-artifact-filesystem-reconciliation.md` + summary: Story 2.4 реализует PostgreSQL claim/recheck/finalize protocol, crash recovery coordinator и bounded Admin scheduling. + evidence: DB authority и background orchestration являются отдельным independently reviewable goal, зависящим от готовых filesystem capabilities 2.1b2a. + +## Resolved at completion of Story 2.1 (2026-08-29) + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-3-artifact-filesystem-reconciliation.md` + summary: Изолировать test-only traversal syscall counter и вернуть прход default-parallel `cargo test -p crank-artifacts --test reconciliation`. + evidence: Process-global `TRAVERSAL_CALLS` сбрасывается и читается exact-budget тестом одновременно с другими reconciliation tests; production scanner не затронут, а serial repository verification проходит. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-4-artifact-claim-recovery.md` + summary: Изолировать process-global fault seams и traversal counters, чтобы reconciliation suite стабильно проходил с default parallelism. + evidence: Blind review воспроизвёл шесть падений при обычном parallel `cargo test`; согласованная serial verification проходит, production scanner и coordinator этим test-only race не затронуты. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md` + summary: Сделать replay ответа OpenAPI apply идентичным первому ответу, когда selected_operation_keys содержит отсутствующие operation keys. + evidence: Локальные skipped entries формируются в AdminService и не входят в сохранённый ImportJobApplyResult; завершённая job при повторе поэтому возвращает только сохранённые created/conflict результаты. Поведение существовало до verified-source изменения и требует отдельного уточнения create/apply response semantics. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md` + summary: Убрать календарную зависимость из reconciliation_claims_are_fenced_global_and_allow_verified_revival. + evidence: Тест использует detached_at 2026-08-27T10:02:00Z и ожидает попадание в 24-часовой grace относительно реального database clock; 2026-08-28 он стабильно возвращает другой outcome. Изолированный повтор воспроизводит падение, а OpenAPI/Story 2.5 пути этот тест не затрагивает. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Учитывать quality weights и порядок предпочтения в Accept-Language для OpenAPI upload diagnostics. + evidence: `openapi_upload_locale` выбирает RU при любом диапазоне `ru`, включая `ru;q=0` после предпочтительного `en`, поэтому может вернуть язык, который клиент явно запретил. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Сделать cleanup expired OpenAPI jobs и dangling sources исчерпывающим при объёме больше одного batch. + evidence: `delete_expired_import_jobs` обрабатывает не более `IMPORT_JOB_CLEANUP_BATCH` записей за вызов и не повторяет выборку, поэтому startup оставляет хвост при backlog больше 128. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Запускать lifecycle cleanup OpenAPI artifacts периодически на тихом долгоживущем Admin API. + evidence: cleanup вызывается на startup и при preview/apply; без нового import traffic истёкшие jobs и sources могут оставаться дольше retention window. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Сделать аварийный detach OpenAPI source надёжным при cancellation и остановке runtime. + evidence: `SourceDetachGuard::drop` запускает fire-and-forget task и игнорирует результат; shutdown или transient DB failure могут оставить active source до последующего reconciliation. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Добавить process-level startup recovery test для dangling OpenAPI source. + evidence: текущие integration tests вызывают registry cleanup напрямую; удаление startup-вызова из `main.rs` не будет обнаружено. + +- RESOLVED 2026-08-29 — source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Закрыть race между чтением Pending import job и detach source конкурентным успешным apply. + evidence: второй запрос может прочитать Pending до завершения первого, а затем увидеть уже detached source и вернуть source-unavailable вместо replay canonical result. + +- source_spec: `_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md` + summary: Сохранять unknown-operation skips в canonical OpenAPI apply result для идентичного replay. + evidence: unknown selected keys добавляются только в локальный response, но не в `ImportJobApplyResult`, поэтому completed fast path их не воспроизводит. +- source_spec: `_bmad-output/implementation-artifacts/spec-ci-community-scope-marker.md` + summary: Укрепить cleanup import jobs против повреждённых legacy `preview_payload`. + evidence: `jsonb_array_elements` вызывается без проверки array-типа, а tolerant cleanup принимает любой bounded `source_id`, поэтому corrupt payload может сорвать sweep либо отсоединить посторонний source того же workspace. + +- source_spec: `_bmad-output/implementation-artifacts/spec-2-9-http-contract.md` + summary: Проверять undeclared path placeholders в некорректных OpenAPI specifications (review B8, pre-existing). + evidence: Проверка parameter→placeholder не проверяет обратное направление; baseline adapter оставляет placeholder без объявленного параметра. Нужна отдельная malformed-spec regression и согласованная точная диагностика. + +- source_spec: `_bmad-output/implementation-artifacts/spec-2-9-http-contract.md` + summary: Определить сохранение либо явный blocker для object/array schema defaults в normalized IR (review E8, pre-existing). + evidence: normalized_literal и до Story 2.9 представлял только scalar defaults; compound defaults пропадают. Нужны совместимый IR contract и roundtrip fixtures, не изменение replay старых jobs. + +### DW-1: Проверить credential URL query, если поддерживаемый downstream consumer использует semicolon separator. +origin: spec-deferred fd22e0cb4a86 +location: crates/crank-import/src/rest/metadata_findings.rs::query_has_secret_parameter +source_spec: `spec-2-10-security-schemes-secrets.md` +reason: BH-F7, maybe-false: scanner использует form_urlencoded с &; конкретный поддерживаемый consumer, который интерпретирует ; как границу credential parameter, не показан. Нужны consumer/config и wire regression для установления фактического поведения. Это новая unverified гипотеза, не статус существующей записи ledger. +status: open + +### DW-2: Проверить credential URL query для поддерживаемого proxy/server с повторным percent decoding имени. +origin: spec-deferred 69f3c5c359cf +location: crates/crank-import/src/rest/metadata_findings.rs::query_has_secret_parameter +source_spec: `spec-2-10-security-schemes-secrets.md` +reason: BH-F8, maybe-false: текущая проверка совпадает с однократным form decoding; reachable proxy/server со вторым decoding не продемонстрирован. Нужны конкретный consumer/config и wire regression. Это новая unverified гипотеза, не статус существующей записи ledger. +status: open + + +### DW-3: Проверить AC-11 Reference preview p95 после deploy Story 2.12 на crank.itexp.me. +origin: user-deferred 2026-10-03 +location: apps/ui/tests/e2e/openapi-preview-reference.spec.js; docs/openapi-import.md +source_spec: `spec-2-12-preview-partial-mode.md` +reason: Пользователь разрешил закрыть Story 2.12 и перенести оставшийся внешний benchmark в deferred work. Функциональные проверки, bounded DOM до 2000 candidates, API/registry suites, Playwright 40 scenarios и полный just verify PASS. Фактический end-to-end Reference p95 ≤2 s не измерен; local mocked handler samples его не подтверждают. Существующий deployment crank.itexp.me отвечает, но проверенный опубликованный UI ещё не содержит partial mode/revalidation этой story; покупать новый стенд не требуется. +acceptance: После штатного merge/deploy подтвердить deployed revision/image digest, проверить фактические Reference environment параметры и отдельное размещение browser/load-generator, получить авторизованную test session и выполнить готовый harness с 20 real preview samples. Сохранить sanitized environment, raw samples и p95; при соответствии Reference условиям и p95 ≤2000 ms приложить evidence и закрыть DW-3, иначе исправить производительность либо явно зафиксировать отличие окружения без ложного PASS. +status: open diff --git a/_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md b/_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md new file mode 100644 index 0000000..8e9c7e0 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md @@ -0,0 +1,230 @@ +--- +title: '2.12 — Предоставить полный preview и явный partial mode' +type: feature +created: '2026-10-03' +status: done +baseline_revision: d1ba0bd0e4135a42bd710ee06df0acf27e5b488f +review_loop_iteration: 0 +followup_review_recommended: true +context: + - _bmad-output/implementation-artifacts/epic-2-context.md +warnings: [oversized] +deferred: + - summary: >- + Проверить AC-11 end-to-end preview p95 ≤2 секунд после штатного deploy Story 2.12 на crank.itexp.me (DW-3). + evidence: |- + Функциональные и bounded-rendering проверки PASS; фактический Reference p95 не измерен. Существующий deployment доступен, но опубликованный UI ещё не содержит Story 2.12. После deploy проверить revision/image digest и параметры Reference environment, запустить готовый openapi-preview-reference.spec.js из отдельного browser host с авторизованной сессией, сохранить 20 raw samples/environment/p95. Локальные mocked handler samples не доказывают AC-11. Пользователь явно разрешил перенести этот замер в deferred work и закрыть story. + location: >- + apps/ui/tests/e2e/openapi-preview-reference.spec.js; docs/openapi-import.md; deferred-work.md#dw-3 + severity: medium (unverified) +--- + + + +## Intent + +**Problem:** Preview теряет source locations, не показывает deterministic naming conflicts и рендерит все строки; partial импорт получается неявно. Plan digest зависит от случайного ID, а catalog drift не обозначается при повторном открытии. + +**Approach:** Завершить полный детерминированный preview и immutable plan evidence, добавить явный partial mode, bounded UI и read-only plan revalidation. Проверить все AC Story 2.12 на API и пользовательской поверхности. + +## Boundaries & Constraints + +**Always:** API вычисляет actionable из typed findings/security и verified references. Full mode запрещает Apply при любом blocker всего документа. Partial включается явно, selected candidates должны быть actionable с замкнутыми разрешёнными references; excluded/blocked сохраняют причины в plan/report. Сохранять immutable source/старые plans, workspace isolation, redaction, auth authority и request revision guards. Поддержать до 2000 candidates с bounded rendering и findings, RU/EN и keyboard/live statuses. Только verified external snapshots, без повторного mutable remote fetch. Read-only revalidation не создаёт Operations/versions/bindings/profiles. Canonical digest не включает random plan/job/source row IDs, время, request ID; semantic state, source/external digests, catalog revision и selections входит. Legacy сохранённые планы продолжают проверяться по своему контракту. + +**Never:** Записывать или откатывать sprint-status.yaml. Выполнять whole-epic corpus qualification Story 2.14, onboarding Story 2.15 или расширять atomic Apply Story 2.13 сверх необходимых совместимых проверок этой story. Raw credentials в artifacts/DOM/logs/plans. Выдавать mock/local latency за Reference Deployment proof. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| Full/blocker | Один либо document blocker, full mode | Полный count/affected candidates; Apply запрещён, мутаций нет | Safe finding code/location | +| Partial | Явный mode и subset | Только API-actionable с resolved references; excluded/blocked причины в plan/report | Незамкнутый/blocked subset отвергается | +| Determinism | Те же digests/config/catalog/selections, иные request IDs/time | Те же ordered candidates/findings/summary/semantic digest | Changed selection/name/auth/decision меняет digest | +| Naming | Duplicate/invalid/taken name | Conflict type/location и deterministic rename proposal, разрешённый выбор | Snapshot неизменен | +| Stale | Catalog/Auth Profile drift либо старый response | Read-only revalidation показывает stale и снимает прежнюю authority | Re-preview guidance; mutation отсутствует | +| Large | 2000 candidates, bounded findings | Search/filter/groups и bounded pagination, сохранение selection между страницами | Измерение интерактивности p95 ≤2 s с явным environment | +| Upload | valid/invalid/empty/oversized/no-methods RU/EN | Реальные методы, точные безопасные outcomes; до Apply нет Operations | Replacement/context guards | + + + +## Code Map + +- `crates/crank-import/src/rest/model.rs:493` — ImportFinding и ImportOperationCandidate теряют locations; NormalizedIr/reference_graph сохраняет source pointers/digests. `normalize_projection.rs:12` — mapping IR → preview; `naming.rs` — reuse deterministic names; `normalize.rs` — ordering/typed readiness. +- `apps/admin-api/src/service/imports.rs:55` — cap 512; verified upload preview и safe profile choices. `imports/verified_preview.rs` — immutable replay/fingerprint normalizer/projection/IR/preview digests. `dto.rs:544` — response view, add bounded typed metadata. +- `apps/admin-api/src/service/imports/import_plan.rs:7` — resolve_plan_selection, security bindings, name conflicts, persisted payload including random plan_reference. `imports/plan_apply.rs` — source/auth drift and safe recovery. `routes/imports.rs`, `app.rs` — existing scoped plan routes, add read-only reopen/revalidation route. +- `crates/crank-registry/src/postgres/import_job.rs:94` — immutable persistence, canonical payload digest; `import_job/plan_apply/material.rs` — stored plan validation and limits, `verify.rs` — apply revalidation. Existing registry catalog reads permit deterministic workspace revision over relevant catalog/auth state; avoid unrelated DB schema abstraction. +- `apps/ui/js/openapi-import.js:778` — renderPreview renders all rows; :1728 implicit partial. Reuse decisions/security guards, mapping details, filters and confirmation. `apps/ui/index.html` — controls; `js/i18n.js` RU/EN; `css/openapi-import.css` — existing styles. Small sibling helpers allowed for code-health limits. +- `apps/ui/tests/e2e/openapi-import-plan.spec.js`, `openapi-security-mapping.spec.js`, `operations.spec.js` — harness plus real API round-trip. `apps/admin-api/tests/integration/openapi_import.rs`, `import_plan_create/`, `crates/crank-registry/tests/integration/import_plan/`, `crates/crank-import/tests/preview.rs` — reuse no-mutation, stale, workspace and partial tests. +- `_bmad-output/test-artifacts/test-design-epic-2.md`, `test-design-qa.md` — required strategy. PRD §5.1 Reference Deployment: Linux x86_64, services+PG16/Valkey8 4vCPU/8GiB, separate equivalent load generator, SSD 3000 IOPS/100MB/s and 1Gbit LAN. Use reproducible benchmark evidence; document actual limits honestly. + +## Tasks & Acceptance + +**Execution:** +- [x] `apps/ui/tests/e2e/openapi-preview-partial.spec.js`, relevant existing Rust integration test modules and `_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md` — separate ATDD stage; frozen AC snapshot, matrix mapping, real RED/existing GREEN. +- [x] `crates/crank-import/src/rest/model.rs`, `normalize_projection.rs` and minimal constructors — expose source locations/stable codes without semantic loss; backward replay compatibility. +- [x] `apps/admin-api/src/service/imports/`, `dto.rs`, `routes/imports.rs`, `app.rs`, `crates/crank-registry/src/postgres/import_job.rs`, `import_job/plan_apply/` — deterministic semantic digest, complete plan metadata/findings/catalog revision, naming proposals/readiness, read-only reopen/revalidation, safe partial closure and 2000 bound. Keep existing Apply invariants. +- [x] `apps/ui/js/openapi-import.js`, necessary sibling helpers, `index.html`, `js/i18n.js`, `css/openapi-import.css` — explicit partial control, API authority, complete preview/conflicts/source locations, bounded pagination/selection, stale revalidation RU/EN. +- [x] `docs/openapi-import.md`, checklist and story — document actual contracts, record executed acceptance/latency evidence and limits. +- [x] `crates/crank-metrics/src/schema.rs`, `tests/schema_v1.rs`, `docs/schemas/metrics-registry-v1.json` — register read-only plan route in closed HTTP metrics domain; recalculate exact bounded cardinality and snapshot, preserving existing budget headroom. + +**Acceptance Criteria:** + +**Given** успешно проанализированный source snapshot +**When** backend формирует preview +**Then** он возвращает groups/tags, endpoint candidates, proposed names, methods/paths, input/output schemas, mappings, security bindings, conflicts, warnings и unsupported findings +**And** каждый элемент связан с source location и stable finding code. + +**Given** preview request +**When** parsing, resolution и mapping завершаются +**Then** ни одна Operation, Operation Version, Agent binding или Auth Profile не создаётся и не изменяется +**And** единственными сохраняемыми объектами являются immutable source snapshots и preview/plan artifacts. + +**Given** одинаковые source digests, importer config, catalog revision и user selections +**When** preview формируется повторно +**Then** ordered candidates, findings, summary и plan digest совпадают детерминированно +**And** runtime timestamps и request IDs не входят в canonical digest. + +**Given** generated candidate names +**When** обнаружены duplicate, invalid или уже занятые names +**Then** UI показывает deterministic rename proposal и conflict type +**And** пользователь может выбрать разрешённое имя без изменения исходного snapshot. + +**Given** candidate без blocker findings и с разрешённой authentication +**When** preview оценивает готовность +**Then** candidate получает status `actionable` +**And** status вычисляется из typed findings/requirements, а не устанавливается клиентом произвольно. + +**Given** хотя бы один blocker finding +**When** пользователь не включал partial mode +**Then** Apply всего документа запрещён +**And** UI показывает полный blocker count и affected candidates без создания частичного набора Operations. + +**Given** пользователь явно включает partial mode +**When** он выбирает subset candidates +**Then** selected set может содержать только actionable candidates с замкнутыми разрешёнными dependencies +**And** excluded/blocked candidates и причина исключения сохраняются в ImportPlan и итоговом report. + +**Given** изменение selection, proposed name, Auth Profile mapping или conflict policy +**When** пользователь подтверждает новый preview state +**Then** создаётся новая immutable ImportPlan version с новым digest +**And** прежний plan остаётся доступным для audit, но не изменяется in place. + +**Given** immutable ImportPlan +**When** он сохраняется +**Then** plan связывает source и external snapshot digests, importer/support-matrix version, catalog revision, candidates, selections, mappings, findings и conflict decisions +**And** не содержит raw credentials или mutable remote references. + +**Given** catalog либо Auth Profile state изменились после preview +**When** UI повторно открывает plan +**Then** plan получает stale/revalidation-required status +**And** UI не утверждает, что прежний actionable status гарантирует успешный Apply. + +**Given** preview большого документа +**When** UI отображает до 2 000 candidates и bounded findings +**Then** используются search/filter/grouping и bounded pagination/virtualized rendering без загрузки unbounded DOM +**And** основной экран становится интерактивным ≤2 s p95 на Reference Deployment LAN. + +**Given** preview UI на RU и EN +**When** пользователь загружает реальный `openapi.yaml`, меняет selection или получает findings +**Then** UI реализует uploading, parsing, loading, empty/no-methods, error, actionable, blocked, stale и confirmation states +**And** request generation guard не позволяет старому preview перезаписать новый файл или selection. + +**Given** end-to-end upload regression +**When** загружаются valid `openapi.yaml`, invalid, empty, oversized и no-method documents +**Then** valid case показывает методы именно загруженного файла, остальные дают точные pre-mutation outcomes +**And** database assertions подтверждают отсутствие созданных Operations до Apply. + +**Given** preview verification suite +**When** выполняются API/Playwright tests +**Then** покрыты deterministic output, blockers, explicit partial selection, dependency closure, naming conflicts, stale plan, cross-workspace access и no-mutation contract +**And** `just verify` и UI build проходят. + +## Spec Change Log + +- 2026-10-03: AC сохранены. Уточнена provenance производных групп/counts через membership; реализация использует preview-v6 и import-plan-v2 с совместимостью исторических payloads. Внешний AC-11 Reference Deployment остаётся операторским evidence, не заменяется mock timings. +- 2026-10-03: полный workspace gate обнаружил необходимую зависимость нового GET route от закрытого metrics domain. Добавлена задача синхронизации домена/schema snapshot; увеличение бюджетов ограничено точным вкладом одного route (+70 logical, +220 rendered), прежний запас сохранён. + +## Review Triage Log + +### 2026-10-03 — Review pass +- verdicts: 13 findings — high 0, medium 3, low 4, false 6, maybe-false 0 +- findings: + - `[medium]` `[patch]` Verification-gap: новый GET revalidation не проверяется через настоящий router — service tests и mocked UI действительно не покрывают регистрацию/session/workspace boundary; добавлен route_get regression через настоящий HTTP router: exact reference/digest, current/stale, 401 без сессии, 403 чужого workspace и отсутствие GET mutations; адресный тест PASS. + - `[false]` `[reject]` Blind-1: schemas/mappings якобы не связаны с source — публичные schemas/mappings принадлежат candidate с RFC 6901 location; immutable source/dependency digests и IR fingerprint связывают material с проверяемой provenance. Внутренние parser-only schema-location slots были пусты до этой story и не являются обещанными полями публичного preview; связи candidate/provenance не утрачены. + - `[low]` `[reject]` Blind-2: предлагается согласовать Design Notes и AC путём изменения spec — typed code принадлежит finding; агрегаты связаны membership candidates, отдельный pointer/code приписал бы ложную provenance. Кроме того, workflow явно отклоняет findings, исправлением которых является редактирование build spec. + - `[medium]` `[patch]` Blind-3: label выбора группы обещает всю группу, callback меняет только page slice — фактически header показывает общий размер, а выбор bounded текущей страницей. Прямое исправление RU/EN label обозначает «группу на этой странице», сохраняя действие и separate Select visible semantics; regression проверяет page scope и сохранённый выбор следующей страницы; PASS. + - `[low]` `[patch]` Blind-4: document findings доступны только на page0 — условие `state.pageIndex === 0` реально убирает panel на других страницах. Прямое удаление этого условия сохраняет lazy bounded findings и доступ к ним на каждой странице; добавлен paging assertion; адресный и полный browser suite PASS. + - `[false]` `[reject]` Blind-5: global blocker якобы запрещает независимый actionable subset — server `attach_preview_readiness` и `global_blocker` plan creation помечают каждый candidate blocked при document-level Error без operation key. Независимых actionable candidates в таком состоянии нет; candidate-scoped blocker исключается в explicit partial и покрыт тестами. + - `[false]` `[reject]` Blind-6: global excluded reason якобы неверен — document-level blocker применяется ко всем candidates; его code является действительной причиной исключения, даже если присутствует дополнительный candidate error. Контракт не обещает приоритет самой узкой из нескольких истинных причин; причины сортированы и сохранены в plan/report. + - `[false]` `[reject]` Blind-7: catalog check якобы отделён от записи — registry `create_import_plan` повторно проверяет revision внутри той же transaction до INSERT, с workspace FOR UPDATE и catalog FOR SHARE. API double-read является предварительным guard, а не последней authority. + - `[medium]` `[reject]` Blind-8: Reference p95 ещё не подтверждён — факт отсутствия внешнего evidence записан честно, acceptance не объявлен полным. Пользователь явно требует завершать agent-can работу и оформлять внешние человеческие обязанности как awaiting-operator; это route в operator_actions при финализации, не defect кода и не blocked. + - `[low]` `[reject]` Blind-9: harness не подтверждает hardware независимо от operator manifest — report явно помечает provenance `operator_manifest`, документация требует подтверждённых фактических параметров и не называет manifest сертификатом. Автоматическая проверка удалённого hardware потребовала бы новых privileges/интерфейсов; фактическое подтверждение стенда включается в operator actions. + - `[false]` `[reject]` Blind-10: legacy stale якобы нарушает собственный контракт — legacy payload/digest остаются неизменными/readable, legacy job replay сохраняется. Baseline Apply уже требовал current normalizer/projection для новой мутации; v5→v6 является настоящим importer change, v1 plan без catalog evidence нельзя выдавать за current authority. + - `[low]` `[reject]` Intent-alignment: in-review frontmatter ещё не содержит operator_actions/Auto Run Result/commit — это верное описание промежуточного review state, который workflow требует до Finalize. Пользователь требует сначала code commit, затем awaiting-operator; финальное оформление выполняется после patches/gate. Finding, исправляющий лишь spec, отклонён согласно правилу workflow. + - `[false]` `[reject]` Edge-case: clean candidates якобы лишены обещанного finding code — clean candidate не является finding и не должен получать вымышленный diagnosis code. Он имеет stable key/location; существующие typed findings сохраняют точные code/location, проверенные pure/API/UI тестами. Добавление code чистой сущности не требуется для связи source-derived preview с evidence. + +## Design Notes + +References разрешаются и материализуются до создания candidate; unresolved/unsupported references блокируют candidate. Замыкание означает сохранение materialized schemas/mappings и проверку всех immutable snapshots зависимостей, без вымышленных межоперационных связей. Conflict policy означает существующие create/skip/rename/new_version decisions. Сохранить evidence исходных duplicate/invalid имён. Catalog revision детерминирован по relevant workspace catalog/auth metadata без runtime timestamps; консервативная invalidation при drift допустима. Новая immutable запись/reference является версией; старые rows доступны для audit. + +Для AC-1 source location относится к source-derived candidate, finding и naming conflict; schemas/mappings принадлежат candidate и сохраняют IR/reference provenance. Производные groups, counts и summary связаны с исходником через membership candidates. Не назначать им вымышленный единственный source pointer или finding code; стабильный code принадлежит typed finding. + +Этапы: ATDD отдельно, затем backend contract, затем UI; каждый результат принимается до следующего. Один автор на файл, исполнитель не один в codebase; не откатывать чужую работу. Эта spec — единственный источник задания. На ATDD разрешены только tests/checklist; при реализации разрешены перечисленные Tasks пути и минимальные sibling helpers. Архитектурные изменения вернуть ведущему. + +## Verification + +- `cargo test -p crank-import` — pure preview/source/reference regression PASS. +- `cargo test -p admin-api --test integration` — scoped API no-mutation/determinism/partial/conflict/revalidation PASS (confirm actual package/test names from manifest before running). +- `cargo test -p crank-registry --test integration` — immutable plan compatibility/digest/partial/stale PASS. +- `cd apps/ui && npm run build` — PASS. +- `cd apps/ui && npx playwright test tests/e2e/openapi-preview-partial.spec.js tests/e2e/openapi-import-plan.spec.js tests/e2e/openapi-security-mapping.spec.js tests/e2e/operations.spec.js --workers=1` — all mandatory scenarios executed PASS, no skipped. +- `just verify` — full mandatory gate PASS. +- Reproducible large-preview benchmark (2000 candidates) — bounded DOM, interaction and p95 ≤2 seconds, actual environment and raw samples recorded; Reference Deployment evidence required by AC. + +### Проверка ведущего после implementation handoff + +- `cargo test -p crank-import` — PASS, 0 ignored. +- `cargo test -p admin-api --test integration -- --test-threads=1` — 125 PASS, 0 ignored; 1014.51 s при параллельной нагрузке. +- `cargo test -p crank-registry --test integration -- --test-threads=1` — 139 PASS, 0 FAIL, 1 ранее существовавший unrelated ignored; 751.61 s. +- `cd apps/ui && npm run build` — PASS. +- Полная указанная выше Playwright-команда — 40 PASS, 0 skipped, 3.0 min на финальном UI и финальных assertions. Предыдущий параллельный прогон: 37 PASS/3 timeout при общем 45 s budget в существующих operations scenarios; повтор без одновременной компиляции прошёл без изменения assertions/timeouts. +- `just verify` — PASS, exit 0, полный workspace gate через pipe/tee после metrics integration correction. Первый запуск выявил code-health limit (1001 строк), исправлен extraction v5 replay test без изменения assertions. Второй прошёл структурные gates/clippy/API, но прямой stdout-file redirect вызвал отказ существующего RLIMIT_FSIZE-теста; адресный запуск через pipe PASS, production/test-код не менялся. + +Третий gate обнаружил незарегистрированный новый GET в metrics route domain; внесена минимальная schema/test/canonical-JSON correction с точным приростом cardinality budget. Четвёртый gate полностью PASS. После трёх review patches полный gate выполнен снова и полностью PASS, exit 0. + +### Исправления после review + +Применены 3 patch entries: medium 2, low 1. HTTP GET regression проверяет router/session/workspace boundary, catalog drift и отсутствие мутаций. RU/EN подпись группового checkbox явно указывает текущую страницу; тест подтверждает сохранение выбора второй страницы. Document findings доступны на каждой странице с прежним lazy/bounded panel. Адресные HTTP и UI проверки PASS; ведущий повторил UI build и все 40 browser scenarios: PASS, 0 skipped, 2.9 min. Pure crank-import suite повторно PASS. + +### Matrix Test Audit + +| Строка | Фактически выполненные PASS-проверки | Статус | +|---|---|---| +| Full/blocker | API `operation_blockers_apply_only_to_selected_keys_and_full_selection_fails_atomically`; registry `apply_rejects_whole_plan_when_any_candidate_is_blocked`; UI AC-6 | PASS | +| Partial | API `partial_plan_rejects_selected_blocker_before_persistence`, `detached_dependency_snapshot_repreview_requires_without_a_plan`; registry `partial_v2_apply_preserves_the_reason_for_an_excluded_candidate`; UI AC-7 | PASS | +| Determinism | API `full_plan_is_server_authored_with_bounded_confirmation_and_no_mutation`; registry `v2_digest_ignores_job_plan_generated_operation_ids_and_runtime_timestamps`, `v2_digest_changes_for_selection_name_and_conflict_decision`; pure preview tests | PASS | +| Naming | API `preview_name_conflicts_are_typed_and_deterministic`; UI AC-4; crowded catalog unit test | PASS | +| Stale | API `reopening_plan_is_read_only_and_reports_catalog_drift`, existing Auth Profile/secret drift tests; registry `revalidation_and_apply_reject_catalog_drift_without_plan_mutation`; UI AC-10/12 | PASS | +| Large | API `previews_and_plans_two_thousand_operations_without_catalog_mutation`; registry `plan_store_accepts_the_full_two_thousand_candidate_limit`; UI AC-11 pagination/selection/findings/report; local raw handler samples | Agent-can PASS; Reference LAN p95 требует оператора | +| Upload | API `preview_outcomes_do_not_mutate_operation_catalog` с прямыми SQL counts; real browser AC-13; RU/EN states и request-generation AC-12 | PASS | + +Reference performance не объявляется verified: доступ к внешним отдельным 4 vCPU/8 GiB deployment/load-generator hosts отсутствует. Подготовлены реальный operator-run harness и manifest/команда в `docs/openapi-import.md`; первоначально внешняя проверка была оформлена через awaiting-operator после code commit и ревью; по последующей инструкции пользователя она перенесена в DW-3, story закрыта. + + +## Auto Run Result + +- status: done +- Реализованы полный детерминированный preview с source provenance/naming conflicts, explicit partial selection с сохранёнными excluded reasons, immutable semantic v2 plans, read-only scoped revalidation и bounded RU/EN UI до 2000 candidates. Legacy payload/digest и audit readability сохранены; новая Apply authority проверяет актуальные importer/catalog/auth snapshots. +- Существенные файлы: `crates/crank-import/src/rest/` — source locations и projection; `apps/admin-api/src/service/imports/` и routes/DTO — server-authored plans, readiness, revalidation; `crates/crank-registry/src/postgres/import_job/` — semantic digest, immutable evidence и transactional catalog guards; `apps/ui/js/openapi-import.js`, i18n/index/css — partial mode, bounded pages/findings, guards и доступность; integration/pure/Playwright tests — regression и no-mutation evidence; `crates/crank-metrics/src/schema.rs`, tests и canonical schema — регистрация нового GET с точным приростом бюджетов; `docs/openapi-import.md` и `openapi-preview-reference.spec.js` — операторский Reference benchmark; spec/checklist — приёмка и результаты. +- Review: 13 findings, high 0 / medium 3 / low 4 / false 6 / maybe-false 0. Применены 3 patches (high 0 / medium 2 / low 1), deferred 0, rejected 10. Причина отклонения каждого finding записана отдельно в Review Triage Log: шесть claims опровергнуты фактическими guards/contracts; два spec-only findings отклонены workflow; два Reference findings оформляются как честные operator obligations без утверждения performance acceptance. +- Follow-up review recommended: true — первая итерация исправила две medium entries. Конкретный непроверенный риск: AC-11 end-to-end p95 ≤2 s на фактическом Reference Deployment; результат зависит от deployment/LAN/browser hosts и ещё не измерен. После операторского запуска необходимо проверить raw samples, manifest и p95 перед объявлением AC-11 verified. +- После patches: pure import suite PASS; UI build PASS; Playwright 40 PASS, 0 skipped (2.9 min); admin-api integration 126 PASS, 0 ignored (528.43 s); registry integration 139 PASS, 1 pre-existing unrelated ignored (413.60 s). Финальный `just verify` PASS, exit 0: tooling 152 tests, structural/contracts/code health/fmt/clippy, полный workspace all-targets serial, включая API 126, registry 139 (1 pre-existing ignored), MCP 40 и остальные suites. +- Остаточный риск: внешняя Reference performance verification отсутствует; локальные browser handler samples и bounded DOM не заменяют этот evidence. Остальная agent-can matrix выполнена. `sprint-status.yaml` не редактировался и не включается в commits. + +- Cleanup: связанные test/preview/OpenCode процессы завершены; посторонние два контейнера/активных тома сохранены. `docker volume prune -f` без `--all` завершился exit 0, reported reclaimed 10.06 GB. После очистки docker volumes 2/2 active, свободно 100.34 GiB, Btrfs Metadata,DUP 1.31/7.01 GiB (18.72%), global reserve used 0; запас достаточен. Непривилегированная Btrfs usage summary доступна, per-device detail требует root и не получен. + +- Agent-can реализация закоммичена перед финализацией frontmatter: `b1eab258be476197784cbd13482116233f9338d9`. Первоначальная финализация использовала awaiting-operator; последующая инструкция пользователя переносит внешний замер в DW-3 и закрывает story со status: done. + +- Уточнение обязанностей: оператор предоставляет только отсутствующий внешний доступ. Настройку сервисов, проверку доступных параметров hosts, подготовку manifest, запуск benchmark, сохранение raw samples и оценку p95 выполняет агент после получения доступа; эти шаги не являются HUMAN-only действиями. + +- Уточнение пользователя: оставшийся внешний замер перенесён в deferred work DW-3; Story 2.12 закрыта со status: done, operator_actions сняты. Это не означает PASS AC-11: end-to-end Reference p95 остаётся непроверенным до отдельного запуска после штатного deploy на существующий crank.itexp.me. Review pass не переоценивался: его deferred count 0 относится к findings того pass, а новая запись добавлена по последующей прямой инструкции пользователя. `sprint-status.yaml` остаётся собственностью оркестратора и не изменён. diff --git a/_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md b/_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md new file mode 100644 index 0000000..fc5c2fd --- /dev/null +++ b/_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md @@ -0,0 +1,256 @@ +--- +stepsCompleted: ['step-01-preflight-and-context', 'step-02-generation-mode', 'step-03-test-strategy', 'step-04-generate-tests', 'step-05-validate-and-complete'] +lastStep: 'step-05-validate-and-complete' +lastSaved: '2026-10-03' +workflowType: 'testarch-atdd' +storyId: '2.12' +storyKey: '2-12-preview-partial-mode' +storyFile: '_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md' +atddChecklistPath: '_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md' +generatedTestFiles: + - 'apps/ui/tests/e2e/openapi-preview-partial.spec.js' +inputDocuments: + - '_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md' + - '_bmad-output/implementation-artifacts/epic-2-context.md' + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-epic-2.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad/tea/config.yaml' + - 'apps/ui/package.json' + - 'apps/ui/playwright.config.js' + - 'apps/ui/tests/e2e/helpers.js' + - 'apps/ui/tests/e2e/openapi-import-plan.spec.js' + - 'apps/ui/tests/e2e/openapi-security-mapping.spec.js' + - 'apps/ui/tests/e2e/operations.spec.js' + - 'apps/admin-api/tests/integration/openapi_import.rs' + - 'apps/admin-api/tests/integration/openapi_import/import_plan_create/mod.rs' + - 'apps/admin-api/tests/integration/openapi_import/import_plan_create/creation.rs' + - 'crates/crank-import/tests/preview.rs' + - 'crates/crank-registry/tests/integration/import_plan/create.rs' + - '.agents/skills/bmad-testarch-atdd/steps-c/step-01-preflight-and-context.md' + - '.agents/skills/bmad-testarch-atdd/steps-c/step-02-generation-mode.md' + - '.agents/skills/bmad-testarch-atdd/steps-c/step-03-test-strategy.md' + - '.agents/skills/bmad-testarch-atdd/steps-c/step-04-generate-tests.md' + - '.agents/skills/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md' + - '.agents/skills/bmad-testarch-atdd/checklist.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/data-factories.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/component-tdd.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/test-quality.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/test-healing-patterns.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/selector-resilience.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/timing-debugging.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/fixture-architecture.md' + - '.agents/skills/bmad-testarch-atdd/resources/knowledge/network-first.md' +acceptanceCriteria: + - id: 'AC-1' + idSource: 'generated' + text: 'Given успешно проанализированный source snapshot, when backend формирует preview, then он возвращает groups/tags, endpoint candidates, proposed names, methods/paths, input/output schemas, mappings, security bindings, conflicts, warnings и unsupported findings; каждый элемент связан с source location и stable finding code.' + - id: 'AC-2' + idSource: 'generated' + text: 'Given preview request, when parsing, resolution и mapping завершаются, then ни одна Operation, Operation Version, Agent binding или Auth Profile не создаётся и не изменяется; единственными сохраняемыми объектами являются immutable source snapshots и preview/plan artifacts.' + - id: 'AC-3' + idSource: 'generated' + text: 'Given одинаковые source digests, importer config, catalog revision и user selections, when preview формируется повторно, then ordered candidates, findings, summary и plan digest совпадают детерминированно; runtime timestamps и request IDs не входят в canonical digest.' + - id: 'AC-4' + idSource: 'generated' + text: 'Given generated candidate names, when обнаружены duplicate, invalid или уже занятые names, then UI показывает deterministic rename proposal и conflict type; пользователь может выбрать разрешённое имя без изменения исходного snapshot.' + - id: 'AC-5' + idSource: 'generated' + text: 'Given candidate без blocker findings и с разрешённой authentication, when preview оценивает готовность, then candidate получает status actionable; status вычисляется из typed findings/requirements, а не устанавливается клиентом произвольно.' + - id: 'AC-6' + idSource: 'generated' + text: 'Given хотя бы один blocker finding, when пользователь не включал partial mode, then Apply всего документа запрещён; UI показывает полный blocker count и affected candidates без создания частичного набора Operations.' + - id: 'AC-7' + idSource: 'generated' + text: 'Given пользователь явно включает partial mode, when он выбирает subset candidates, then selected set может содержать только actionable candidates с замкнутыми разрешёнными dependencies; excluded/blocked candidates и причина исключения сохраняются в ImportPlan и итоговом report.' + - id: 'AC-8' + idSource: 'generated' + text: 'Given изменение selection, proposed name, Auth Profile mapping или conflict policy, when пользователь подтверждает новый preview state, then создаётся новая immutable ImportPlan version с новым digest; прежний plan остаётся доступным для audit, но не изменяется in place.' + - id: 'AC-9' + idSource: 'generated' + text: 'Given immutable ImportPlan, when он сохраняется, then plan связывает source и external snapshot digests, importer/support-matrix version, catalog revision, candidates, selections, mappings, findings и conflict decisions; не содержит raw credentials или mutable remote references.' + - id: 'AC-10' + idSource: 'generated' + text: 'Given catalog либо Auth Profile state изменились после preview, when UI повторно открывает plan, then plan получает stale/revalidation-required status; UI не утверждает, что прежний actionable status гарантирует успешный Apply.' + - id: 'AC-11' + idSource: 'generated' + text: 'Given preview большого документа, when UI отображает до 2 000 candidates и bounded findings, then используются search/filter/grouping и bounded pagination/virtualized rendering без загрузки unbounded DOM; основной экран становится интерактивным ≤2 s p95 на Reference Deployment LAN.' + - id: 'AC-12' + idSource: 'generated' + text: 'Given preview UI на RU и EN, when пользователь загружает реальный openapi.yaml, меняет selection или получает findings, then UI реализует uploading, parsing, loading, empty/no-methods, error, actionable, blocked, stale и confirmation states; request generation guard не позволяет старому preview перезаписать новый файл или selection.' + - id: 'AC-13' + idSource: 'generated' + text: 'Given end-to-end upload regression, when загружаются valid openapi.yaml, invalid, empty, oversized и no-method documents, then valid case показывает методы именно загруженного файла, остальные дают точные pre-mutation outcomes; database assertions подтверждают отсутствие созданных Operations до Apply.' + - id: 'AC-14' + idSource: 'generated' + text: 'Given preview verification suite, when выполняются API/Playwright tests, then покрыты deterministic output, blockers, explicit partial selection, dependency closure, naming conflicts, stale plan, cross-workspace access и no-mutation contract; just verify и UI build проходят.' +--- + +# ATDD Checklist — Story 2.12: Предоставить полный preview и явный partial mode + +**Date:** 2026-10-03 +**Author:** Bsodfather +**Primary test level:** E2E (Playwright Chromium) для UI-наблюдаемых AC; существующие Rust INT/UNIT suites переиспользуются для backend-only AC (P1; epic scenario `2.12-API-A,B`, risks E2-R1/E2-R4). + +## Story summary + +Администратор до импорта видит полный детерминированный preview и может осознанно применить либо весь документ, либо явно выбранное подмножество actionable candidates. Неизменяемый ImportPlan связывает selections, findings и metadata без секретов, а stale/revalidation виден при повторном открытии. + +**As a** администратор +**I want** просмотреть все будущие Operations, конфликты и проблемы документа +**So that** могу исправить контракт либо осознанно импортировать только безопасную часть. + +## Approved acceptance criteria snapshot + +Supplied `AC-` IDs в спецификации отсутствуют; IDs назначены детерминированно по source order. Этот snapshot взят только из `Acceptance Criteria` в `_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md`, единственного источника требований для story. + +| ID | ID source | Acceptance criterion | +|---|---|---| +| AC-1 | generated | Preview возвращает groups/tags, candidates, proposed names, methods/paths, schemas, mappings, security bindings, conflicts, warnings, unsupported findings; каждый элемент связан с source location и stable finding code. | +| AC-2 | generated | Preview/plan не создаёт и не изменяет Operations/Versions/Agent bindings/Auth Profiles; сохраняются только immutable snapshots и preview/plan artifacts. | +| AC-3 | generated | При одинаковых digests/config/catalog/selections ordered candidates, findings, summary и plan digest детерминированны; timestamps/request IDs не входят в canonical digest. | +| AC-4 | generated | Duplicate/invalid/taken names дают deterministic rename proposal и conflict type; выбор допустимого имени не меняет исходный snapshot. | +| AC-5 | generated | Candidate без blockers и с разрешённой authentication получает `actionable` из typed findings/requirements, не от клиента. | +| AC-6 | generated | При blocker в full mode Apply всего документа запрещён; UI показывает полный blocker count и affected candidates без частичного набора Operations. | +| AC-7 | generated | Явный partial mode принимает только actionable subset с замкнутыми разрешёнными dependencies; excluded/blocked и причины сохраняются в ImportPlan и report. | +| AC-8 | generated | Изменение selection/name/Auth Profile/conflict policy создаёт новую immutable ImportPlan version с новым digest; прежний plan остаётся доступным, не мутируется in place. | +| AC-9 | generated | Immutable ImportPlan связывает source/external digests, importer/support-matrix version, catalog revision, candidates, selections, mappings, findings, conflict decisions; без raw credentials и mutable remote references. | +| AC-10 | generated | При изменении catalog/Auth Profile после preview повторное открытие plan даёт stale/revalidation-required status; UI не гарантирует успешный Apply. | +| AC-11 | generated | До 2000 candidates и bounded findings с search/filter/grouping и bounded pagination/virtualized rendering без unbounded DOM; интерактивность ≤2 s p95 на Reference Deployment. | +| AC-12 | generated | RU/EN состояния uploading/parsing/loading/empty/no-methods/error/actionable/blocked/stale/confirmation; request generation guard не даёт старому preview перезаписать новый файл/selection. | +| AC-13 | generated | E2E upload regression для valid/invalid/empty/oversized/no-method; valid показывает методы загруженного файла; DB assertions подтверждают отсутствие Operations до Apply. | +| AC-14 | generated | API/Playwright suite покрывает deterministic output, blockers, explicit partial selection, dependency closure, naming conflicts, stale plan, cross-workspace access, no-mutation; `just verify` и UI build проходят. | + +## Story integration metadata + +- **Story ID:** `2.12` +- **Story key:** `2-12-preview-partial-mode` +- **Story file:** `_bmad-output/implementation-artifacts/spec-2-12-preview-partial-mode.md` +- **Checklist:** `_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md` +- **Test file:** `apps/ui/tests/e2e/openapi-preview-partial.spec.js` (9 leaves: AC-7 активирован и реально RED; остальные 8 остаются skipped preparation) +- **Context:** `_bmad-output/implementation-artifacts/epic-2-context.md`; canonical Epic 2 test design `2.12 / 2.12-API-A,B` (FR-7, AC groups 14, P1, E2-R1/E2-R4). + +## Preflight and generation decisions + +- Baseline из frontmatter спецификации и текущий HEAD: `d1ba0bd0e4135a42bd710ee06df0acf27e5b488f`. Worktree уже содержал оставленный незавершённым предыдущим запуском untracked E2E-файл; он изучен и продолжен. +- Stack: `fullstack` (Rust `Cargo.toml` + Playwright в `apps/ui/playwright.config.js`). Framework config: `apps/ui/playwright.config.js`, testDir `apps/ui/tests/e2e`, Chromium, workers=1. +- Generation mode: AI specification mode, unattended. Запись браузером не выполнялась (нет поднятого dev-стека); селекторы для ещё не реализованных контролов — предлагаемые доступные имена/`data-testid` (см. DOM contract). +- `@seontechnologies/playwright-utils` отсутствует в `apps/ui/package.json`; applicability gate закрыт. Существующий suite использует `@playwright/test` и `page.route`; новые scaffolds следуют этой же манере. Pact-ветка не релевантна (нет Pact-артефактов/брокера). +- Заданий production-кода не вносилось. Изменены только E2E test-файл и этот checklist; `sprint-status.yaml` не трогался. +- `npm ci` выполнен в `apps/ui` по существующему lockfile; tracked manifests/lockfile не изменялись. Локальный Chromium уже был установлен. +- Reuse over duplication: для API/backend AC не создавались дублирующие E2E проверки. Упомянутые ниже существующие Rust/Playwright cases пока только проверены по исходникам: в этой стадии они не запускались и поэтому не объявляются измеренным GREEN. + +## Scenario-to-AC mapping + +Каждый AC имеет один основной oracle. Таблица различает source-level найденные reusable tests, новые E2E UI contract mocks и отсутствующие/неисполненные доказательства. Только AC-7 получил выполненный RED. Ни один существующий тест не объявляется GREEN по одному наличию исходника. + +| AC | Уровень | Reuse / evidence status | Primary scaffold и оставшаяся работа | +|---|---|---|---| +| AC-1 | API/INT + E2E | Reusable parser/source tests found in `preview.rs`, `http_contract_regressions.rs`, `coverage.rs`, security suites; **not run here**. | Skipped E2E asserts UI rendering only with mocked API. Backend projection still needs Rust test: finding/candidate source locations and typed conflicts are absent from preview DTO. | +| AC-2 | INT | No-mutation candidates found in `import_plan_create/creation.rs`, `openapi_import.rs`, registry create suite, and `operations.spec.js`; **not run here**. | Reuse these as implementation evidence after running on candidate; no new E2E leaf. | +| AC-3 | UNIT/INT | Corpus equality covers normalized output; it does not establish canonical plan digest. Relevant plan tests found but **not run here**. | Required new/extended Rust regression: independent equivalent plan generations with different random IDs/times must have equal semantic digest while semantic changes differ. Source currently includes random `plan_reference` in digest material. | +| AC-4 | E2E + API | Legacy import/name conflict tests and registry plan conflict case found; **not run here**. | Skipped E2E uses a mocked preview conflict and proposed name; backend typed conflict/source-location projection still needs an API/Rust test. | +| AC-5 | API | Client-authority rejection/count/security availability tests found; **not run here**. | No new E2E leaf. Run/reuse typed-readiness tests on candidate; preserve proof that client cannot set `actionable`. | +| AC-6 | E2E + INT | Blocked apply suites and existing mixed-plan UI test found; **not run here**. | Skipped E2E uses mocked findings/plan to check UI blocker summary. API/DB authority and no-mutation need executed backend tests. | +| AC-7 | E2E + INT | `resolve_plan_selection`, partial apply and dependency snapshot tests found; **not run here**. | E2E leaf is active and gives actual RED at missing `#openapi-import-partial-mode`. Later assertions use mocked preview/plan and only specify the UI request/display contract; dependency closure, persisted exclusions, and report require real Rust/API tests. Closure follows spec Design Notes (materialized schemas/mappings and immutable snapshot validation). | +| AC-8 | E2E + INT | Immutable replay/version cases found; **not run here**. | Skipped E2E assigns synthetic `d…`/`e…` digests by call count; this checks intended UI rendering only and cannot prove digest derivation, plan immutability, or old-plan auditability. Backend audit/reopen route and tests remain required. | +| AC-9 | INT | Existing source/dependency/fingerprint/no-secret cases found; **not run here**. | Required Rust payload/storage tests for source/external digests, importer/support-matrix version, catalog revision, findings and conflict decisions, plus raw-secret/mutable-reference rejection. Current plan payload lacks required metadata fields. | +| AC-10 | E2E + INT | Auth Profile/secret drift/apply stale cases found; **not run here**. Apply-time stale rejection is not proof of read-only reopen UI. | Skipped E2E mocks plan and a 409 apply response; must be changed to exercise actual persisted-plan reopen/revalidation route. | +| AC-11 | E2E + benchmark | No pagination source found; UI currently renders rows directly and server cap is 512. | Skipped 2,000-row mock E2E is unexecuted and itself has weak pagination/search assertions; interaction p95 must be separately measured on Reference Deployment LAN. Local 4-CPU/browser same-host evidence is not a substitute. | +| AC-12 | E2E | Existing stale-request guards in operations/security tests found; **not run here**. | Skipped mock E2E currently checks uploading text and a no-method response plus held older response. It does not assert parsing, loading, empty, generic error, actionable, blocked, stale, confirmation, RU coverage or a changed selection race; expand/split in implementation. | +| AC-13 | E2E + INT | Existing upload and no-mutation cases found; **not run here**. | Skipped E2E covers valid and empty only. It intercepts `/operations`, so it can detect a browser POST but provides no DB assertion; invalid, oversized, no-method outcomes and real DB state require additional API/Rust integration coverage. | +| AC-14 | Process | `just verify`, UI build/e2e targets and source tests found; **not run here**. | Meta-AC remains open until all mandatory API/Playwright scenarios execute on the implementation candidate and `just verify` + UI build pass. | + +## Red-phase leaf coverage note + +Это checklist фиксирует наличие исходного кода тестов отдельно от факта их исполнения. На baseline выполнен один RED: AC-7 дошёл до первого обещанного UI-предиката и упал из-за отсутствующего partial toggle. Остальные пропуски — подготовленные сценарии, не RED; перечисленные существующие tests не являются измеренным GREEN, поскольку здесь не запускались. AC-3 и AC-9 требуют новых/расширенных backend assertions; mock E2E не может закрыть контракт digest/persistence. + +## Red-phase E2E scaffolds + +File: `apps/ui/tests/e2e/openapi-preview-partial.spec.js` (AC-7 active; 8 leaves remain `test.skip` preparation). + +| Test leaf | AC | Expected failing behavior after activation | Baseline status | +|---|---|---|---| +| `[P1] AC-1 preview renders source locations and stable finding codes for candidates and conflicts` | AC-1 | API и UI ещё не отдают/не рендерят `source_location` и `conflicts`. | Skipped scaffold (prepared). | +| `[P1] AC-4 preview shows conflict type and deterministic rename proposal without mutating the snapshot` | AC-4 | Нет conflict type и deterministic rename proposal в preview/UI. | Skipped scaffold. | +| `[P1] AC-6 full mode disables Apply and lists blocker count and affected candidates` | AC-6 | UI не показывает полный blocker count/affected candidates как authority (backend GREEN). | Skipped scaffold. | +| `[P1] AC-7 explicit partial mode submits only the actionable closed subset and shows excluded reasons` | AC-7 | `#openapi-import-partial-mode` отсутствует в DOM. | **Executed RED**: UI E2E on baseline, 2026-10-03; first criterion assertion failed (`toBeVisible`, no element). Later mocked assertions were not reached and do not prove dependency closure/persistence. | +| `[P1] AC-8 confirming a changed selection creates a new plan version with a new digest` | AC-8 | UI не показывает version/digest нового плана. | Skipped scaffold. | +| `[P1] AC-10 reopening a stored plan reports stale/revalidation-required without implying Apply succeeds` | AC-10 | Нет read-only reopen/revalidation и stale-состояния. | Skipped scaffold. | +| `[P1] AC-11 renders bounded pages for 2000 candidates and preserves selection across pages` | AC-11 | UI рендерит все строки; нет pagination/virtualization и cap 2000. | Skipped scaffold. | +| `[P1] AC-12 renders uploading/parsing/loading/empty/error/stale states and drops a stale preview response` | AC-12 | Нет полного набора UI states; current leaf omits several named states/locales and selection replacement. | Skipped and incomplete contract mock; expand before relying on it. | +| `[P1] AC-13 real upload round-trip gives exact pre-mutation outcomes and creates no Operations before Apply` | AC-13 | Нет полного upload corpus/DB assertion. | Skipped and incomplete: only valid+empty; operation route is mocked, so no DB claim. | + +Leaf bodies опираются на существующие селекторы (`#openapi-import-*`, `.openapi-import-operation`, `[data-openapi-operation]`, `[data-testid="openapi-import-apply-confirmation"]`) и на предлагаемые контракты ниже. Backend endpoints/payload grounded in `apps/admin-api/src/dto.rs`, `routes/imports.rs`, `app.rs`; preview shape grounded in `crates/crank-import/src/rest/model.rs`. + +## Proposed DOM / accessibility contract (for implementation stage) + +- `#openapi-import-partial-mode` — явный checkbox/label «Partial import» / «Частичный импорт». +- `[data-testid="openapi-import-blockers"]` — полный blocker count и affected candidate keys. +- `[data-testid="openapi-import-operation-location"]`, `[data-testid="openapi-import-finding-code"]`, `[data-testid="openapi-import-finding-location"]` — source locations и stable codes. +- `[data-testid="openapi-import-conflict"]`, `[data-testid="openapi-import-rename-proposal"]` — conflict type и deterministic proposal (editable input). +- `[data-testid="openapi-import-excluded-reason"]` — причины `not_selected`/blocked. +- `[data-testid="openapi-import-pagination"]`, `[data-testid="openapi-import-page-status"]` — bounded pages и общее число кандидатов. +- `[data-testid="openapi-import-plan-stale"]`, `[data-testid="openapi-import-plan-version"]`, `[data-testid="openapi-import-plan-reopen"]` — stale/revalidation, digest version и read-only переоткрытие плана. +- Сохранить keyboard/focus и `role=status`/`aria-live=polite`; секреты/raw credentials не попадают в DOM, storage, plans, logs. + +## Proposed API contract deltas (implementation stage) + +- Preview response: `ImportPreview.conflicts[] = {operation_key, conflict_type, proposed_name, source_location}`; per-candidate `source_location`; per-finding `source_location` (+ existing `code`). Backward replay compatibility для persisted v2/v4/v5 previews сохранить. +- Existing `crank_import::rest::SourceLocation` is `{ pointer }` (RFC 6901) by design; do not add `source_digest` to the location object. Source snapshot digests belong to plan metadata. +- ImportPlan payload/fingerprint: убрать random `plan_reference` из digest-материала; добавить `catalog_revision`, `support_matrix_version`, `findings`. Digest должен быть стабилен при иных request IDs/timestamps. +- Read-only reopen/revalidation endpoint для plan: возвращает stale/revalidation-required без мутаций. +- 2000 bound: не повышать unbounded DOM; cap 512 для plan keys пересмотреть согласованно с AC (2000 display) — архитектурное решение ведущего. + +## Implementation checklist (для следующего stage, не выполнено здесь) + +- [ ] `crates/crank-import`: добавить `source_location` в finding/candidate projection и `conflicts[]`, не теряя current ordering/coverage; добавить Rust tests. +- [ ] `apps/admin-api`: детерминированный semantic digest (без random plan_reference/time/request ID); `catalog_revision`, `support_matrix_version`, `findings` в plan payload; read-only reopen/revalidation; naming conflict/rename proposal projection. +- [ ] `apps/ui/openapi-import.js` + `index.html` + `i18n.js` + css: явный partial control, locations/conflicts, blocker summary, bounded pagination (2000), stale revalidation, RU/EN, keyboard/live status. +- [ ] `apps/ui/tests/e2e/openapi-preview-partial.spec.js`: активировать по одному листу, подтвердить RED, реализовать, GREEN. +- [ ] `cargo test -p crank-import`; `cargo test -p admin-api --test integration`; `cargo test -p crank-registry --test integration`; `cd apps/ui && npm run build`; обязательные Playwright suites `--workers=1`; `just verify`. +- [ ] Reproducible benchmark 2000 candidates: bounded DOM, p95 ≤2 s на Reference Deployment, raw samples и environment записаны; поддельные mock-латентности не выдаются за proof. + +## Test execution evidence (this ATDD stage) + +- `cd apps/ui && npm ci` — **PASS**; использован lockfile, tracked package files не менялись. +- `node --check apps/ui/tests/e2e/openapi-preview-partial.spec.js` — результат ниже после activation. +- `cd apps/ui && npx playwright test tests/e2e/openapi-preview-partial.spec.js --grep 'AC-7' --workers=1` — **EXPECTED RED (EXIT=1)** на baseline `d1ba0bd…`: реальный Chromium/webServer стартовал, после upload/preview первый AC-предикат `#openapi-import-partial-mode` упал `element(s) not found`; это отсутствующий feature, не setup failure. Штатная сборка/migration завершилась, PostgreSQL 16 поднят тестовым stack script и им же остановлен при завершении. +- Полный Playwright discovery и остальные Rust reuse suites в этом ATDD stage не запускались. Следовательно, **0 existing GREEN переизмерено**; исходный код тестов ниже — candidates for reuse, не pass evidence. Reference Deployment p95 benchmark не запускался: local browser/application share one machine и не составляют требуемый LAN setup. +- Execution summary: 9 E2E leaves: 1 active executed RED (AC-7), 8 skipped preparation, 0 new GREEN; `generatedTestFiles` содержит один E2E файл. + +## Red-Green-Refactor workflow + +- **RED:** AC-7 выполнен против baseline и подтвердил отсутствие явного partial control. Остальные 8 `test.skip` — подготовка, а не executed RED. +- **GREEN:** реализовать минимальный production-код из Tasks спецификации; включить существующие Rust оракулы; прогонять suite по одному листу. +- **REFACTOR:** после зелёного — quality pass без изменения поведения; повторный прогон `just verify` + UI build. + +## Knowledge fragments applied + +- `test-quality.md`, `component-tdd.md`: один primary leaf на AC, скалярный first-failure, Given-When-Then. +- `data-factories.md`: reused deterministic helpers (`importDocument`, `candidate`, `previewResponse`, `planResponse`) вместо хардкода секретов; секретные canary не добавлялись. +- `network-first.md`, `timing-debugging.md`: route mocking до навигации, deterministic request settlement barrier вместо `waitForTimeout`. +- `selector-resilience.md`: доступные имена и стабильные `data-testid`. +- `fixture-architecture.md`, `test-healing-patterns.md`: reuse существующего `login` helper; без лишних fixture-абстракций. +- Playwright Utils / Pact.js mandates: N/A (пакеты отсутствуют; contract boundary отсутствует). + +## Handoff + +ATDD-only выход готов к отдельному implementation stage. Один реальный RED: AC-7 отсутствует partial toggle. UI mocks дают лишь interaction contracts; AC-7 closure/report, AC-8 digest/version, AC-10 reopen/revalidation, AC-12 полный state/locale/request-generation набор, AC-13 oversized/no-method/DB assertions и AC-11 performance остаются незакрытыми. AC-2/3/5/9 source suites не запускались и не объявляются GREEN; AC-3/9 требуют отдельного proof по semantic digest и stored metadata. `sprint-status.yaml` не изменён. + +## Implementation-stage evidence (2026-10-03; separate from historical RED snapshot) + +Все девять подготовленных E2E leaves AC-1/4/6/7/8/10/11/12/13 активированы; в `openapi-preview-partial.spec.js` больше нет `test.skip`. AC-1/4 проверяют UI projection с mock response и соответствующий Rust/API typed contract; AC-8/10 проверяют UI GET/selection flow, а хранение и server authority подтверждаются отдельными integration tests. AC-13 browser leaf обращается к реальному preview API и сравнивает operations GET до/после; прямые SQL-счётчики для пяти upload-исходов проверяет `preview_outcomes_do_not_mutate_operation_catalog`. + +| AC | Executed implementation evidence | Ограничение | +|---|---|---| +| 1–5 | `crank-import` preview/source corpus, API naming/readiness и registry semantic digest tests; v5 persisted replay regression | Group/count/summary получают provenance через membership candidates, не вымышленный singular pointer/code. | +| 6–7 | Active UI leaves; API partial blocker/selection tests; registry material/Apply checks сохраняют excluded reasons | UI mock не заменяет registry closure authority. | +| 8–10 | Active UI leaves; v2 payload/digest, catalog/Auth drift и read-only GET integration; старый план остаётся readable | UI version — номер обзора в modal; неизменяемый server reference/digest — authority. | +| 11 | Active UI leaf: 2 000 candidates, preview/plan/result rows ≤100, 20 raw local browser handler samples; real API 2 000 YAML → full plan → GET current, SQL no-mutation | Reference Deployment LAN full interaction p95 **не измерен**; отдельный operator-run harness `openapi-preview-reference.spec.js` ожидает удалённую инфраструктуру и manifest. | +| 12–13 | Active RU/EN states/race/real upload leaves; typed invalid/empty/oversized/no-method SQL regression | Локальный Playwright stack не является Reference Deployment. | +| 14 | Обязательные Rust/UI проверки ниже, `just verify` и обязательный review выполняет ведущий после handoff | Gate не считается закрытым до фактического PASS. | + +Измеренные команды к моменту handoff: `cargo test -p crank-import` — PASS, 0 ignored; `cargo test -p admin-api --test integration import_plan_create -- --test-threads=1` — 17 PASS; адресные `preview_outcomes_do_not_mutate_operation_catalog`, `previews_and_plans_two_thousand_operations_without_catalog_mutation`, `older_v2_support_matrix_rejects_new_apply_but_keeps_plan_auditable`, `http_contract_preview_apply_and_replay_preserve_json_multipart_schemas_mapping_and_mime` — по 1 PASS; `cargo test -p admin-api --lib preview_name_tests` — 1 PASS; `cargo test -p crank-registry --test integration -- --test-threads=1` — 139 PASS, 1 ранее существовавший unrelated ignored; `just clippy` — PASS. Первый полный API run выявил устаревшее буквальное сравнение persisted projection с workspace-aware response status (122 tests: 121 PASS, 1 FAIL); адресный regression после точечного исправления PASS. Финальный полный API/`just verify` gate ещё нужен. + +`cd apps/ui && npx playwright test tests/e2e/openapi-preview-partial.spec.js tests/e2e/openapi-import-plan.spec.js tests/e2e/openapi-security-mapping.spec.js tests/e2e/operations.spec.js --workers=1` — **40 PASS, 0 skipped** на final production UI; после этого добавлен только keyboard assertion в AC-12, адресный rerun выполняется перед handoff, а полный final gate повторит ведущий. Локальные raw AC-11 samples и воспроизводимый Reference command/manifest находятся в `docs/openapi-import.md`; mock handler timings не используются как LAN p95 proof. diff --git a/apps/admin-api/src/app.rs b/apps/admin-api/src/app.rs index 95b1324..47d737e 100644 --- a/apps/admin-api/src/app.rs +++ b/apps/admin-api/src/app.rs @@ -29,7 +29,7 @@ use crate::{ capabilities::get_capabilities, imports::{ apply_openapi_import_plan, create_openapi_import, create_openapi_import_plan, - preview_openapi_import, + preview_openapi_import, revalidate_openapi_import_plan, }, observability::{ approve_approval, deny_approval, export_logs_csv, export_usage_csv, get_agent_usage, @@ -65,6 +65,10 @@ pub fn build_app(state: AppState) -> Router { "/imports/openapi/{job_id}/plans", post(create_openapi_import_plan), ) + .route( + "/imports/openapi/plans/{plan_id}", + get(revalidate_openapi_import_plan), + ) .route( "/imports/openapi/{plan_id}/apply", post(apply_openapi_import_plan).layer(DefaultBodyLimit::max(16 * 1024)), diff --git a/apps/admin-api/src/dto.rs b/apps/admin-api/src/dto.rs index e9582e7..828f69c 100644 --- a/apps/admin-api/src/dto.rs +++ b/apps/admin-api/src/dto.rs @@ -656,12 +656,25 @@ pub struct OpenApiImportPlanCandidateView { pub struct OpenApiImportPlanCreateResponse { pub plan_reference: String, pub plan_digest: String, + pub catalog_revision: String, + pub support_matrix_version: String, pub expires_at: String, pub selection_mode: String, pub counts: OpenApiImportPlanCounts, pub candidates: Vec, } +#[derive(Clone, Debug, Serialize)] +pub struct OpenApiImportPlanRevalidationResponse { + pub plan_reference: String, + pub plan_digest: String, + pub revalidation_status: String, + pub revalidation_required: bool, + pub reason: Option, + pub counts: OpenApiImportPlanCounts, + pub candidates: Vec, +} + #[derive(Clone, Debug, Serialize)] pub struct CreatedOperationResponse { pub operation_id: String, diff --git a/apps/admin-api/src/routes/imports.rs b/apps/admin-api/src/routes/imports.rs index 5b39c45..31b6867 100644 --- a/apps/admin-api/src/routes/imports.rs +++ b/apps/admin-api/src/routes/imports.rs @@ -223,6 +223,20 @@ pub async fn create_openapi_import_plan( Ok(Json(json!(plan))) } +pub async fn revalidate_openapi_import_plan( + Path(path): Path, + State(state): State, +) -> Result, ApiError> { + let plan = state + .service + .revalidate_openapi_import_plan( + &path.workspace_id.as_str().into(), + &path.plan_id.as_str().into(), + ) + .await?; + Ok(Json(json!(plan))) +} + pub async fn apply_openapi_import_plan( Path(path): Path, State(state): State, diff --git a/apps/admin-api/src/service/imports.rs b/apps/admin-api/src/service/imports.rs index ba0f19b..aabe067 100644 --- a/apps/admin-api/src/service/imports.rs +++ b/apps/admin-api/src/service/imports.rs @@ -6,8 +6,9 @@ use crank_core::{ SecretStatus, ToolQualityFinding, ToolQualitySeverity, WorkspaceId, }; use crank_import::rest::{ - ImportFinding, ImportFindingSeverity, ImportOperationCandidate, NORMALIZER_VERSION, - PROJECTION_VERSION, operation_draft_from_candidate, validate_document_source_safe, + ImportFinding, ImportFindingSeverity, ImportNameConflict, ImportOperationCandidate, + NORMALIZER_VERSION, PROJECTION_VERSION, operation_draft_from_candidate, + validate_document_source_safe, }; use crank_registry::{ ApplyImportJobRequest, ArtifactSourceId, ArtifactSourceSensitivity, @@ -27,7 +28,8 @@ use crate::{ AdminService, OpenApiImportAuthProfileChoice, OpenApiImportCreatePayload, OpenApiImportCreateResponse, OpenApiImportCreatedOperation, OpenApiImportPlanApplyPayload, OpenApiImportPlanCandidateView, OpenApiImportPlanCounts, OpenApiImportPlanCreatePayload, - OpenApiImportPlanCreateResponse, OpenApiImportPlanDecision, OpenApiImportPreviewResponse, + OpenApiImportPlanCreateResponse, OpenApiImportPlanDecision, + OpenApiImportPlanRevalidationResponse, OpenApiImportPreviewResponse, OpenApiImportSecurityProfileChoice, OpenApiImportSkippedOperation, OpenApiUpload, OpenApiUploadLocale, OperationPayload, new_prefixed_id, }, @@ -52,7 +54,8 @@ use verified_preview::{ const IMPORT_JOB_TTL_HOURS: i64 = 24; const OPENAPI_PARSE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(30); const OPENAPI_PARSE_CONCURRENCY: usize = 4; -const MAX_IMPORT_PLAN_KEYS: usize = 512; +const MAX_IMPORT_PLAN_KEYS: usize = 2_000; +const OPENAPI_SUPPORT_MATRIX_VERSION: &str = "1.0.2"; const MAX_IMPORT_PLAN_KEY_BYTES: usize = 4_096; const MAX_IMPORT_PLAN_SERVER_URL_BYTES: usize = 8_192; const MAX_IMPORT_PLAN_NAME_BYTES: usize = 256; @@ -60,6 +63,132 @@ const MAX_IMPORT_PLAN_ID_REF_BYTES: usize = 128; static OPENAPI_PARSE_SLOTS: tokio::sync::Semaphore = tokio::sync::Semaphore::const_new(OPENAPI_PARSE_CONCURRENCY); +fn preview_name_conflicts( + preview: &crank_import::rest::ImportPreview, + catalog_names: &[String], +) -> Vec { + let operations = preview + .groups + .iter() + .flat_map(|group| group.operations.iter()) + .collect::>(); + let mut operation_ids = BTreeMap::<&str, usize>::new(); + for candidate in &operations { + if let Some(id) = candidate.operation_id.as_deref() { + *operation_ids.entry(id).or_default() += 1; + } + } + let occupied = catalog_names + .iter() + .map(String::as_str) + .collect::>(); + let mut proposals = catalog_names.iter().cloned().collect::>(); + proposals.extend( + operations + .iter() + .map(|candidate| candidate.suggested_name.clone()), + ); + let mut conflicts = Vec::new(); + for candidate in operations { + let duplicate = candidate + .operation_id + .as_deref() + .is_some_and(|id| operation_ids.get(id).is_some_and(|count| *count > 1)); + let invalid = candidate.operation_id.as_deref().is_some_and(|id| { + id.is_empty() + || id.len() > MAX_IMPORT_PLAN_NAME_BYTES + || !id.bytes().enumerate().all(|(index, ch)| { + ch.is_ascii_alphabetic() || ch == b'_' || (index > 0 && ch.is_ascii_digit()) + }) + }); + let taken = occupied.contains(candidate.suggested_name.as_str()); + if !duplicate && !invalid && !taken { + continue; + } + let base = candidate + .suggested_name + .chars() + .take(240) + .collect::(); + let proposal = next_available_name(&base, &mut proposals); + for conflict_type in [ + duplicate.then_some("duplicate_name"), + invalid.then_some("invalid_name"), + taken.then_some("taken_name"), + ] + .into_iter() + .flatten() + { + conflicts.push(ImportNameConflict { + operation_key: candidate.key.clone(), + conflict_type: conflict_type.to_owned(), + proposed_name: proposal.clone(), + source_location: candidate.source_location.as_ref().map(|location| { + crank_import::rest::SourceLocation { + pointer: if candidate.operation_id.is_some() { + format!("{}/operationId", location.pointer) + } else { + location.pointer.clone() + }, + } + }), + }); + } + } + conflicts +} + +fn next_available_name(base: &str, occupied: &mut BTreeSet) -> String { + // A catalog may contain more names than the preview candidate cap. With + // occupied.len() + 1 suffixes, at least one candidate must be free. + (2..=occupied.len() + 2) + .map(|index| format!("{base}_{index}")) + .find(|name| occupied.insert(name.clone())) + .expect("finite occupied names always leave a free suffix") +} + +fn attach_preview_readiness( + preview: &mut crank_import::rest::ImportPreview, + choices: &[OpenApiImportSecurityProfileChoice], +) { + let document_blocked = preview.findings.iter().any(|finding| { + finding.severity == ImportFindingSeverity::Error && finding.operation_key.is_none() + }); + for candidate in preview + .groups + .iter_mut() + .flat_map(|group| group.operations.iter_mut()) + { + let blocked = document_blocked + || candidate + .findings + .iter() + .any(|finding| finding.severity == ImportFindingSeverity::Error); + let alternatives = &candidate.security_requirements.alternatives; + let public = alternatives.is_empty() + || alternatives + .iter() + .any(|alternative| alternative.supported && alternative.schemes.is_empty()); + candidate.status = if blocked { + "blocked" + } else if public { + "actionable" + } else if alternatives.iter().enumerate().any(|(index, alternative)| { + alternative.supported + && choices.iter().any(|choice| { + choice.operation_key == candidate.key + && choice.alternative_index == index + && !choice.profiles.is_empty() + }) + }) { + "unresolved" + } else { + "blocked" + } + .to_owned(); + } +} + impl AdminService { #[instrument(skip(self, upload), fields(workspace_id = %workspace_id.as_str()))] pub async fn preview_openapi_import( @@ -186,6 +315,20 @@ impl AdminService { detach_guard.detach_now().await; return Err(ApiError::openapi_upload(locale, "no_methods")); } + let candidate_count: usize = parsed + .preview + .groups + .iter() + .map(|group| group.operations.len()) + .sum(); + if candidate_count > MAX_IMPORT_PLAN_KEYS { + dependencies.detach_all().await; + detach_guard.detach_now().await; + return Err(ApiError::validation_with_context( + "OpenAPI preview has too many candidates", + json!({ "error_code": "openapi_preview_too_many_candidates", "limit": MAX_IMPORT_PLAN_KEYS }), + )); + } let source_envelope = ImportJobSourceEnvelope { source_id, digest: artifact.artifact_ref().clone(), @@ -236,12 +379,19 @@ impl AdminService { let security_profile_choices = self .security_profile_choices(workspace_id, &parsed.preview) .await?; + let catalog_names = self + .registry + .list_import_catalog_names(workspace_id) + .await?; + let mut response_preview = parsed.preview; + response_preview.conflicts = preview_name_conflicts(&response_preview, &catalog_names); + attach_preview_readiness(&mut response_preview, &security_profile_choices); Ok(OpenApiImportPreviewResponse { job_id: job_id.as_str().to_owned(), expires_at: expires_at .format(&Rfc3339) .map_err(|error| ApiError::internal(error.to_string()))?, - preview: parsed.preview, + preview: response_preview, security_profile_choices, }) } @@ -542,6 +692,7 @@ fn openapi_import_response(applied: ImportJobApplyResult) -> OpenApiImportCreate operation.name ), operation_key: Some(operation.operation_key.clone()), + source_location: None, }) }) .collect::>(); @@ -560,6 +711,7 @@ fn openapi_import_response(applied: ImportJobApplyResult) -> OpenApiImportCreate format!("Операция {name} уже существует и была пропущена.") }, operation_key: Some(operation.operation_key.clone()), + source_location: None, }); OpenApiImportSkippedOperation { operation_key: operation.operation_key.clone(), @@ -658,3 +810,20 @@ fn tool_quality_finding_from_import(finding: &ImportFinding) -> ToolQualityFindi field_path: finding.operation_key.clone(), } } + +#[cfg(test)] +mod preview_name_tests { + use super::next_available_name; + use std::collections::BTreeSet; + + #[test] + fn crowded_catalog_still_gets_a_free_deterministic_proposal() { + let mut occupied = (2..=2_002) + .map(|index| format!("shared_{index}")) + .collect::>(); + occupied.insert("shared".to_owned()); + + assert_eq!(next_available_name("shared", &mut occupied), "shared_2003"); + assert_eq!(next_available_name("shared", &mut occupied), "shared_2004"); + } +} diff --git a/apps/admin-api/src/service/imports/import_plan.rs b/apps/admin-api/src/service/imports/import_plan.rs index a596174..ed23e74 100644 --- a/apps/admin-api/src/service/imports/import_plan.rs +++ b/apps/admin-api/src/service/imports/import_plan.rs @@ -1,3 +1,5 @@ +mod validation; + use super::*; use crank_core::AuthConfig; use crank_import::rest::SecurityRequirementsSource as SecuritySource; @@ -61,6 +63,7 @@ impl AdminService { ImportPreviewResolution::NonFatal(error) => error, })?; let preview = &resolved.preview; + let catalog_revision = self.registry.import_catalog_revision(workspace_id).await?; // Stored external dependency snapshots are re-verified for every // replay variant (including historically persisted ones) without a @@ -81,6 +84,12 @@ impl AdminService { .map(|operation| (operation.key.clone(), operation)) .collect(); let all_set: BTreeSet = candidates.keys().cloned().collect(); + if all_set.len() > MAX_IMPORT_PLAN_KEYS { + return Err(ApiError::validation_with_context( + "too many candidates for an import plan", + json!({ "error_code": "import_plan_invalid_input" }), + )); + } let selected = resolve_plan_selection( &payload.selection_mode, &payload.selected_operation_keys, @@ -100,7 +109,31 @@ impl AdminService { .filter(|key| !selected.contains(*key)) .cloned() .collect(); - let decisions = validate_plan_decisions(&payload.decisions, &selected)?; + let excluded_reasons = excluded + .iter() + .map(|key| { + let reason = preview + .findings + .iter() + .find(|finding| { + finding.severity == ImportFindingSeverity::Error + && finding.operation_key.is_none() + }) + .map(|finding| finding.code.clone()) + .or_else(|| { + candidates.get(key).and_then(|candidate| { + candidate + .findings + .iter() + .find(|finding| finding.severity == ImportFindingSeverity::Error) + .map(|finding| finding.code.clone()) + }) + }) + .unwrap_or_else(|| "not_selected".to_owned()); + (key.clone(), reason) + }) + .collect::>(); + let decisions = validation::validate_plan_decisions(&payload.decisions, &selected)?; let global_blocker = preview .findings @@ -144,6 +177,15 @@ impl AdminService { .count(), blocked: planned.iter().filter(|candidate| candidate.blocked).count(), }; + if payload.selection_mode == "partial" && counts.blocked != 0 { + return Err(ApiError::validation_with_context( + "partial selection includes blocked candidates", + json!({ "error_code": "import_plan_partial_blocked" }), + )); + } + if self.registry.import_catalog_revision(workspace_id).await? != catalog_revision { + return Err(import_plan_repreview_error("import_plan_catalog_stale")); + } // Server-authored immutable plan. Client-supplied candidate material, // digests or payload fields are not read: every value below derives @@ -157,7 +199,7 @@ impl AdminService { }); let plan_reference = new_prefixed_id("plan"); let plan_payload = json!({ - "schema_version": "import-plan-v1", + "schema_version": "import-plan-v2", "plan_reference": plan_reference, "job_id": job_id.as_str(), "server_url": payload.server_url, @@ -167,12 +209,25 @@ impl AdminService { }, "dependencies": job.preview_payload.get("dependencies").cloned().unwrap_or(json!([])), "fingerprint": resolved.fingerprint, + "catalog_revision": catalog_revision, + "support_matrix_version": OPENAPI_SUPPORT_MATRIX_VERSION, + "findings": { + "document": preview.findings, + "candidates": candidates.iter().map(|(key, candidate)| json!({ + "key": key, + "findings": candidate.findings, + })).collect::>(), + }, "selection": { "mode": payload.selection_mode, "all": all_keys, "selected": selected_keys, "excluded": excluded, }, + "excluded_reasons": excluded_reasons.iter().map(|(key, reason)| json!({ + "key": key, + "reason": reason, + })).collect::>(), "counts": plan_counts_value, "candidates": planned.iter().map(plan_candidate_payload).collect::, _>>()?, }); @@ -224,13 +279,15 @@ impl AdminService { confirmed_name: None, auth_profile_id: None, security_alternative_index: None, - reason: Some("not_selected".to_owned()), + reason: excluded_reasons.get(key).cloned(), } })); Ok(OpenApiImportPlanCreateResponse { plan_reference: created.id.as_str().to_owned(), plan_digest: created.digest, + catalog_revision, + support_matrix_version: OPENAPI_SUPPORT_MATRIX_VERSION.to_owned(), expires_at: created .expires_at .format(&Rfc3339) @@ -703,133 +760,6 @@ fn resolve_plan_selection( } } -/// Binds decisions to selected candidates with action-specific field rules: -/// unknown/duplicate keys, foreign fields and oversized references are -/// rejected before the plan is materialized. -fn validate_plan_decisions<'input>( - decisions: &'input [OpenApiImportPlanDecision], - selected: &BTreeSet, -) -> Result, ApiError> { - let invalid = |context: Value| { - Err(ApiError::validation_with_context( - "import plan decision is invalid", - context, - )) - }; - let mut mapping = BTreeMap::new(); - for decision in decisions { - if decision.operation_key.is_empty() - || decision.operation_key.len() > MAX_IMPORT_PLAN_KEY_BYTES - { - return invalid(json!({ - "operation_key": decision.operation_key, - "error_code": "import_plan_invalid_input" - })); - } - if !matches!( - decision.action.as_str(), - "create" | "skip" | "rename" | "new_version" - ) { - return invalid(json!({ - "operation_key": decision.operation_key, - "error_code": "import_plan_invalid_input" - })); - } - validate_decision_fields(decision)?; - if !selected.contains(&decision.operation_key) { - return invalid(json!({ - "operation_key": decision.operation_key, - "error_code": "import_plan_decision_unselected" - })); - } - if mapping - .insert(decision.operation_key.clone(), decision) - .is_some() - { - return invalid(json!({ - "operation_key": decision.operation_key, - "error_code": "import_plan_invalid_input" - })); - } - } - Ok(mapping) -} - -fn validate_decision_fields(decision: &OpenApiImportPlanDecision) -> Result<(), ApiError> { - let context = json!({ - "operation_key": decision.operation_key, - "error_code": "import_plan_invalid_input" - }); - let invalid = |message: &str| -> Result<(), ApiError> { - Err(ApiError::validation_with_context(message, context.clone())) - }; - if decision - .target_operation_id - .as_deref() - .is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_ID_REF_BYTES) - { - return invalid("decision target_operation_id is empty or too long"); - } - if decision - .confirmed_name - .as_deref() - .is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_NAME_BYTES) - { - return invalid("decision confirmed_name is empty or too long"); - } - if decision - .auth_profile_id - .as_deref() - .is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_ID_REF_BYTES) - { - return invalid("decision auth_profile_id is empty or too long"); - } - if decision - .security_alternative_index - .is_some_and(|index| index > MAX_IMPORT_PLAN_KEYS) - { - return invalid("decision security_alternative_index is too large"); - } - match decision.action.as_str() { - "create" => { - if decision.target_operation_id.is_some() || decision.confirmed_name.is_some() { - return invalid( - "target_operation_id and confirmed_name are not allowed for action create", - ); - } - } - "skip" => { - if decision.auth_profile_id.is_some() || decision.security_alternative_index.is_some() { - return invalid("security binding is not allowed for action skip"); - } - if decision.target_operation_id.is_none() { - return invalid("action skip requires the exact target_operation_id"); - } - if decision.confirmed_name.is_some() { - return invalid("confirmed_name is not allowed for action skip"); - } - } - "rename" => { - if decision.target_operation_id.is_some() { - return invalid("target_operation_id is not allowed for action rename"); - } - if decision.confirmed_name.is_none() { - return invalid("action rename requires the exact confirmed_name"); - } - } - "new_version" => { - if decision.target_operation_id.is_none() { - return invalid("action new_version requires the exact target_operation_id"); - } - if decision.confirmed_name.is_some() { - return invalid("confirmed_name is not allowed for action new_version"); - } - } - _ => unreachable!("decision action is validated before the field rules"), - } - Ok(()) -} - async fn resolve_security_binding( service: &AdminService, workspace_id: &WorkspaceId, diff --git a/apps/admin-api/src/service/imports/import_plan/validation.rs b/apps/admin-api/src/service/imports/import_plan/validation.rs new file mode 100644 index 0000000..0c6ae53 --- /dev/null +++ b/apps/admin-api/src/service/imports/import_plan/validation.rs @@ -0,0 +1,128 @@ +use super::*; + +/// Binds decisions to selected candidates with action-specific field rules: +/// unknown/duplicate keys, foreign fields and oversized references are +/// rejected before the plan is materialized. +pub(super) fn validate_plan_decisions<'input>( + decisions: &'input [OpenApiImportPlanDecision], + selected: &BTreeSet, +) -> Result, ApiError> { + let invalid = |context: Value| { + Err(ApiError::validation_with_context( + "import plan decision is invalid", + context, + )) + }; + let mut mapping = BTreeMap::new(); + for decision in decisions { + if decision.operation_key.is_empty() + || decision.operation_key.len() > MAX_IMPORT_PLAN_KEY_BYTES + { + return invalid(json!({ + "operation_key": decision.operation_key, + "error_code": "import_plan_invalid_input" + })); + } + if !matches!( + decision.action.as_str(), + "create" | "skip" | "rename" | "new_version" + ) { + return invalid(json!({ + "operation_key": decision.operation_key, + "error_code": "import_plan_invalid_input" + })); + } + validate_decision_fields(decision)?; + if !selected.contains(&decision.operation_key) { + return invalid(json!({ + "operation_key": decision.operation_key, + "error_code": "import_plan_decision_unselected" + })); + } + if mapping + .insert(decision.operation_key.clone(), decision) + .is_some() + { + return invalid(json!({ + "operation_key": decision.operation_key, + "error_code": "import_plan_invalid_input" + })); + } + } + Ok(mapping) +} + +fn validate_decision_fields(decision: &OpenApiImportPlanDecision) -> Result<(), ApiError> { + let context = json!({ + "operation_key": decision.operation_key, + "error_code": "import_plan_invalid_input" + }); + let invalid = |message: &str| -> Result<(), ApiError> { + Err(ApiError::validation_with_context(message, context.clone())) + }; + if decision + .target_operation_id + .as_deref() + .is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_ID_REF_BYTES) + { + return invalid("decision target_operation_id is empty or too long"); + } + if decision + .confirmed_name + .as_deref() + .is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_NAME_BYTES) + { + return invalid("decision confirmed_name is empty or too long"); + } + if decision + .auth_profile_id + .as_deref() + .is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_ID_REF_BYTES) + { + return invalid("decision auth_profile_id is empty or too long"); + } + if decision + .security_alternative_index + .is_some_and(|index| index > MAX_IMPORT_PLAN_KEYS) + { + return invalid("decision security_alternative_index is too large"); + } + match decision.action.as_str() { + "create" => { + if decision.target_operation_id.is_some() || decision.confirmed_name.is_some() { + return invalid( + "target_operation_id and confirmed_name are not allowed for action create", + ); + } + } + "skip" => { + if decision.auth_profile_id.is_some() || decision.security_alternative_index.is_some() { + return invalid("security binding is not allowed for action skip"); + } + if decision.target_operation_id.is_none() { + return invalid("action skip requires the exact target_operation_id"); + } + if decision.confirmed_name.is_some() { + return invalid("confirmed_name is not allowed for action skip"); + } + } + "rename" => { + if decision.target_operation_id.is_some() { + return invalid("target_operation_id is not allowed for action rename"); + } + if decision.confirmed_name.is_none() { + return invalid("action rename requires the exact confirmed_name"); + } + } + "new_version" => { + if decision.target_operation_id.is_none() { + return invalid("action new_version requires the exact target_operation_id"); + } + if decision.confirmed_name.is_some() { + return invalid("confirmed_name is not allowed for action new_version"); + } + } + _ => unreachable!("decision action is validated before the field rules"), + } + Ok(()) +} diff --git a/apps/admin-api/src/service/imports/plan_apply.rs b/apps/admin-api/src/service/imports/plan_apply.rs index fd486a2..cb95bd8 100644 --- a/apps/admin-api/src/service/imports/plan_apply.rs +++ b/apps/admin-api/src/service/imports/plan_apply.rs @@ -4,6 +4,160 @@ use crank_registry::{ApplyImportPlanRequest, ImportPlanApplyReport}; const MAX_IMPORT_PLAN_IDEMPOTENCY_KEY_BYTES: usize = 128; impl AdminService { + /// Reads an immutable plan and checks its current authority without Apply mutations. + pub async fn revalidate_openapi_import_plan( + &self, + workspace_id: &WorkspaceId, + plan_id: &ImportPlanId, + ) -> Result { + self.ensure_workspace_exists(workspace_id).await?; + let plan = self + .registry + .get_import_plan(workspace_id, plan_id) + .await? + .ok_or_else(|| { + ApiError::not_found_with_context( + "import plan was not found in this workspace", + json!({ "error_code": "import_plan_not_found" }), + ) + })?; + let mut reason = None; + let now = OffsetDateTime::now_utc(); + if plan.expires_at <= now { + reason = Some("import_plan_expired"); + } else if let Some(job) = self + .registry + .get_import_job(workspace_id, &plan.job_id) + .await? + { + if job.kind != ImportJobKind::OpenApi + || job.status != ImportJobStatus::Pending + || job.expires_at <= now + { + reason = Some("import_plan_job_terminal"); + } else { + match self + .resolve_verified_openapi_preview(workspace_id, &job, OpenApiUploadLocale::En) + .await + { + Ok(resolved) => { + let v2 = plan.payload.get("schema_version").and_then(Value::as_str) + == Some("import-plan-v2"); + if self + .read_import_job_dependencies( + workspace_id, + &job.preview_payload, + OpenApiUploadLocale::En, + ) + .await + .is_err() + { + reason = Some("import_dependency_verification_failed"); + } else if !v2 { + // Historical plans stay readable for audit, but lack the + // catalog evidence required for current Apply authority. + reason = Some("importer_version_changed"); + } else if resolved + .fingerprint + .get("normalizer_version") + .and_then(Value::as_str) + != Some(NORMALIZER_VERSION) + || resolved + .fingerprint + .get("projection_version") + .and_then(Value::as_str) + != Some(PROJECTION_VERSION) + || plan + .payload + .get("support_matrix_version") + .and_then(Value::as_str) + != Some(OPENAPI_SUPPORT_MATRIX_VERSION) + { + reason = Some("importer_version_changed"); + } else if self + .registry + .revalidate_import_plan(workspace_id, plan_id, &resolved.fingerprint) + .await + .is_err() + { + reason = Some("import_plan_revalidation_failed"); + } + } + Err(_) => reason = Some("import_preview_revalidation_failed"), + } + } + } else { + reason = Some("import_plan_job_unavailable"); + } + + let counts = &plan.payload["counts"]; + let count = |key: &str| { + counts + .get(key) + .and_then(Value::as_u64) + .and_then(|value| usize::try_from(value).ok()) + .unwrap_or(0) + }; + let selected = plan.payload["candidates"] + .as_array() + .into_iter() + .flatten() + .map(|candidate| { + let decision = &candidate["decision"]; + let string = |value: &Value| value.as_str().map(str::to_owned); + OpenApiImportPlanCandidateView { + key: string(&candidate["key"]).unwrap_or_default(), + name: string(&candidate["name"]).unwrap_or_default(), + state: string(&candidate["state"]).unwrap_or_default(), + action: string(&decision["action"]), + target_operation_id: string(&decision["target_operation_id"]), + confirmed_name: string(&decision["confirmed_name"]), + auth_profile_id: string(&decision["auth_profile_id"]), + security_alternative_index: decision["security_alternative_index"] + .as_u64() + .and_then(|value| usize::try_from(value).ok()), + reason: string(&candidate["reason"]), + } + }); + let excluded = plan + .payload + .pointer("/selection/excluded") + .and_then(Value::as_array) + .into_iter() + .flatten() + .filter_map(Value::as_str) + .map(|key| OpenApiImportPlanCandidateView { + key: key.to_owned(), + name: key.to_owned(), + state: "excluded".to_owned(), + action: None, + target_operation_id: None, + confirmed_name: None, + auth_profile_id: None, + security_alternative_index: None, + reason: plan.payload["excluded_reasons"] + .as_array() + .and_then(|items| items.iter().find(|item| item["key"].as_str() == Some(key))) + .and_then(|item| item["reason"].as_str()) + .map(str::to_owned) + .or_else(|| Some("not_selected".to_owned())), + }); + Ok(OpenApiImportPlanRevalidationResponse { + plan_reference: plan.id.as_str().to_owned(), + plan_digest: plan.digest, + revalidation_status: if reason.is_some() { "stale" } else { "current" }.to_owned(), + revalidation_required: reason.is_some(), + reason: reason.map(str::to_owned), + counts: OpenApiImportPlanCounts { + selected: count("selected"), + excluded: count("excluded"), + actionable: count("actionable"), + blocked: count("blocked"), + }, + candidates: selected.chain(excluded).collect(), + }) + } + #[instrument(skip(self, payload), fields(workspace_id = %workspace_id.as_str(), plan_id = %plan_id.as_str()))] pub async fn apply_openapi_import_plan( &self, @@ -85,6 +239,13 @@ impl AdminService { .get("projection_version") .and_then(Value::as_str) != Some(PROJECTION_VERSION) + || (plan.payload.get("schema_version").and_then(Value::as_str) + == Some("import-plan-v2") + && plan + .payload + .get("support_matrix_version") + .and_then(Value::as_str) + != Some(OPENAPI_SUPPORT_MATRIX_VERSION)) { return Err(import_plan_repreview_error("importer_version_changed")); } diff --git a/apps/admin-api/src/service/imports/verified_preview.rs b/apps/admin-api/src/service/imports/verified_preview.rs index c84b64d..d06cbb1 100644 --- a/apps/admin-api/src/service/imports/verified_preview.rs +++ b/apps/admin-api/src/service/imports/verified_preview.rs @@ -209,6 +209,7 @@ fn import_replay_contract( ("normalized-ir-v2", "preview-v2") | ("normalized-ir-v3", "preview-v3") | ("normalized-ir-v4", "preview-v4") + | ("normalized-ir-v5", "preview-v5") ) { return Err(ApiError::openapi_upload(locale, "source_integrity")); } diff --git a/apps/admin-api/tests/integration/openapi_import.rs b/apps/admin-api/tests/integration/openapi_import.rs index b70a440..e0c6213 100644 --- a/apps/admin-api/tests/integration/openapi_import.rs +++ b/apps/admin-api/tests/integration/openapi_import.rs @@ -13,6 +13,9 @@ mod external_references; mod http_contract; mod import_plan_apply; mod import_plan_create; +mod large_preview; +mod upload_outcomes; +mod v5_replay; #[tokio::test] #[serial] diff --git a/apps/admin-api/tests/integration/openapi_import/http_contract.rs b/apps/admin-api/tests/integration/openapi_import/http_contract.rs index e00cb66..1801f9f 100644 --- a/apps/admin-api/tests/integration/openapi_import/http_contract.rs +++ b/apps/admin-api/tests/integration/openapi_import/http_contract.rs @@ -26,10 +26,17 @@ async fn http_contract_preview_apply_and_replay_preserve_json_multipart_schemas_ .unwrap() .preview_payload["preview"] .clone(); - assert_eq!( - persisted_preview_before_apply, - serde_json::to_value(&preview.preview).unwrap() - ); + // Readiness is workspace-aware response metadata, not part of the immutable + // projection persisted with the source job. + let mut response_projection = serde_json::to_value(&preview.preview).unwrap(); + for group in response_projection["groups"].as_array_mut().unwrap() { + for operation in group["operations"].as_array_mut().unwrap() { + assert_eq!(operation["status"], "actionable"); + operation.as_object_mut().unwrap().remove("status"); + } + } + assert!(preview.preview.conflicts.is_empty()); + assert_eq!(persisted_preview_before_apply, response_projection); let operations = preview .preview diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_apply.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_apply.rs index d4aeaea..c8b2ae5 100644 --- a/apps/admin-api/tests/integration/openapi_import/import_plan_apply.rs +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_apply.rs @@ -987,3 +987,4 @@ async fn ac_4_corpus_operation_completes_the_real_http_to_mcp_workflow() { mod corpus_hostile; mod security_source; +mod support_matrix; diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_apply/support_matrix.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_apply/support_matrix.rs new file mode 100644 index 0000000..309042c --- /dev/null +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_apply/support_matrix.rs @@ -0,0 +1,106 @@ +use super::*; + +use admin_api::error::ApiError; +use admin_api::service::{ + OpenApiImportPlanApplyPayload, OpenApiImportPlanCreatePayload, OpenApiUpload, + OpenApiUploadLocale, +}; +use crank_core::WorkspaceId; +use crank_registry::{CreateImportPlanRequest, ImportPlanId}; + +#[tokio::test] +#[serial] +async fn older_v2_support_matrix_rejects_new_apply_but_keeps_plan_auditable() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_old_support_matrix_apply"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import( + &workspace_id, + OpenApiUpload { + bytes: OPENAPI_SINGLE.as_bytes().to_vec(), + mime_type: "application/yaml".to_owned(), + locale: OpenApiUploadLocale::En, + }, + ) + .await + .unwrap(); + let job_id = preview.job_id.as_str().into(); + let created = service + .create_openapi_import_plan( + &workspace_id, + &job_id, + OpenApiImportPlanCreatePayload { + selection_mode: "full".to_owned(), + selected_operation_keys: Vec::new(), + server_url: None, + decisions: Vec::new(), + }, + ) + .await + .unwrap(); + let original_id: ImportPlanId = created.plan_reference.as_str().into(); + let original = registry + .get_import_plan(&workspace_id, &original_id) + .await + .unwrap() + .unwrap(); + + // Model an immutable plan saved under an earlier support matrix. The + // registry derives its valid semantic digest from the changed payload. + let old_id: ImportPlanId = "plan_older_support_matrix".into(); + let mut old_payload = original.payload.clone(); + old_payload["plan_reference"] = json!(old_id.as_str()); + old_payload["support_matrix_version"] = json!("1.0.1"); + let older = registry + .create_import_plan(CreateImportPlanRequest { + id: &old_id, + workspace_id: &workspace_id, + job_id: &original.job_id, + payload: &old_payload, + created_at: &original.created_at, + expires_at: &original.expires_at, + }) + .await + .unwrap(); + assert_ne!(older.digest, original.digest); + + let audit = service + .revalidate_openapi_import_plan(&workspace_id, &old_id) + .await + .unwrap(); + assert_eq!(audit.revalidation_status, "stale"); + assert!(audit.revalidation_required); + assert_eq!(audit.reason.as_deref(), Some("importer_version_changed")); + + let error = service + .apply_openapi_import_plan( + &workspace_id, + &old_id, + OpenApiImportPlanApplyPayload { + plan_digest: older.digest, + idempotency_key: "old-matrix-new-attempt".to_owned(), + }, + ) + .await + .expect_err("old support matrix must not authorize a new Apply"); + match error { + ApiError::Conflict { + context: Some(context), + .. + } => assert_eq!(context["error_code"], "importer_version_changed"), + other => panic!("expected typed re-preview conflict, got {other:?}"), + } + assert!( + service + .list_operations(&workspace_id) + .await + .unwrap() + .is_empty() + ); +} diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_create/creation.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_create/creation.rs index 6e79198..10c28df 100644 --- a/apps/admin-api/tests/integration/openapi_import/import_plan_create/creation.rs +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_create/creation.rs @@ -16,6 +16,134 @@ paths: responses: { '200': { description: ok } } "#; +#[tokio::test(flavor = "multi_thread")] +#[serial] +async fn preview_name_conflicts_are_typed_and_deterministic() { + let registry = test_registry().await; + let upstream = spawn_upstream_server().await; + let service = test_service( + registry, + test_storage_root("openapi_preview_name_conflicts"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace = WorkspaceId::new("ws_default"); + service + .create_operation( + &workspace, + test_operation_payload(&upstream, "duplicate_id"), + ) + .await + .unwrap(); + let document = r#" +openapi: 3.0.3 +info: { title: Naming } +servers: [{ url: https://api.example.test }] +paths: + /one: + get: + operationId: duplicate_id + responses: { '200': { description: ok } } + /two: + get: + operationId: duplicate_id + responses: { '200': { description: ok } } + /bad: + get: + operationId: bad-id + responses: { '200': { description: ok } } +"#; + let first = service + .preview_openapi_import(&workspace, upload(document)) + .await + .unwrap(); + let repeated = service + .preview_openapi_import(&workspace, upload(document)) + .await + .unwrap(); + assert_eq!(first.preview.conflicts, repeated.preview.conflicts); + assert!( + first + .preview + .conflicts + .iter() + .any(|item| item.conflict_type == "duplicate_name") + ); + assert!( + first + .preview + .conflicts + .iter() + .any(|item| item.conflict_type == "invalid_name") + ); + assert!( + first + .preview + .conflicts + .iter() + .any(|item| item.conflict_type == "taken_name") + ); + assert!(first.preview.conflicts.iter().all(|item| { + item.source_location + .as_ref() + .is_some_and(|location| location.pointer.starts_with("/paths/")) + && !item.proposed_name.is_empty() + })); + assert_eq!(service.list_operations(&workspace).await.unwrap().len(), 1); +} + +#[tokio::test(flavor = "multi_thread")] +#[serial] +async fn reopening_plan_is_read_only_and_reports_catalog_drift() { + let registry = test_registry().await; + let upstream = spawn_upstream_server().await; + let service = test_service( + registry, + test_storage_root("openapi_plan_reopen_catalog"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace, upload(OPENAPI_SINGLE)) + .await + .unwrap(); + let job_id: ImportJobId = preview.job_id.as_str().into(); + let plan = service + .create_openapi_import_plan(&workspace, &job_id, plan_payload("full", vec![], vec![])) + .await + .unwrap(); + let plan_id = plan.plan_reference.as_str().into(); + let current = service + .revalidate_openapi_import_plan(&workspace, &plan_id) + .await + .unwrap(); + assert_eq!(current.revalidation_status, "current"); + assert!(!current.revalidation_required); + assert!( + service + .list_operations(&workspace) + .await + .unwrap() + .is_empty() + ); + + service + .create_operation( + &workspace, + test_operation_payload(&upstream, "unrelated_operation"), + ) + .await + .unwrap(); + let stale = service + .revalidate_openapi_import_plan(&workspace, &plan_id) + .await + .unwrap(); + assert_eq!(stale.revalidation_status, "stale"); + assert!(stale.revalidation_required); + assert_eq!(service.list_operations(&workspace).await.unwrap().len(), 1); +} + #[tokio::test(flavor = "multi_thread")] #[serial] async fn full_plan_is_server_authored_with_bounded_confirmation_and_no_mutation() { @@ -31,6 +159,7 @@ async fn full_plan_is_server_authored_with_bounded_confirmation_and_no_mutation( .preview_openapi_import(&workspace_id, upload(OPENAPI_SINGLE)) .await .unwrap(); + assert_eq!(preview.preview.groups[0].operations[0].status, "actionable"); let job_id: ImportJobId = preview.job_id.as_str().into(); let job = registry .get_import_job(&workspace_id, &job_id) @@ -77,6 +206,11 @@ async fn full_plan_is_server_authored_with_bounded_confirmation_and_no_mutation( .unwrap() .expect("the created plan must be readable in its workspace"); assert_eq!(stored.digest, plan.plan_digest); + assert_eq!(stored.payload["schema_version"], "import-plan-v2"); + assert_eq!(stored.payload["catalog_revision"], plan.catalog_revision); + assert_eq!(stored.payload["support_matrix_version"], "1.0.2"); + assert!(stored.payload["findings"]["document"].is_array()); + assert!(stored.payload["findings"]["candidates"].is_array()); assert_eq!(stored.expires_at, expires_at); assert_eq!( stored.payload["selection"]["selected"], @@ -98,6 +232,21 @@ async fn full_plan_is_server_authored_with_bounded_confirmation_and_no_mutation( job.preview_payload["source"]["digest"] ); assert!(stored.payload["fingerprint"]["ir_fingerprint"].is_string()); + let repeated = service + .create_openapi_import_plan(&workspace_id, &job_id, plan_payload("full", vec![], vec![])) + .await + .unwrap(); + assert_ne!(repeated.plan_reference, plan.plan_reference); + assert_eq!(repeated.plan_digest, plan.plan_digest); + let repeated_stored = registry + .get_import_plan(&workspace_id, &repeated.plan_reference.as_str().into()) + .await + .unwrap() + .unwrap(); + assert_ne!( + repeated_stored.payload["candidates"][0]["operation"]["id"], + stored.payload["candidates"][0]["operation"]["id"] + ); // Planning is non-mutating: no operation exists and the job stays pending. assert!( service @@ -154,6 +303,18 @@ async fn partial_plan_counts_selection_and_rejects_invalid_request_material() { .expect("the excluded candidate is listed for confirmation"); assert_eq!(excluded.state, "excluded"); assert_eq!(excluded.reason.as_deref(), Some("not_selected")); + let stored = registry + .get_import_plan(&workspace_id, &plan.plan_reference.as_str().into()) + .await + .unwrap() + .unwrap(); + assert_eq!( + stored.payload["excluded_reasons"], + json!([{ + "key": second, + "reason": "not_selected", + }]) + ); let stored = registry .get_import_plan(&workspace_id, &plan.plan_reference.as_str().into()) @@ -351,7 +512,7 @@ async fn client_supplied_candidate_material_has_no_authority() { stored.payload["selection"]["all"], json!(["GET /v2/latest"]) ); - assert_eq!(stored.payload["schema_version"], "import-plan-v1"); + assert_eq!(stored.payload["schema_version"], "import-plan-v2"); assert!(stored.digest.len() == 64 && stored.digest.bytes().all(|b| b.is_ascii_hexdigit())); } @@ -403,6 +564,11 @@ async fn plan_creation_is_workspace_scoped() { .await .unwrap(); assert!(stored.is_none(), "a foreign plan id must be invisible"); + let reopen_error = service + .revalidate_openapi_import_plan(&secondary, &plan.plan_reference.as_str().into()) + .await + .expect_err("a foreign plan cannot be reopened"); + assert_http_status(reopen_error, axum::http::StatusCode::NOT_FOUND); } #[tokio::test(flavor = "multi_thread")] diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_create/mod.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_create/mod.rs index b2253d7..f3555b6 100644 --- a/apps/admin-api/tests/integration/openapi_import/import_plan_create/mod.rs +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_create/mod.rs @@ -161,6 +161,7 @@ fn assert_http_status(error: ApiError, expected: axum::http::StatusCode) { } mod creation; +mod route_get; pub(super) use creation::OPENAPI_SINGLE_SECURITY; mod security_availability; mod security_binding; diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_create/route_get.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_create/route_get.rs new file mode 100644 index 0000000..0b9e941 --- /dev/null +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_create/route_get.rs @@ -0,0 +1,87 @@ +use super::*; + +#[tokio::test(flavor = "multi_thread")] +#[serial] +async fn persisted_plan_get_requires_owner_and_reports_catalog_drift() { + let registry = test_registry().await; + let storage_root = test_storage_root("openapi_import_plan_get_route"); + let service = test_service( + registry.clone(), + storage_root.clone(), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace, upload(OPENAPI_SINGLE)) + .await + .unwrap(); + let job_id: ImportJobId = preview.job_id.as_str().into(); + let plan = service + .create_openapi_import_plan(&workspace, &job_id, plan_payload("full", vec![], vec![])) + .await + .unwrap(); + let plan_id = plan.plan_reference.clone(); + let plan_digest = plan.plan_digest.clone(); + + let foreign_workspace = WorkspaceId::new("ws_plan_get_foreign"); + let now = OffsetDateTime::now_utc(); + registry + .create_workspace(CreateWorkspaceRequest { + workspace: &Workspace { + id: foreign_workspace.clone(), + slug: "ws-plan-get-foreign".to_owned(), + display_name: "Foreign plan workspace".to_owned(), + status: WorkspaceStatus::Active, + settings: json!({}), + created_at: now, + updated_at: now, + }, + }) + .await + .unwrap(); + + let server = spawn_admin_api(build_test_app(registry, storage_root)).await; + let client = authorized_client(&server).await; + let url = format!("{server}/imports/openapi/plans/{plan_id}"); + let anonymous = reqwest::Client::new().get(&url).send().await.unwrap(); + assert_eq!(anonymous.status(), reqwest::StatusCode::UNAUTHORIZED); + let foreign = client + .get(url.replace("ws_default", foreign_workspace.as_str())) + .send() + .await + .unwrap(); + assert_eq!(foreign.status(), reqwest::StatusCode::FORBIDDEN); + + let current = client.get(&url).send().await.unwrap(); + assert_eq!(current.status(), reqwest::StatusCode::OK); + let current: Value = current.json().await.unwrap(); + assert_eq!(current["plan_reference"], plan_id); + assert_eq!(current["plan_digest"], plan_digest); + assert_eq!(current["revalidation_status"], "current"); + assert_eq!(current["revalidation_required"], false); + assert!( + service + .list_operations(&workspace) + .await + .unwrap() + .is_empty() + ); + + let upstream = spawn_upstream_server().await; + service + .create_operation( + &workspace, + test_operation_payload(&upstream, "plan_get_catalog_drift"), + ) + .await + .unwrap(); + let stale = client.get(&url).send().await.unwrap(); + assert_eq!(stale.status(), reqwest::StatusCode::OK); + let stale: Value = stale.json().await.unwrap(); + assert_eq!(stale["plan_reference"], plan_id); + assert_eq!(stale["plan_digest"], plan_digest); + assert_eq!(stale["revalidation_status"], "stale"); + assert_eq!(stale["revalidation_required"], true); + assert_eq!(service.list_operations(&workspace).await.unwrap().len(), 1); +} diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_create/security_binding.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_create/security_binding.rs index 0394e9b..9d41579 100644 --- a/apps/admin-api/tests/integration/openapi_import/import_plan_create/security_binding.rs +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_create/security_binding.rs @@ -119,6 +119,7 @@ async fn auth_profile_references_are_validated_stored_and_inherited() { .preview_openapi_import(&workspace_id, upload(OPENAPI_SINGLE_SECURITY)) .await .unwrap(); + assert_eq!(preview.preview.groups[0].operations[0].status, "unresolved"); let selectable = preview .security_profile_choices .iter() @@ -648,7 +649,7 @@ async fn basic_and_query_profiles_bind_to_matching_security_alternatives_and_app plan_payload( "partial", vec!["GET /v2/query".to_owned()], - vec![query_decision], + vec![query_decision.clone()], ), ) .await @@ -664,7 +665,7 @@ async fn basic_and_query_profiles_bind_to_matching_security_alternatives_and_app Some(query_profile.id.as_str()) ); - for (plan, expected_profile, idempotency_key) in [ + for (index, (plan, expected_profile, idempotency_key)) in [ ( &basic_plan, basic_profile.id.as_str(), @@ -675,7 +676,44 @@ async fn basic_and_query_profiles_bind_to_matching_security_alternatives_and_app query_profile.id.as_str(), "apply-query-profile", ), - ] { + ] + .into_iter() + .enumerate() + { + let fresh_plan; + let plan = if index == 1 { + let stale = service + .apply_openapi_import_plan( + &workspace_id, + &crank_registry::ImportPlanId::new(plan.plan_reference.clone()), + admin_api::service::OpenApiImportPlanApplyPayload { + plan_digest: plan.plan_digest.clone(), + idempotency_key: "stale-query-profile".to_owned(), + }, + ) + .await + .expect_err("the earlier query plan is stale after catalog mutation"); + assert_error_code(&stale, "import_plan_fingerprint_stale"); + let refreshed = service + .preview_openapi_import(&workspace_id, upload(OPENAPI_BASIC_AND_QUERY_SECURITY)) + .await + .unwrap(); + fresh_plan = service + .create_openapi_import_plan( + &workspace_id, + &refreshed.job_id.as_str().into(), + plan_payload( + "partial", + vec!["GET /v2/query".to_owned()], + vec![query_decision.clone()], + ), + ) + .await + .unwrap(); + &fresh_plan + } else { + plan + }; let report = service .apply_openapi_import_plan( &workspace_id, diff --git a/apps/admin-api/tests/integration/openapi_import/import_plan_create/validation.rs b/apps/admin-api/tests/integration/openapi_import/import_plan_create/validation.rs index 555f9d7..2fff462 100644 --- a/apps/admin-api/tests/integration/openapi_import/import_plan_create/validation.rs +++ b/apps/admin-api/tests/integration/openapi_import/import_plan_create/validation.rs @@ -1,5 +1,80 @@ use super::*; +#[tokio::test(flavor = "multi_thread")] +#[serial] +async fn preview_rejects_candidate_2001_without_truncation_or_operations() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_preview_candidate_limit"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace = WorkspaceId::new("ws_default"); + let mut document = String::from( + "openapi: 3.0.3\ninfo: { title: Limit }\nservers: [{ url: https://api.example.test }]\npaths:\n", + ); + for index in 0..2001 { + document.push_str(&format!(" /p{index}:\n get:\n operationId: op{index}\n responses: {{ '200': {{ description: ok }} }}\n")); + } + let error = service + .preview_openapi_import(&workspace, upload(&document)) + .await + .expect_err("candidate 2001 must be rejected as a whole"); + assert_error_code(&error, "openapi_preview_too_many_candidates"); + assert!( + service + .list_operations(&workspace) + .await + .unwrap() + .is_empty() + ); + let active_sources: i64 = sqlx::query_scalar( + "select count(*) from artifact_sources where workspace_id = $1 and lifecycle = 'active'", + ) + .bind(workspace.as_str()) + .fetch_one(registry.pool()) + .await + .unwrap(); + assert_eq!(active_sources, 0); +} + +#[tokio::test(flavor = "multi_thread")] +#[serial] +async fn partial_plan_rejects_selected_blocker_before_persistence() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_import_plan_partial_blocker"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace_id, upload(OPENAPI_GLOBAL_BLOCKER)) + .await + .unwrap(); + assert_eq!(preview.preview.groups[0].operations[0].status, "blocked"); + let job_id: ImportJobId = preview.job_id.as_str().into(); + let key = preview.preview.groups[0].operations[0].key.clone(); + let error = service + .create_openapi_import_plan( + &workspace_id, + &job_id, + plan_payload("partial", vec![key], vec![]), + ) + .await + .expect_err("blocked partial selection must be rejected"); + assert_error_code(&error, "import_plan_partial_blocked"); + assert!( + service + .list_operations(&workspace_id) + .await + .unwrap() + .is_empty() + ); +} + #[tokio::test(flavor = "multi_thread")] #[serial] async fn explicit_targets_are_checked_even_when_the_candidate_is_blocked() { diff --git a/apps/admin-api/tests/integration/openapi_import/large_preview.rs b/apps/admin-api/tests/integration/openapi_import/large_preview.rs new file mode 100644 index 0000000..8702916 --- /dev/null +++ b/apps/admin-api/tests/integration/openapi_import/large_preview.rs @@ -0,0 +1,142 @@ +use super::*; + +use admin_api::service::OpenApiImportPlanCreatePayload; +use std::fmt::Write as _; + +const OPERATION_COUNT: usize = 2_000; +const MAX_UPLOAD_BYTES: usize = 256 * 1024; +const MAX_STORED_PLAN_BYTES: usize = 16 * 1024 * 1024; + +fn large_openapi_document() -> String { + let mut document = String::from( + "openapi: 3.0.3\n\ + info: { title: Large preview, version: '1' }\n\ + servers: [{ url: 'https://api.example.test' }]\n\ + paths:\n", + ); + for index in 0..OPERATION_COUNT { + writeln!( + document, + " /p{index:04}:\n get:\n operationId: o{index:04}\n responses: {{ '200': {{ description: ok }} }}" + ) + .unwrap(); + } + document +} + +#[tokio::test] +#[serial] +async fn previews_and_plans_two_thousand_operations_without_catalog_mutation() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_large_preview"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let document = large_openapi_document(); + assert!( + document.len() <= MAX_UPLOAD_BYTES, + "generated document is {} bytes, over the 256 KiB upload limit", + document.len() + ); + + let preview = service + .preview_openapi_import( + &workspace_id, + OpenApiUpload { + bytes: document.into_bytes(), + mime_type: "application/yaml".to_owned(), + locale: OpenApiUploadLocale::En, + }, + ) + .await + .expect("valid 2,000-operation OpenAPI document should preview"); + let preview_candidates = preview + .preview + .groups + .iter() + .flat_map(|group| &group.operations) + .collect::>(); + assert_eq!(preview_candidates.len(), OPERATION_COUNT); + assert_eq!(preview_candidates[0].key, "GET /p0000"); + assert_eq!(preview_candidates[OPERATION_COUNT - 1].key, "GET /p1999"); + assert!(preview_candidates.iter().all(|candidate| { + candidate.status == "actionable" + && candidate.method == crank_core::HttpMethod::Get + && candidate.path.starts_with("/p") + })); + + let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into(); + let plan = service + .create_openapi_import_plan( + &workspace_id, + &job_id, + OpenApiImportPlanCreatePayload { + selection_mode: "full".to_owned(), + selected_operation_keys: Vec::new(), + server_url: None, + decisions: Vec::new(), + }, + ) + .await + .expect("full plan should include all 2,000 operations"); + assert_eq!(plan.counts.selected, OPERATION_COUNT); + assert_eq!(plan.counts.actionable, OPERATION_COUNT); + assert_eq!(plan.counts.excluded, 0); + assert_eq!(plan.counts.blocked, 0); + assert_eq!(plan.candidates.len(), OPERATION_COUNT); + assert!(plan.candidates.iter().all(|candidate| { + candidate.state == "actionable" && candidate.action.as_deref() == Some("create") + })); + + let plan_id = plan.plan_reference.as_str().into(); + let stored = registry + .get_import_plan(&workspace_id, &plan_id) + .await + .unwrap() + .expect("full plan should be persisted and readable"); + let stored_payload_bytes = serde_json::to_vec(&stored.payload).unwrap().len(); + assert!( + stored_payload_bytes <= MAX_STORED_PLAN_BYTES, + "stored plan payload is {stored_payload_bytes} bytes, over 16 MiB" + ); + let stored_candidates = stored.payload["candidates"] + .as_array() + .expect("stored plan contains its full candidate list"); + assert_eq!(stored_candidates.len(), OPERATION_COUNT); + assert!(stored_candidates.iter().all(|candidate| { + candidate["state"] == "actionable" && candidate["decision"]["action"] == "create" + })); + assert_eq!(stored.payload["counts"]["selected"], OPERATION_COUNT); + assert_eq!(stored.payload["counts"]["actionable"], OPERATION_COUNT); + + let revalidated = service + .revalidate_openapi_import_plan(&workspace_id, &plan_id) + .await + .expect("revalidating the unchanged plan should be read-only and current"); + assert_eq!(revalidated.revalidation_status, "current"); + assert!(!revalidated.revalidation_required); + assert_eq!(revalidated.counts.selected, OPERATION_COUNT); + assert_eq!(revalidated.counts.actionable, OPERATION_COUNT); + assert_eq!(revalidated.counts.excluded, 0); + assert_eq!(revalidated.counts.blocked, 0); + assert_eq!(revalidated.candidates.len(), OPERATION_COUNT); + + let (operations, operation_versions) = sqlx::query_as::<_, (i64, i64)>( + "select + (select count(*) from operations where workspace_id = $1), + (select count(*) from operation_versions ov + join operations o on o.id = ov.operation_id where o.workspace_id = $1)", + ) + .bind(workspace_id.as_str()) + .fetch_one(registry.pool()) + .await + .unwrap(); + assert_eq!(operations, 0, "preview and plan must not create operations"); + assert_eq!( + operation_versions, 0, + "preview and plan must not create operation versions" + ); +} diff --git a/apps/admin-api/tests/integration/openapi_import/upload_outcomes.rs b/apps/admin-api/tests/integration/openapi_import/upload_outcomes.rs new file mode 100644 index 0000000..c57edd3 --- /dev/null +++ b/apps/admin-api/tests/integration/openapi_import/upload_outcomes.rs @@ -0,0 +1,140 @@ +use super::*; + +use admin_api::error::ApiError; +use crank_artifacts::MAX_ARTIFACT_BYTES; +use crank_core::HttpMethod; + +#[derive(Debug, PartialEq, Eq)] +struct CatalogCounts { + operations: i64, + operation_versions: i64, + auth_profiles: i64, + agent_operation_bindings: i64, +} + +async fn catalog_counts( + registry: &crank_registry::PostgresRegistry, + workspace_id: &WorkspaceId, +) -> CatalogCounts { + let (operations, operation_versions, auth_profiles, agent_operation_bindings) = + sqlx::query_as::<_, (i64, i64, i64, i64)>( + "select + (select count(*) from operations where workspace_id = $1), + (select count(*) from operation_versions ov + join operations o on o.id = ov.operation_id where o.workspace_id = $1), + (select count(*) from auth_profiles where workspace_id = $1), + (select count(*) from agent_operation_bindings b + join operations o on o.id = b.operation_id where o.workspace_id = $1)", + ) + .bind(workspace_id.as_str()) + .fetch_one(registry.pool()) + .await + .unwrap(); + + CatalogCounts { + operations, + operation_versions, + auth_profiles, + agent_operation_bindings, + } +} + +fn upload(bytes: Vec) -> OpenApiUpload { + OpenApiUpload { + bytes, + mime_type: "application/json".to_owned(), + locale: OpenApiUploadLocale::En, + } +} + +fn assert_upload_error(error: ApiError, variant: &str, code: &str) { + let context = match (variant, error) { + ("validation", ApiError::Validation { context, .. }) => context, + ("payload_too_large", ApiError::PayloadTooLarge { context, .. }) => context, + (expected, actual) => panic!("expected {expected} error, got {actual:?}"), + } + .expect("OpenAPI upload errors carry a machine-readable code"); + assert_eq!(context["error_code"], format!("openapi_upload.{code}")); +} + +#[tokio::test] +#[serial] +async fn preview_outcomes_do_not_mutate_operation_catalog() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_upload_outcomes"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + + let before = catalog_counts(®istry, &workspace_id).await; + let preview = service + .preview_openapi_import( + &workspace_id, + upload( + br#"{ + "openapi":"3.0.3", + "info":{"title":"Upload outcomes","version":"1"}, + "paths":{"/ready":{"get":{"responses":{"200":{"description":"ok"}}}}} + }"# + .to_vec(), + ), + ) + .await + .expect("valid OpenAPI document should return a preview"); + let candidates = preview + .preview + .groups + .iter() + .flat_map(|group| &group.operations) + .collect::>(); + assert_eq!(candidates.len(), 1); + assert_eq!(candidates[0].method, HttpMethod::Get); + assert_eq!(candidates[0].path, "/ready"); + assert_eq!(candidates[0].key, "GET /ready"); + assert_eq!(catalog_counts(®istry, &workspace_id).await, before); + + let before = catalog_counts(®istry, &workspace_id).await; + let error = service + .preview_openapi_import(&workspace_id, upload(Vec::new())) + .await + .expect_err("empty upload should be rejected"); + assert_upload_error(error, "validation", "empty_file"); + assert_eq!(catalog_counts(®istry, &workspace_id).await, before); + + let before = catalog_counts(®istry, &workspace_id).await; + let error = service + .preview_openapi_import(&workspace_id, upload(b"{".to_vec())) + .await + .expect_err("malformed OpenAPI document should be rejected"); + assert_upload_error(error, "validation", "invalid_document"); + assert_eq!(catalog_counts(®istry, &workspace_id).await, before); + + let before = catalog_counts(®istry, &workspace_id).await; + let error = service + .preview_openapi_import(&workspace_id, upload(vec![b' '; MAX_ARTIFACT_BYTES + 1])) + .await + .expect_err("oversized upload should be rejected"); + assert_upload_error(error, "payload_too_large", "file_too_large"); + assert_eq!(catalog_counts(®istry, &workspace_id).await, before); + + let before = catalog_counts(®istry, &workspace_id).await; + let error = service + .preview_openapi_import( + &workspace_id, + upload( + br#"{ + "openapi":"3.0.3", + "info":{"title":"No methods","version":"1"}, + "paths":{} + }"# + .to_vec(), + ), + ) + .await + .expect_err("document without supported methods should be rejected"); + assert_upload_error(error, "validation", "no_methods"); + assert_eq!(catalog_counts(®istry, &workspace_id).await, before); +} diff --git a/apps/admin-api/tests/integration/openapi_import/v5_replay.rs b/apps/admin-api/tests/integration/openapi_import/v5_replay.rs new file mode 100644 index 0000000..f7538d4 --- /dev/null +++ b/apps/admin-api/tests/integration/openapi_import/v5_replay.rs @@ -0,0 +1,93 @@ +use super::*; + +#[tokio::test] +#[serial] +async fn exact_v5_contract_replays_saved_preview_without_source_locations() { + use sha2::{Digest, Sha256}; + + fn remove_source_locations(value: &mut serde_json::Value) { + match value { + serde_json::Value::Object(object) => { + object.remove("source_location"); + for value in object.values_mut() { + remove_source_locations(value); + } + } + serde_json::Value::Array(values) => { + for value in values { + remove_source_locations(value); + } + } + _ => {} + } + } + + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_import_v5_compatibility"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace_id, openapi_upload()) + .await + .unwrap(); + let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into(); + let mut payload = registry + .get_import_job(&workspace_id, &job_id) + .await + .unwrap() + .unwrap() + .preview_payload; + + // A preview persisted under v5 has the then-current projection and digest, + // without the source_location fields added by v6. + let persisted_preview = payload + .get_mut("preview") + .expect("newly saved job includes its preview"); + assert!(persisted_preview.to_string().contains("source_location")); + remove_source_locations(persisted_preview); + let digest = format!( + "{:x}", + Sha256::digest(serde_json::to_vec(persisted_preview).unwrap()) + ); + payload["normalization"]["normalizer_version"] = "normalized-ir-v5".into(); + payload["normalization"]["projection_version"] = "preview-v5".into(); + payload["normalization"]["config"]["normalizer_version"] = "normalized-ir-v5".into(); + payload["normalization"]["config"]["projection_version"] = "preview-v5".into(); + payload["preview_digest"] = digest.into(); + // If v5 is reparsed, this deliberately absent dependency makes the replay fail. + payload["dependency_snapshots"] = serde_json::json!([{ + "source_id": "src_openapi_dep_v5_must_not_be_read", + "digest": format!("sha256:{}", "0".repeat(64)), + "canonical_uri": "https://schemas.example.test/v5.yaml" + }]); + sqlx::query("update import_jobs set preview_payload = $1::jsonb where id = $2") + .bind(serde_json::to_string(&payload).unwrap()) + .bind(job_id.as_str()) + .execute(registry.pool()) + .await + .unwrap(); + + let result = service + .create_openapi_import( + &workspace_id, + &job_id, + OpenApiImportCreatePayload { + selected_operation_keys: vec!["GET /v2/latest".to_owned()], + server_url: Some("https://api.frankfurter.dev".to_owned()), + conflict_mode: "skip".to_owned(), + }, + ) + .await + .unwrap(); + assert_eq!(result.created.len(), 1); + let completed = registry + .get_import_job(&workspace_id, &job_id) + .await + .unwrap() + .unwrap(); + assert_eq!(completed.status, ImportJobStatus::Completed); +} diff --git a/apps/ui/css/openapi-import.css b/apps/ui/css/openapi-import.css index 5e696b1..8e5d266 100644 --- a/apps/ui/css/openapi-import.css +++ b/apps/ui/css/openapi-import.css @@ -213,6 +213,27 @@ gap: 8px; } +.openapi-import-findings summary { + cursor: pointer; + color: var(--text-secondary); + font-weight: 700; +} + +.openapi-import-findings-page { + display: grid; + gap: 4px; + padding-top: 6px; +} + +.openapi-import-findings-pagination { + display: flex; + align-items: center; + justify-content: flex-start; + gap: 8px; + padding-top: 6px; + color: var(--text-secondary); +} + .openapi-import-plan-candidate, .openapi-import-plan-outcome { display: grid; @@ -334,6 +355,30 @@ gap: 14px; } +.openapi-import-partial-toggle { + display: flex; + align-items: center; + gap: 9px; + width: fit-content; + color: var(--text-primary); + font-size: 13px; + font-weight: 700; +} + +.openapi-import-pagination { + display: flex; + align-items: center; + justify-content: center; + gap: 12px; + padding: 4px 0; + color: var(--text-secondary); + font-size: 13px; +} + +.openapi-import-pagination[hidden] { + display: none; +} + .openapi-import-group-header { display: flex; align-items: center; @@ -452,6 +497,21 @@ font-weight: 700; } +.openapi-import-plan-version, +.openapi-import-plan-revalidation { + color: var(--text-secondary); + font-size: 12px; + overflow-wrap: anywhere; +} + +.openapi-import-plan-stale { + padding: 10px 12px; + border: 1px solid var(--red); + border-radius: 10px; + color: var(--red); + font-weight: 700; +} + .openapi-import-operation:last-child { border-bottom: 0; } @@ -466,6 +526,25 @@ font-size: 12px; } +.openapi-import-source-location { + color: var(--text-muted); + font-size: 11px; + overflow-wrap: anywhere; +} + +.openapi-import-conflict { + display: flex; + flex-wrap: wrap; + align-items: baseline; + gap: 6px; + color: var(--amber); + font-size: 12px; +} + +.openapi-import-conflict-proposal { + color: var(--text-primary); +} + .openapi-import-method { padding: 4px 8px; border-radius: 999px; @@ -475,6 +554,26 @@ font-weight: 800; } +.openapi-import-operation-readiness { + justify-self: start; + padding: 4px 8px; + border-radius: 999px; + background: var(--surface-muted, #21262d); + color: var(--text-secondary); + font-size: 11px; + font-weight: 800; +} + +.openapi-import-operation-readiness-actionable { + background: var(--green-glow, rgba(63, 185, 80, 0.16)); + color: var(--green); +} + +.openapi-import-operation-readiness-blocked { + background: var(--red-glow, rgba(248, 81, 73, 0.16)); + color: var(--red); +} + .openapi-import-findings { grid-column: 2 / -1; display: grid; @@ -643,6 +742,17 @@ font-size: 13px; } +.openapi-import-result-skipped-page { + margin-top: 6px; +} + +.openapi-import-result-skipped-page ul { + max-height: 320px; + overflow: auto; + margin: 0; + padding-left: 22px; +} + .openapi-import-created-list { display: grid; gap: 6px; diff --git a/apps/ui/index.html b/apps/ui/index.html index 7cb1bdd..a7cec4f 100644 --- a/apps/ui/index.html +++ b/apps/ui/index.html @@ -433,7 +433,16 @@ +
+ '; - response.created.forEach(function(operation) { + var created = Array.isArray(response.created) ? response.created : []; + var resultPageCount = Math.max(1, Math.ceil(created.length / OPERATIONS_PER_PAGE)); + state.resultPageIndex = Math.min(Math.max(0, state.resultPageIndex), resultPageCount - 1); + created.slice(state.resultPageIndex * OPERATIONS_PER_PAGE, (state.resultPageIndex + 1) * OPERATIONS_PER_PAGE).forEach(function(operation) { var previewOperation = previewOperationForCreated(operation); var row = document.createElement('div'); var nameCell = document.createElement('div'); @@ -1276,23 +1549,22 @@ }); node.appendChild(table); + if (created.length > OPERATIONS_PER_PAGE) { + node.appendChild(createPageNavigation(state.resultPageIndex, created.length, 'openapi.pagination.result_label', function(page) { + state.resultPageIndex = page; + renderResult(response); + })); + } } if (response.skipped && response.skipped.length) { - var skippedNode = document.createElement('div'); - skippedNode.className = 'openapi-import-result-skipped'; - skippedNode.textContent = tKey('openapi.result.skipped') + ': ' + response.skipped.map(function(item) { - return (item.name || item.operation_key || tKey('openapi.result.unnamed')) + ' — ' - + findingMessage({ code: item.code || item.reason_code || item.reason }); - }).join('; '); - node.appendChild(skippedNode); + node.appendChild(renderSkippedPanel(response.skipped)); } if (response.findings && response.findings.length) { - var findings = document.createElement('div'); - findings.className = 'openapi-import-result-findings'; - findings.innerHTML = response.findings.map(renderFinding).join(''); - node.appendChild(findings); + var findingsPanel = renderFindingsPanel(response.findings); + findingsPanel.classList.add('openapi-import-result-findings'); + node.appendChild(findingsPanel); } node.hidden = false; @@ -1323,7 +1595,25 @@ return tKey(key) === key ? tKey('openapi.plan.action.create') : tKey(key); } - function renderImportPlan(plan) { + function updatePlanRevalidationUi(plan, hasBlocked) { + var statusNode = qs('openapi-import-plan-revalidation-status'); + var staleNode = qs('openapi-import-plan-stale'); + var reopenButton = qs('openapi-import-plan-reopen'); + var statusKey = 'openapi.plan.revalidation_' + state.planRevalidationState; + statusNode.textContent = tKey(statusKey); + var unsafe = state.planRevalidationState === 'stale' + || state.planRevalidationState === 'error' + || state.planRevalidationState === 'pending' + || !!plan.revalidation_required + || state.applyOutcomeUnknown; + staleNode.hidden = !unsafe || state.planRevalidationState === 'pending' || state.applyOutcomeUnknown; + staleNode.textContent = unsafe && !staleNode.hidden ? tKey('openapi.plan.revalidation_guidance') : ''; + reopenButton.disabled = state.applyInFlight || state.applyOutcomeUnknown; + reopenButton.setAttribute('aria-busy', state.planRevalidationState === 'pending' ? 'true' : 'false'); + qs('openapi-import-plan-apply').disabled = hasBlocked || unsafe; + } + + function renderImportPlan(plan, pageOnly) { var countsNode = qs('openapi-import-plan-counts'); var candidatesNode = qs('openapi-import-plan-candidates'); var versioningNode = qs('openapi-import-versioning-consequences'); @@ -1332,30 +1622,37 @@ var operationsByKey = Object.create(null); importOperations().forEach(function(operation) { operationsByKey[operation.key] = operation; }); - // The plan API is the sole authority for each operation's binding outcome. - (Array.isArray(plan.candidates) ? plan.candidates : []).forEach(function(candidate) { - if (!candidate || !candidate.key) return; - var operation = operationsByKey[candidate.key]; - var alternativeIndex = candidate.security_alternative_index; - var anonymous = alternativeIndex !== null && alternativeIndex !== undefined - && isAnonymousAlternative(alternativeFor(operation, alternativeIndex)); - var status; - if (candidate.state === 'blocked') { - status = 'blocked'; - } else if (candidate.state === 'actionable') { - // Only a genuine auth binding confirmed by the API is resolved; a - // no-auth/anonymous or unbound candidate must never read as resolved. - if (candidate.auth_profile_id) status = 'resolved'; - else if (operation && !operationRequiresAuth(operation)) status = 'no_auth'; - else if (anonymous) status = 'no_auth'; - else status = 'unresolved'; - } else { - // Excluded/skipped candidates keep the operation untouched. - status = 'unresolved'; - } - setOperationSecurityStatus(candidate.key, status); - }); - updateSecuritySummary(); + if (!pageOnly) { + // The plan API is the sole authority for each operation's binding outcome. + (Array.isArray(plan.candidates) ? plan.candidates : []).forEach(function(candidate) { + if (!candidate || !candidate.key) return; + var operation = operationsByKey[candidate.key]; + var alternativeIndex = candidate.security_alternative_index; + var anonymous = alternativeIndex !== null && alternativeIndex !== undefined + && isAnonymousAlternative(alternativeFor(operation, alternativeIndex)); + var status; + if (candidate.state === 'blocked') { + status = 'blocked'; + } else if (candidate.state === 'actionable') { + // Only a genuine auth binding confirmed by the API is resolved; a + // no-auth/anonymous or unbound candidate must never read as resolved. + if (candidate.auth_profile_id) status = 'resolved'; + else if (operation && !operationRequiresAuth(operation)) status = 'no_auth'; + else if (anonymous) status = 'no_auth'; + else status = 'unresolved'; + } else { + // Excluded/skipped candidates keep the operation untouched. + status = 'unresolved'; + } + state.securityByOperation[candidate.key] = status; + }); + document.querySelectorAll('[data-openapi-security-op-status]').forEach(function(node) { + var status = state.securityByOperation[node.dataset.openapiSecurityOpStatus] || 'unresolved'; + node.dataset.status = status; + node.textContent = securityStatusLabel(status); + }); + updateSecuritySummary(); + } var countSpecs = [ ['selected', 'openapi.plan.selected'], ['excluded', 'openapi.plan.excluded'], @@ -1363,17 +1660,38 @@ ['blocked', 'openapi.plan.blocked'], ]; + var planCandidates = Array.isArray(plan.candidates) ? plan.candidates : []; + var planPageCount = Math.max(1, Math.ceil(planCandidates.length / OPERATIONS_PER_PAGE)); + state.planPageIndex = Math.min(Math.max(0, state.planPageIndex), planPageCount - 1); + state.planCandidates = planCandidates; countsNode.replaceChildren(); candidatesNode.replaceChildren(); + var planPagination = qs('openapi-import-plan-pagination'); + planPagination.hidden = planCandidates.length <= OPERATIONS_PER_PAGE; + qs('openapi-import-plan-page-status').textContent = tfKey('openapi.pagination.status', { + page: state.planPageIndex + 1, + pages: planPageCount, + total: planCandidates.length, + }); + qs('openapi-import-plan-page-previous').disabled = state.planPageIndex === 0; + qs('openapi-import-plan-page-next').disabled = state.planPageIndex + 1 >= planPageCount; countSpecs.forEach(function(spec) { var item = document.createElement('span'); item.className = 'openapi-import-plan-count'; + if (spec[0] === 'blocked') item.dataset.testid = 'openapi-import-blockers'; item.textContent = tfKey(spec[1], { count: Number(counts[spec[0]]) || 0 }); countsNode.appendChild(item); }); - var hasNewVersion = false; - (Array.isArray(plan.candidates) ? plan.candidates : []).forEach(function(candidate) { + var hasNewVersion = planCandidates.some(function(candidate) { + return candidate.action === 'new_version' && candidate.state !== 'blocked' && candidate.state !== 'excluded'; + }); + qs('openapi-import-plan-version').textContent = tfKey('openapi.plan.version', { + version: state.planVersion, + reference: plan.plan_reference, + digest: plan.plan_digest, + }); + planCandidates.slice(state.planPageIndex * OPERATIONS_PER_PAGE, (state.planPageIndex + 1) * OPERATIONS_PER_PAGE).forEach(function(candidate) { var item = document.createElement('article'); var title = document.createElement('strong'); var key = document.createElement('code'); @@ -1394,13 +1712,12 @@ confirmedName.textContent = tKey('openapi.plan.confirmed_name') + ': ' + candidate.confirmed_name; item.appendChild(confirmedName); } - if (candidate.action === 'new_version' && candidate.state !== 'blocked' && candidate.state !== 'excluded') { - hasNewVersion = true; - } if (candidate.reason) { var reason = document.createElement('p'); reason.className = 'openapi-import-plan-reason'; + if (candidate.state === 'excluded') reason.dataset.testid = 'openapi-import-excluded-reason'; reason.textContent = findingMessage({ code: candidate.reason }); + if (candidate.state === 'excluded') reason.textContent += ' (' + candidate.reason + ')'; item.appendChild(reason); } candidatesNode.appendChild(item); @@ -1411,9 +1728,47 @@ qs('openapi-import-plan-confirmation').hidden = false; qs('openapi-import-plan-blocked-help').hidden = !hasBlocked; qs('openapi-import-result').hidden = true; - qs('openapi-import-plan-apply').disabled = hasBlocked; + updatePlanRevalidationUi(plan, hasBlocked); qs('openapi-import-plan-back').textContent = tKey(hasBlocked ? 'openapi.plan.back_fix' : 'openapi.plan.back'); - lockPlanEditing(true); + if (!pageOnly) lockPlanEditing(true); + } + + async function revalidateCurrentPlan() { + if (!state.plan || state.applyInFlight || state.applyOutcomeUnknown) return; + var planReference = state.plan.plan_reference; + var generation = ++state.planRevalidationGeneration; + state.planRevalidationState = 'pending'; + updatePlanRevalidationUi(state.plan, (Number(state.plan.counts && state.plan.counts.blocked) || 0) > 0); + try { + var response = await window.CrankApi.revalidateOpenApiImportPlan( + state.workspaceId, + planReference, + {} + ); + if (generation !== state.planRevalidationGeneration + || !state.plan || state.plan.plan_reference !== planReference) return; + if (!response || response.plan_reference !== planReference + || !/^[a-f0-9]{64}$/.test(String(response.plan_digest || '')) + || response.plan_digest !== state.plan.plan_digest + || !response.counts || !Array.isArray(response.candidates) + || typeof response.revalidation_required !== 'boolean') { + throw new Error('Backend returned an invalid ImportPlan revalidation response'); + } + state.plan = Object.assign({}, state.plan, response); + if (response.revalidation_status === 'stale' || response.revalidation_required) { + state.planRevalidationState = 'stale'; + } else if (response.revalidation_status === 'current' && !response.revalidation_required) { + state.planRevalidationState = 'current'; + } else { + state.planRevalidationState = 'error'; + } + renderImportPlan(state.plan); + } catch (_error) { + if (generation !== state.planRevalidationGeneration + || !state.plan || state.plan.plan_reference !== planReference) return; + state.planRevalidationState = 'error'; + updatePlanRevalidationUi(state.plan, (Number(state.plan.counts && state.plan.counts.blocked) || 0) > 0); + } } function reportOutcomeLabel(outcome) { @@ -1447,7 +1802,9 @@ if (outcomes.length) { var list = document.createElement('div'); list.className = 'openapi-import-plan-outcomes'; - outcomes.forEach(function(outcome) { + var pageCount = Math.max(1, Math.ceil(outcomes.length / OPERATIONS_PER_PAGE)); + state.resultPageIndex = Math.min(Math.max(0, state.resultPageIndex), pageCount - 1); + outcomes.slice(state.resultPageIndex * OPERATIONS_PER_PAGE, (state.resultPageIndex + 1) * OPERATIONS_PER_PAGE).forEach(function(outcome) { var item = document.createElement('article'); var heading = document.createElement('strong'); var key = document.createElement('code'); @@ -1471,6 +1828,12 @@ list.appendChild(item); }); node.appendChild(list); + if (outcomes.length > OPERATIONS_PER_PAGE) { + node.appendChild(createPageNavigation(state.resultPageIndex, outcomes.length, 'openapi.pagination.result_label', function(page) { + state.resultPageIndex = page; + renderImportPlanReport(report); + })); + } } node.hidden = false; @@ -1554,10 +1917,12 @@ return; } state.applyResult = response; + state.resultPageIndex = 0; state.applyRequest = null; state.plan = null; if (isCurrent(revision, workspaceId, language)) { - renderImportPlanReport(response); + if (Array.isArray(response.outcomes)) renderImportPlanReport(response); + else renderResult(response); if (response.recovery === 'repreview_required') { setStatus(tKey('openapi.plan.repreview'), true, true); showRetry(true); @@ -1594,6 +1959,7 @@ var report = reportFromPayload(error.payload); if (report && isCurrent(revision, workspaceId, language)) { state.applyResult = report; + state.resultPageIndex = 0; renderImportPlanReport(report); } var recovery = recoveryCode(error.payload); @@ -1641,7 +2007,7 @@ setStatus(tKey('openapi.error.selection'), true, true); return; } - if (keys.length > 512 || importOperations().length - keys.length > 512) { + if (keys.length > 2000 || importOperations().length - keys.length > 2000) { setStatus(tKey('openapi.error.plan_too_large'), true, true); return; } @@ -1722,13 +2088,10 @@ return; } - var total = (state.preview.groups || []).reduce(function(count, group) { - return count + (group.operations || []).length; - }, 0); - var selectionMode = keys.length === total ? 'full' : 'partial'; + var selectionMode = state.partialMode ? 'partial' : 'full'; var payload = { selection_mode: selectionMode, - selected_operation_keys: selectionMode === 'full' ? [] : keys, + selected_operation_keys: keys, server_url: serverUrl, decisions: decisions, }; @@ -1736,6 +2099,8 @@ var workspaceId = state.workspaceId; var language = locale(); var controller = new AbortController(); + state.planRevalidationGeneration += 1; + state.planRevalidationState = 'current'; state.planController = controller; state.plan = null; lockPlanEditing(true); @@ -1759,6 +2124,10 @@ throw new Error('Backend returned an invalid ImportPlan response'); } state.plan = plan; + state.planVersion += 1; + state.planPageIndex = 0; + state.planRevalidationState = plan.revalidation_status === 'stale' || plan.revalidation_required + ? 'stale' : 'current'; renderImportPlan(plan); setStatus(tKey('openapi.status.plan_ready')); } catch (error) { @@ -1797,6 +2166,7 @@ async function applyImportPlan() { if (state.applyInFlight || !state.plan || state.applyOutcomeUnknown) return; + if (state.planRevalidationState !== 'current' || state.plan.revalidation_required) return; var request = { workspaceId: state.workspaceId, planReference: state.plan.plan_reference, @@ -1814,7 +2184,9 @@ function backToImportSelection() { if (state.applyInFlight || state.applyOutcomeUnknown) return; + state.planRevalidationGeneration += 1; state.plan = null; + state.planRevalidationState = 'current'; // Returning to editing voids the previous review: revalidation is done by // the next plan request. resetSecurityStatuses(); @@ -1823,6 +2195,8 @@ qs('openapi-import-plan-candidates').replaceChildren(); qs('openapi-import-versioning-consequences').hidden = true; qs('openapi-import-plan-blocked-help').hidden = true; + qs('openapi-import-plan-stale').hidden = true; + qs('openapi-import-plan-revalidation-status').textContent = ''; qs('openapi-import-plan-back').textContent = tKey('openapi.plan.back'); lockPlanEditing(false); setStatus(tKey('openapi.status.preview_ready')); @@ -1966,6 +2340,41 @@ qs('openapi-import-clear-visible').addEventListener('click', function() { setVisibleSelection(false); }); + qs('openapi-import-partial-mode').addEventListener('change', function(event) { + state.partialMode = event.target.checked && !documentIsBlocked(); + event.target.checked = state.partialMode; + if (!state.partialMode) state.selectedOperationKeys = new Set(importOperations().map(function(operation) { return operation.key; })); + else importOperations().forEach(function(operation) { + if (operationIsBlocked(operation)) state.selectedOperationKeys.delete(operation.key); + }); + renderOperationPage(); + qs('openapi-import-select-visible').disabled = !state.partialMode; + qs('openapi-import-clear-visible').disabled = !state.partialMode; + lockPlanEditing(false); + updateSelection(); + }); + qs('openapi-import-page-previous').addEventListener('click', function() { + if (state.pageIndex <= 0) return; + state.pageIndex -= 1; + renderOperationPage(); + updateSelection(); + }); + qs('openapi-import-page-next').addEventListener('click', function() { + state.pageIndex += 1; + renderOperationPage(); + updateSelection(); + }); + qs('openapi-import-plan-page-previous').addEventListener('click', function() { + if (state.planPageIndex <= 0 || !state.plan) return; + state.planPageIndex -= 1; + renderImportPlan(state.plan, true); + }); + qs('openapi-import-plan-page-next').addEventListener('click', function() { + if (!state.plan || state.planPageIndex + 1 >= Math.ceil((state.plan.candidates || []).length / OPERATIONS_PER_PAGE)) return; + state.planPageIndex += 1; + renderImportPlan(state.plan, true); + }); + qs('openapi-import-plan-reopen').addEventListener('click', revalidateCurrentPlan); document.querySelectorAll('[data-openapi-close]').forEach(function(node) { node.addEventListener('click', close); }); @@ -2025,6 +2434,7 @@ renderSecurityControls(operation, row); } }); + if (state.preview) renderOperationPage(); if (!qs('openapi-import-modal').hidden && state.plan) { renderImportPlan(state.plan); setStatus(tKey('openapi.status.plan_ready')); diff --git a/apps/ui/tests/e2e/openapi-import-plan.spec.js b/apps/ui/tests/e2e/openapi-import-plan.spec.js index 77bdfe2..847e1d3 100644 --- a/apps/ui/tests/e2e/openapi-import-plan.spec.js +++ b/apps/ui/tests/e2e/openapi-import-plan.spec.js @@ -254,6 +254,7 @@ test('[P1] AC-13 submits the confirmed new_version decision for the exact existi const operationCheckbox = operationRow.locator('[data-openapi-operation]'); await expect(operationCheckbox).toBeVisible(); const operationKey = await operationCheckbox.inputValue(); + await page.locator('#openapi-import-partial-mode').check(); for (const checkbox of await page.locator('[data-openapi-operation]').all()) { if (await checkbox.inputValue() !== operationKey) await checkbox.uncheck(); } diff --git a/apps/ui/tests/e2e/openapi-preview-partial.spec.js b/apps/ui/tests/e2e/openapi-preview-partial.spec.js new file mode 100644 index 0000000..65698bc --- /dev/null +++ b/apps/ui/tests/e2e/openapi-preview-partial.spec.js @@ -0,0 +1,1184 @@ +// Story 2.12 acceptance tests for full preview and explicit partial mode. +// +// All mandatory UI leaves are active; backend-only contracts are verified in +// the Rust integration and unit suites. +// +// This file covers user-observable behavior; see +// `_bmad-output/test-artifacts/atdd-checklist-2-12-preview-partial-mode.md` +// for the complete AC-to-test evidence map. + +const { test, expect } = require('@playwright/test'); +const { getCurrentWorkspace, login, localized, uniqueName } = require('./helpers'); + +async function dismissOnboardingIfOpen(page) { + await page.locator('#crank-onboarding-panel').waitFor({ state: 'attached' }); + await page.locator('[data-testid="onboarding-dismiss"]').waitFor({ state: 'attached' }); + await page.evaluate(() => { + const dismiss = document.querySelector('[data-testid="onboarding-dismiss"]'); + if (dismiss) dismiss.click(); + }); + await expect(page.locator('#crank-onboarding-panel')).toBeHidden(); +} + +function importDocument(prefix, paths) { + const lines = [ + 'openapi: 3.0.3', + "info: { title: 'Preview partial ATDD', version: '1' }", + 'servers: [{ url: https://api.example.test }]', + 'paths:', + ]; + for (const [path, operationId] of paths) { + lines.push(' /' + path + ':'); + lines.push(' get:'); + lines.push(' operationId: ' + operationId); + lines.push(' responses:'); + lines.push(" '200': { description: OK }"); + } + return lines.join('\n'); +} + +function candidate(prefix, suffix, overrides) { + return Object.assign( + { + key: 'GET /' + prefix + '-' + suffix, + method: 'GET', + path: '/' + prefix + '-' + suffix, + operation_id: prefix + '_' + suffix, + suggested_name: prefix + '_' + suffix, + suggested_display_name: prefix + ' ' + suffix, + description: 'ATDD candidate', + category: 'default', + input_fields: 0, + output_fields: 1, + server_urls: ['https://api.example.test'], + // Proposed Story 2.12 additions (not produced by the baseline API yet). + source_location: { pointer: '/paths/~1' + prefix + '-' + suffix + '/get' }, + findings: [], + security_requirements: { source: 'none', alternatives: [] }, + security_schemes: {}, + draft: { + name: prefix + '_' + suffix, + display_name: prefix + ' ' + suffix, + category: 'default', + target: { method: 'GET', path: '/' + prefix + '-' + suffix, server_url: 'https://api.example.test' }, + input_schema: { type: 'object', properties: {} }, + output_schema: { type: 'object', properties: {} }, + input_mapping: [], + output_mapping: [], + tool_description: {}, + wizard_state: null, + }, + }, + overrides || {}, + ); +} + +function previewResponse(prefix, operations, extra) { + return Object.assign( + { + job_id: 'imp_e2e_preview_partial', + expires_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(), + preview: { + source: { + format: 'openapi', + version: '3.0.3', + title: 'Preview partial ATDD', + servers: ['https://api.example.test'], + }, + groups: [{ key: 'default', title: 'Default', operations }], + findings: [], + // Proposed Story 2.12 addition. + conflicts: [], + }, + security_profile_choices: [], + }, + extra || {}, + ); +} + +function planResponse(prefix, candidates, overrides) { + return Object.assign( + { + plan_reference: 'plan_e2e_preview_partial_212', + plan_digest: 'c'.repeat(64), + expires_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(), + selection_mode: 'full', + counts: { selected: candidates.length, excluded: 0, actionable: candidates.length, blocked: 0 }, + candidates, + }, + overrides || {}, + ); +} + +async function routeOperationsEmpty(page) { + await page.route('**/api/admin/workspaces/*/operations', async (route) => { + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify({ items: [], page: 1, page_size: 0, total: 0 }), + }); + }); +} + +async function openImportModal(page, locale) { + await login(page); + await dismissOnboardingIfOpen(page); + await page.evaluate((language) => window.setLang(language), locale); + await page.getByRole('button', { name: localized('Import OpenAPI', 'Импорт OpenAPI') }).click(); + await expect(page.locator('#openapi-import-modal')).toBeVisible(); +} + +async function uploadAndPreview(page, prefix, paths) { + await page.locator('#openapi-import-file').setInputFiles({ + name: 'preview-partial.yaml', + mimeType: 'application/yaml', + buffer: Buffer.from(importDocument(prefix, paths)), + }); + const previewResponseWaiter = page.waitForResponse((response) => + response.request().method() === 'POST' + && response.url().includes('/imports/openapi/preview'), + ); + await page.locator('#openapi-import-preview').click(); + await previewResponseWaiter; + await expect(page.locator('#openapi-import-preview-panel')).toBeVisible(); +} + +// AC-1: preview must expose source locations and stable finding codes for +// every candidate, finding and conflict. Backend emission is owned by the +// Rust preview suite; this leaf asserts the UI renders what the API returns. +test('[P1] AC-1 preview renders source locations and stable finding codes for candidates and conflicts', async ({ page }) => { + const prefix = uniqueName('preview_location'); + const operations = [ + candidate(prefix, 'located', { + findings: [ + { + code: 'missing_operation_id', + severity: 'warning', + message: 'No operationId', + operation_key: 'GET /' + prefix + '-located', + source_location: { pointer: '/paths/~1' + prefix + '-located/get' }, + }, + ], + }), + ]; + const response = previewResponse(prefix, operations); + response.preview.conflicts = [ + { + operation_key: 'GET /' + prefix + '-located', + conflict_type: 'duplicate_name', + proposed_name: prefix + '_located_2', + source_location: { pointer: '/paths/~1' + prefix + '-located/get/operationId' }, + }, + ]; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(response), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [[prefix + '-located', prefix + '_located']]); + + const row = page.locator('.openapi-import-operation').first(); + await row.locator('.openapi-import-findings summary').click(); + await expect(row.locator('[data-testid="openapi-import-operation-location"]')).toContainText('/paths/'); + await expect(row.locator('[data-testid="openapi-import-finding-code"]')).toContainText('missing_operation_id'); + await expect(row.locator('[data-testid="openapi-import-finding-location"]')).toContainText('/paths/'); + await expect(row.locator('[data-testid="openapi-import-conflict"]')).toContainText('duplicate_name'); + await expect(row.locator('[data-testid="openapi-import-conflict-location"]')).toContainText('/operationId'); +}); + +// AC-4: duplicate/invalid/taken names must show a deterministic rename +// proposal and conflict type, and the snapshot must stay unchanged. +test('[P1] AC-4 preview shows conflict type and deterministic rename proposal without mutating the snapshot', async ({ page }) => { + const prefix = uniqueName('preview_naming'); + const operations = [candidate(prefix, 'clash', { suggested_name: 'shared_name' })]; + const response = previewResponse(prefix, operations); + const planCalls = []; + response.preview.conflicts = [ + { + operation_key: 'GET /' + prefix + '-clash', + conflict_type: 'taken_name', + proposed_name: 'shared_name_2', + source_location: { pointer: '/paths/~1' + prefix + '-clash/get' }, + }, + ]; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(response), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + planCalls.push(route.request().postDataJSON()); + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, [{ + key: 'GET /' + prefix + '-clash', + name: 'reviewed_name', + state: 'actionable', + action: 'rename', + target_operation_id: null, + confirmed_name: 'reviewed_name', + auth_profile_id: null, + reason: null, + }], { selection_mode: 'full', counts: { selected: 1, excluded: 0, actionable: 1, blocked: 0 } })), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [[prefix + '-clash', prefix + '_clash']]); + + const conflict = page.locator('[data-testid="openapi-import-conflict"]').first(); + await expect(conflict).toContainText('taken_name'); + const proposal = page.locator('[data-testid="openapi-import-rename-proposal"]').first(); + await expect(proposal).toHaveValue('shared_name_2'); + await page.locator('[data-openapi-decision-action]').selectOption('rename'); + await proposal.fill('reviewed_name'); + // The original snapshot name is still shown verbatim next to the proposal. + await expect(page.locator('.openapi-import-operation').first()).toContainText('clash'); + expect(operations[0].suggested_name).toBe('shared_name'); + expect(operations[0].draft.name).toBe(prefix + '_clash'); + await page.locator('#openapi-import-server-custom').fill('https://api.example.test'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + expect(planCalls).toHaveLength(1); + expect(planCalls[0].decisions).toContainEqual(expect.objectContaining({ + operation_key: 'GET /' + prefix + '-clash', + action: 'rename', + confirmed_name: 'reviewed_name', + })); +}); + +// AC-6: any blocker in full mode forbids Apply for the whole document while +// showing the full blocker count and affected candidates. +test('[P1] AC-6 full mode disables Apply and lists blocker count and affected candidates', async ({ page }) => { + const prefix = uniqueName('preview_blocker'); + const operations = [ + candidate(prefix, 'valid'), + candidate(prefix, 'broken', { + findings: [ + { + code: 'unsupported_schema', + severity: 'error', + message: 'Unsupported schema', + operation_key: 'GET /' + prefix + '-broken', + source_location: { pointer: '/paths/~1' + prefix + '-broken/get' }, + }, + ], + }), + ]; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + const response = previewResponse(prefix, operations); + response.preview.findings = [{ code: 'unsupported_document', severity: 'error', message: 'Document blocker' }]; + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(response), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, [ + { + key: 'GET /' + prefix + '-valid', + name: 'valid', + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + }, + { + key: 'GET /' + prefix + '-broken', + name: 'broken', + state: 'blocked', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: 'unsupported_schema', + }, + ], { + selection_mode: 'full', + counts: { selected: 2, excluded: 0, actionable: 1, blocked: 1 }, + })), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [ + [prefix + '-valid', prefix + '_valid'], + [prefix + '-broken', prefix + '_broken'], + ]); + await page.locator('#openapi-import-create').click(); + + const blockers = page.locator('[data-testid="openapi-import-blockers"]'); + await expect(blockers).toContainText('1'); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toContainText('broken'); + await expect(page.locator('#openapi-import-plan-apply')).toBeDisabled(); + await expect(page.locator('#openapi-import-partial-mode')).toBeDisabled(); + await expect(page.locator('[data-testid="openapi-import-apply-result"]')).toBeHidden(); +}); + +// AC-7: partial mode is enabled explicitly and accepts only an actionable, +// dependency-closed subset; excluded/blocked reasons stay visible. +test('[P1] AC-7 explicit partial mode submits only the actionable closed subset and shows excluded reasons', async ({ page }) => { + const prefix = uniqueName('preview_partial'); + const planCalls = []; + const operations = [ + candidate(prefix, 'keep'), + candidate(prefix, 'drop'), + candidate(prefix, 'blocked', { status: 'blocked' }), + candidate(prefix, 'typed_blocked'), + ]; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + const response = previewResponse(prefix, operations); + response.preview.findings = [{ + code: 'unsupported_schema', + severity: 'error', + operation_key: 'GET /' + prefix + '-typed_blocked', + }]; + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(response), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + planCalls.push(route.request().postDataJSON()); + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, [ + { + key: 'GET /' + prefix + '-keep', + name: prefix + '_keep', + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + }, + { + key: 'GET /' + prefix + '-drop', + name: prefix + '_drop', + state: 'excluded', + action: null, + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: 'not_selected', + }, + ], { + selection_mode: 'partial', + counts: { selected: 1, excluded: 1, actionable: 1, blocked: 0 }, + })), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [ + [prefix + '-keep', prefix + '_keep'], + [prefix + '-drop', prefix + '_drop'], + [prefix + '-blocked', prefix + '_blocked'], + [prefix + '-typed_blocked', prefix + '_typed_blocked'], + ]); + + const partialToggle = page.locator('#openapi-import-partial-mode'); + await expect(partialToggle).toBeVisible(); + await partialToggle.check(); + const blockedInput = page.locator('[data-openapi-operation][value="GET /' + prefix + '-blocked"]'); + await expect(blockedInput).toBeDisabled(); + const typedBlockedInput = page.locator('[data-openapi-operation][value="GET /' + prefix + '-typed_blocked"]'); + await expect(typedBlockedInput).toBeDisabled(); + await expect(partialToggle).toBeChecked(); + await page.locator('#openapi-import-select-visible').click(); + await expect(blockedInput).not.toBeChecked(); + await expect(typedBlockedInput).not.toBeChecked(); + for (const checkbox of await page.locator('[data-openapi-operation]').all()) { + const key = await checkbox.inputValue(); + if (!key.includes('-keep') && !(await checkbox.isDisabled())) await checkbox.uncheck(); + } + await page.locator('#openapi-import-server-custom').fill('https://api.example.test'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + + expect(planCalls).toHaveLength(1); + expect(planCalls[0].selection_mode).toBe('partial'); + expect(planCalls[0].selected_operation_keys).toEqual(['GET /' + prefix + '-keep']); + await expect(page.locator('[data-testid="openapi-import-excluded-reason"]')).toContainText('not_selected'); +}); + +// AC-8: a changed selection/name/mapping/policy creates a new immutable plan +// version with a new digest while the previous version stays readable. +test('[P1] AC-8 changed selection and rename decision create an immutable plan version; old plan stays readable', async ({ page }) => { + const prefix = uniqueName('preview_version'); + const operations = [candidate(prefix, 'one'), candidate(prefix, 'two')]; + const references = ['plan_previous_e2e', 'plan_current_e2e']; + const digests = ['d'.repeat(64), 'e'.repeat(64)]; + const planCalls = []; + const planReads = []; + let workspaceId = ''; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(previewResponse(prefix, operations)), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + const payload = route.request().postDataJSON(); + planCalls.push(payload); + workspaceId = decodeURIComponent(new URL(route.request().url()).pathname.match(/\/workspaces\/([^/]+)/)[1]); + const index = Math.min(planCalls.length - 1, digests.length - 1); + const planCandidates = index === 0 + ? operations.map((operation) => ({ + key: operation.key, + name: operation.suggested_name, + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + })) + : [ + { + key: operations[0].key, + name: prefix + '_renamed', + state: 'actionable', + action: 'rename', + target_operation_id: null, + confirmed_name: prefix + '_renamed', + auth_profile_id: null, + reason: null, + }, + { + key: operations[1].key, + name: operations[1].suggested_name, + state: 'excluded', + action: null, + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: 'not_selected', + }, + ]; + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, planCandidates, { + plan_reference: references[index], + plan_digest: digests[index], + selection_mode: index === 0 ? 'full' : 'partial', + counts: index === 0 + ? { selected: 2, excluded: 0, actionable: 2, blocked: 0 } + : { selected: 1, excluded: 1, actionable: 1, blocked: 0 }, + })), + }); + }); + await page.route(/\/imports\/openapi\/plans\/[^/]+$/, async (route) => { + const reference = decodeURIComponent(new URL(route.request().url()).pathname.split('/').pop()); + planReads.push(reference); + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, operations.map((operation) => ({ + key: operation.key, + name: operation.suggested_name, + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + })), { + plan_reference: reference, + plan_digest: digests[0], + revalidation_status: 'current', + revalidation_required: false, + reason: null, + })), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [[prefix + '-one', prefix + '_one'], [prefix + '-two', prefix + '_two']]); + + await page.locator('#openapi-import-server-custom').fill('https://api.example.test'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + await page.locator('#openapi-import-plan-back').click(); + await page.locator('#openapi-import-partial-mode').check(); + await page.locator('[data-openapi-operation][value="GET /' + prefix + '-two"]').uncheck(); + await page.locator('[data-openapi-decision-action]').first().selectOption('rename'); + await page.locator('[data-openapi-decision-name]').first().fill(prefix + '_renamed'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + + expect(planCalls).toHaveLength(2); + expect(planCalls[0].selected_operation_keys).toEqual(['GET /' + prefix + '-one', 'GET /' + prefix + '-two']); + expect(planCalls[1].selection_mode).toBe('partial'); + expect(planCalls[1].selected_operation_keys).toEqual(['GET /' + prefix + '-one']); + expect(planCalls[1].decisions).toContainEqual(expect.objectContaining({ + operation_key: 'GET /' + prefix + '-one', action: 'rename', confirmed_name: prefix + '_renamed', + })); + await expect(page.locator('[data-testid="openapi-import-plan-version"]')).toContainText('2'); + await expect(page.locator('[data-testid="openapi-import-plan-version"]')).toContainText(references[1]); + await expect(page.locator('[data-testid="openapi-import-plan-version"]')).toContainText(digests[1]); + + const previousPlan = await page.evaluate(async ({ workspace, reference }) => { + return window.CrankApi.revalidateOpenApiImportPlan(workspace, reference, {}); + }, { workspace: workspaceId, reference: references[0] }); + expect(planReads).toEqual([references[0]]); + expect(previousPlan.plan_reference).toBe(references[0]); + expect(previousPlan.plan_digest).toBe(digests[0]); + expect(previousPlan.candidates).toHaveLength(2); +}); + +// AC-10: re-opening a stored plan after catalog/Auth Profile drift must show +// stale/revalidation-required authority instead of a guaranteed Apply. +test('[P1] AC-10 reopens plans read-only, fails closed when stale/errors, and ignores an older GET response', async ({ page }) => { + const prefix = uniqueName('preview_stale'); + const planReference = 'plan_stale_e2e'; + const planDigest = 'f'.repeat(64); + const revalidationCalls = []; + let finishFirstRead; + const firstReadGate = new Promise((resolve) => { finishFirstRead = resolve; }); + let applyCalls = 0; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(previewResponse(prefix, [candidate(prefix, 'one')])), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, [ + { + key: 'GET /' + prefix + '-one', + name: prefix + '_one', + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + }, + ], { plan_reference: planReference, plan_digest: planDigest })), + }); + }); + await page.route(/\/imports\/openapi\/plans\/[^/]+$/, async (route) => { + const call = revalidationCalls.length + 1; + const reference = decodeURIComponent(new URL(route.request().url()).pathname.split('/').pop()); + revalidationCalls.push(reference); + if (call === 1) await firstReadGate; + if (call === 4) { + await route.fulfill({ status: 503, contentType: 'application/json', body: JSON.stringify({ message: 'temporary read failure' }) }); + return; + } + const current = call === 2; + const response = planResponse(prefix, [{ + key: 'GET /' + prefix + '-one', + name: prefix + '_one', + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + }], { + plan_reference: reference, + plan_digest: planDigest, + revalidation_status: current ? 'current' : 'stale', + revalidation_required: !current, + reason: current ? null : 'catalog_changed', + }); + await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(response) }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/apply$/, async (route) => { + applyCalls += 1; + await route.fulfill({ status: 500, contentType: 'application/json', body: JSON.stringify({ message: 'Apply must not run' }) }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [[prefix + '-one', prefix + '_one']]); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + + const reopen = page.locator('[data-testid="openapi-import-plan-reopen"]'); + await expect(reopen).toHaveAccessibleName('Reopen and check current plan'); + const firstRequest = page.waitForRequest((request) => request.method() === 'GET' && request.url().includes('/imports/openapi/plans/' + planReference)); + await reopen.click(); + await firstRequest; + const secondResponse = page.waitForResponse((response) => response.request().method() === 'GET' && response.url().includes('/imports/openapi/plans/' + planReference)); + await reopen.click(); + await secondResponse; + await expect(page.locator('[data-testid="openapi-import-plan-revalidation-status"]')).toContainText(localized('current', 'актуален')); + await expect(page.locator('#openapi-import-plan-apply')).toBeEnabled(); + const firstResponse = page.waitForResponse((response) => response.request().method() === 'GET' && response.url().includes('/imports/openapi/plans/' + planReference)); + finishFirstRead(); + await firstResponse; + await expect(page.locator('[data-testid="openapi-import-plan-revalidation-status"]')).toContainText(localized('current', 'актуален')); + await expect(page.locator('#openapi-import-plan-apply')).toBeEnabled(); + + await reopen.click(); + await expect(page.locator('[data-testid="openapi-import-plan-stale"]')).toBeVisible(); + await expect(page.locator('[data-testid="openapi-import-plan-stale"]')).toContainText(localized('create a new plan', 'создайте новый план')); + await expect(page.locator('#openapi-import-plan-apply')).toBeDisabled(); + await reopen.click(); + await expect(page.locator('[data-testid="openapi-import-plan-revalidation-status"]')).toContainText(localized('could not be verified', 'Не удалось проверить')); + await expect(page.locator('[data-testid="openapi-import-plan-stale"]')).toContainText(localized('create a new plan', 'создайте новый план')); + await expect(page.locator('#openapi-import-plan-apply')).toBeDisabled(); + expect(revalidationCalls).toEqual([planReference, planReference, planReference, planReference]); + expect(applyCalls).toBe(0); +}); + +// AC-11: a large preview must render bounded pages over up to 2,000 candidates +// without an unbounded DOM, while search/filter/grouping and selection survive +// page changes. +test('[P1] AC-11 renders bounded pages for 2000 candidates and preserves selection across pages', async ({ page }, testInfo) => { + test.setTimeout(120_000); + const prefix = uniqueName('preview_large'); + const operations = []; + for (let index = 0; index < 2000; index += 1) { + operations.push(candidate(prefix, 'op_' + index)); + } + const planCalls = []; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + const response = previewResponse(prefix, operations); + response.preview.findings = [{ + code: 'document_notice', severity: 'warning', message: 'Document-wide sample finding', + }]; + await route.fulfill({ + contentType: 'application/json', + body: JSON.stringify(response), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + planCalls.push(route.request().postDataJSON()); + const candidates = operations.map((operation, index) => { + const excluded = index === 0 || index === 100; + return { + key: operation.key, + name: operation.suggested_name, + state: excluded ? 'excluded' : 'actionable', + action: excluded ? null : 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: excluded ? 'not_selected' : null, + }; + }); + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, candidates, { + selection_mode: 'partial', + counts: { selected: 1998, excluded: 2, actionable: 1998, blocked: 0 }, + })), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [[prefix + '-op_0', prefix + '_op_0']]); + + const pager = page.locator('[data-testid="openapi-import-pagination"]'); + await expect(pager).toBeVisible(); + const rendered = page.locator('.openapi-import-operation'); + expect(await rendered.count()).toBeLessThanOrEqual(100); + await expect(page.locator('[data-testid="openapi-import-page-status"]')).toContainText('2000'); + + await page.locator('#openapi-import-partial-mode').check(); + const groupToggle = page.locator('.openapi-import-group [data-openapi-group]'); + await expect(page.locator('.openapi-import-group-toggle')).toContainText('Select group on this page'); + const russianLabel = await page.evaluate(() => { + localStorage.setItem('crank_lang', 'ru'); + const label = window.t('openapi.group.select'); + localStorage.setItem('crank_lang', 'en'); + return label; + }); + expect(russianLabel).toBe('Выбрать группу на этой странице'); + const firstPageFirst = page.locator('[data-openapi-operation]').first(); + const firstPageFirstKey = await firstPageFirst.inputValue(); + await firstPageFirst.uncheck(); + await groupToggle.check(); + await groupToggle.uncheck(); + await expect(page.locator('#openapi-import-selection')).toContainText('Selected: 1900'); + await pager.getByRole('button', { name: localized('Next', 'Далее') }).click(); + await expect(page.locator('[data-openapi-operation]').first()).toBeChecked(); + await pager.getByRole('button', { name: localized('Previous', 'Назад') }).click(); + await groupToggle.check(); + await firstPageFirst.uncheck(); + await pager.getByRole('button', { name: localized('Next', 'Далее') }).click(); + await expect(page.locator('[data-testid="openapi-import-page-status"]')).toContainText(localized('Page 2', 'Страница 2')); + const documentFindings = page.locator('.openapi-import-document-findings'); + await expect(documentFindings.locator('summary')).toContainText('Findings: 1'); + await documentFindings.locator('summary').click(); + await expect(documentFindings).toContainText('document_notice'); + expect(await rendered.count()).toBeLessThanOrEqual(100); + const secondPageFirst = page.locator('[data-openapi-operation]').first(); + const secondPageFirstKey = await secondPageFirst.inputValue(); + await secondPageFirst.uncheck(); + await pager.getByRole('button', { name: localized('Previous', 'Назад') }).click(); + await expect(page.locator(`[data-openapi-operation][value="${firstPageFirstKey}"]`)).not.toBeChecked(); + await pager.getByRole('button', { name: localized('Next', 'Далее') }).click(); + await expect(page.locator(`[data-openapi-operation][value="${secondPageFirstKey}"]`)).not.toBeChecked(); + + await page.locator('#openapi-import-search').fill('op_1999'); + await expect(page.locator('[data-openapi-operation]')).toHaveCount(1); + await expect(page.locator('[data-openapi-operation]').first()).toBeChecked(); + await expect(page.locator('[data-testid="openapi-import-page-status"]')).toContainText('1 matching operations'); + const previewMetrics = await page.evaluate(() => { + const search = document.querySelector('#openapi-import-search'); + const next = document.querySelector('#openapi-import-page-next'); + const previous = document.querySelector('#openapi-import-page-previous'); + const samples = { search_filter_ms: [], page_change_ms: [] }; + for (let index = 0; index < 20; index += 1) { + const startSearch = performance.now(); + search.value = 'op_' + (index * 10); + search.dispatchEvent(new Event('input', { bubbles: true })); + samples.search_filter_ms.push(Number((performance.now() - startSearch).toFixed(3))); + search.value = ''; + search.dispatchEvent(new Event('input', { bubbles: true })); + const startPage = performance.now(); + next.click(); + samples.page_change_ms.push(Number((performance.now() - startPage).toFixed(3))); + previous.click(); + } + return { + user_agent: navigator.userAgent, + platform: navigator.platform, + hardware_concurrency: navigator.hardwareConcurrency || null, + viewport: { width: innerWidth, height: innerHeight }, + search_filter_ms: samples.search_filter_ms, + page_change_ms: samples.page_change_ms, + }; + }); + await page.locator('#openapi-import-search').fill('op_1999'); + await expect(page.locator('[data-openapi-operation]')).toHaveCount(1); + await expect(page.locator('[data-openapi-operation]').first()).toBeChecked(); + await expect(page.locator('[data-testid="openapi-import-page-status"]')).toContainText('1 matching operations'); + await page.locator('#openapi-import-search').fill(''); + await page.locator('#openapi-import-server-custom').fill('https://api.example.test'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + expect(planCalls).toHaveLength(1); + expect(planCalls[0].selection_mode).toBe('partial'); + expect(planCalls[0].selected_operation_keys).toHaveLength(1998); + const planRows = page.locator('.openapi-import-plan-candidate'); + expect(await planRows.count()).toBeLessThanOrEqual(100); + await expect(page.locator('[data-testid="openapi-import-plan-page-status"]')).toContainText('2000'); + await page.locator('#openapi-import-plan-page-next').click(); + expect(await planRows.count()).toBeLessThanOrEqual(100); + await expect(planRows.first()).toContainText(prefix + '_op_100'); + const planMetrics = await page.evaluate(() => { + const next = document.querySelector('#openapi-import-plan-page-next'); + const previous = document.querySelector('#openapi-import-plan-page-previous'); + const samples = []; + for (let index = 0; index < 10; index += 1) { + let start = performance.now(); + previous.click(); + samples.push(Number((performance.now() - start).toFixed(3))); + start = performance.now(); + next.click(); + samples.push(Number((performance.now() - start).toFixed(3))); + } + return samples; + }); + await testInfo.attach('ac11-local-shared-host-metrics.json', { + body: Buffer.from(JSON.stringify({ + scope: 'LOCAL shared-host browser-handler samples; not Reference Deployment LAN evidence', + environment: { + user_agent: previewMetrics.user_agent, + platform: previewMetrics.platform, + hardware_concurrency: previewMetrics.hardware_concurrency, + viewport: previewMetrics.viewport, + }, + candidates: 2000, + max_operation_rows: 100, + max_plan_candidate_rows: 100, + samples: { + search_filter_ms: previewMetrics.search_filter_ms, + preview_page_change_ms: previewMetrics.page_change_ms, + plan_page_change_ms: planMetrics, + }, + }, null, 2)), + contentType: 'application/json', + }); + console.log('AC11_LOCAL_SHARED_HOST_METRICS ' + JSON.stringify({ + environment: { + user_agent: previewMetrics.user_agent, + platform: previewMetrics.platform, + hardware_concurrency: previewMetrics.hardware_concurrency, + viewport: previewMetrics.viewport, + }, + candidates: 2000, + max_operation_rows: 100, + max_plan_candidate_rows: 100, + samples: { + search_filter_ms: previewMetrics.search_filter_ms, + preview_page_change_ms: previewMetrics.page_change_ms, + plan_page_change_ms: planMetrics, + }, + })); +}); + +test('[P1] AC-11 keeps skipped apply outcomes accessible through bounded pages', async ({ page }) => { + const prefix = uniqueName('preview_skipped_pages'); + const operation = candidate(prefix, 'one'); + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + await route.fulfill({ contentType: 'application/json', body: JSON.stringify(previewResponse(prefix, [operation])) }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, [{ + key: operation.key, + name: operation.suggested_name, + state: 'actionable', + action: 'create', + target_operation_id: null, + confirmed_name: null, + auth_profile_id: null, + reason: null, + }], { counts: { selected: 1, excluded: 0, actionable: 1, blocked: 0 } })), + }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/apply$/, async (route) => { + const skipped = Array.from({ length: 250 }, (_, index) => ({ + operation_key: 'GET /' + prefix + '-skipped-' + index, + name: prefix + '_skipped_' + index, + reason: 'not_selected', + })); + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ created: [], skipped, findings: [] }), + }); + }); + await openImportModal(page, 'en'); + await uploadAndPreview(page, prefix, [[prefix + '-one', prefix + '_one']]); + await page.locator('#openapi-import-server-custom').fill('https://api.example.test'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + await page.locator('#openapi-import-plan-apply').click(); + + const skipped = page.locator('.openapi-import-result-skipped'); + await expect(skipped.locator('summary')).toContainText('250'); + await skipped.locator('summary').click(); + await expect(skipped.locator('li')).toHaveCount(100); + await expect(skipped.locator('[role="status"]')).toContainText('Page 1 of 3'); + await skipped.getByRole('button', { name: localized('Next', 'Далее') }).click(); + await expect(skipped.locator('li').first()).toContainText(prefix + '_skipped_100'); + await expect(skipped.locator('li')).toHaveCount(100); +}); + +// AC-12: RU/EN upload states (uploading, parsing, loading, empty/no-methods, +// error, stale, confirmation) plus a request-generation guard that prevents an +// older preview from overwriting a newer file or selection. +test('[P1] AC-12 exposes RU/EN live import states and discards stale preview/revalidation responses', async ({ page }) => { + const prefix = uniqueName('preview_states'); + const firstStaleCandidate = candidate(prefix, 'stale_file'); + const actionable = candidate(prefix, 'actionable', { status: 'actionable' }); + const blocked = candidate(prefix, 'blocked', { status: 'blocked' }); + const operations = [actionable, blocked]; + let releaseFirstPreview; + let finishFirstPreview; + let releaseOperations; + let releaseSelectionRead; + let releaseCurrentPreview; + let releaseRuPreview; + let releaseRuOperations; + let gateRuOperations = false; + const firstPreviewGate = new Promise((resolve) => { releaseFirstPreview = resolve; }); + const operationsGate = new Promise((resolve) => { releaseOperations = resolve; }); + const selectionReadGate = new Promise((resolve) => { releaseSelectionRead = resolve; }); + const currentPreviewGate = new Promise((resolve) => { releaseCurrentPreview = resolve; }); + const ruPreviewGate = new Promise((resolve) => { releaseRuPreview = resolve; }); + const ruOperationsGate = new Promise((resolve) => { releaseRuOperations = resolve; }); + const firstPreviewFinished = new Promise((resolve) => { finishFirstPreview = resolve; }); + let previewCalls = 0; + let planCalls = 0; + let revalidationCalls = 0; + let staleApplyCalls = 0; + await routeOperationsEmpty(page); + await page.route('**/api/admin/workspaces/*/imports/openapi/preview', async (route) => { + previewCalls += 1; + if (previewCalls === 1) { + await firstPreviewGate; + try { + await route.fulfill({ contentType: 'application/json', body: JSON.stringify(previewResponse(prefix, [firstStaleCandidate])) }); + } catch (_error) { + // The selected file replacement aborts this older request. + } finally { + finishFirstPreview(); + } + return; + } + if (previewCalls === 2 || previewCalls === 5) { + if (previewCalls === 2) await currentPreviewGate; + if (previewCalls === 5) await ruPreviewGate; + await route.fulfill({ contentType: 'application/json', body: JSON.stringify(previewResponse(prefix, operations)) }); + return; + } + const code = previewCalls === 4 || previewCalls === 7 ? 'openapi_upload.no_methods' : 'openapi_upload.invalid_document'; + await route.fulfill({ + status: 400, + contentType: 'application/json', + body: JSON.stringify({ error: { code, message: code } }), + }); + }); + await page.route('**/api/admin/workspaces/*/operations', async (route) => { + if (gateRuOperations) await ruOperationsGate; + else await operationsGate; + await route.fulfill({ contentType: 'application/json', body: JSON.stringify({ items: [], page: 1, page_size: 0, total: 0 }) }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/plans$/, async (route) => { + planCalls += 1; + const second = planCalls > 1; + const candidates = second + ? [{ key: actionable.key, name: actionable.suggested_name, state: 'actionable', action: 'create', target_operation_id: null, confirmed_name: null, auth_profile_id: null, reason: null }, + { key: blocked.key, name: blocked.suggested_name, state: 'excluded', action: null, target_operation_id: null, confirmed_name: null, auth_profile_id: null, reason: 'not_selected' }] + : operations.map((operation) => ({ key: operation.key, name: operation.suggested_name, state: operation.status, action: operation.status === 'actionable' ? 'create' : null, target_operation_id: null, confirmed_name: null, auth_profile_id: null, reason: operation.status === 'blocked' ? 'unsupported_schema' : null })); + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify(planResponse(prefix, candidates, { + plan_reference: 'plan_ac12_' + planCalls, + plan_digest: String(planCalls).padStart(64, 'a'), + selection_mode: second ? 'partial' : 'full', + counts: second + ? { selected: 1, excluded: 1, actionable: 1, blocked: 0 } + : { selected: 2, excluded: 0, actionable: 1, blocked: 1 }, + })), + }); + }); + await page.route(/\/imports\/openapi\/plans\/[^/]+$/, async (route) => { + revalidationCalls += 1; + const stale = { plan_reference: 'plan_ac12_1', plan_digest: '1'.padStart(64, 'a'), revalidation_status: 'stale', revalidation_required: true, reason: 'catalog_changed', counts: { selected: 2, excluded: 0, actionable: 1, blocked: 1 }, candidates: [] }; + if (revalidationCalls === 1) { + await selectionReadGate; + await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(stale) }); + return; + } + const currentPlan = 'plan_ac12_' + planCalls; + await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(Object.assign({}, stale, { + plan_reference: currentPlan, + plan_digest: String(planCalls).padStart(64, 'a'), + })) }); + }); + await page.route(/\/imports\/openapi\/[^/]+\/apply$/, async (route) => { + staleApplyCalls += 1; + await route.fulfill({ status: 500, contentType: 'application/json', body: JSON.stringify({ message: 'Apply must not run' }) }); + }); + await openImportModal(page, 'en'); + + await page.locator('#openapi-import-file').setInputFiles({ + name: 'states-a.yaml', + mimeType: 'application/yaml', + buffer: Buffer.from(importDocument(prefix, [[prefix + '-stale_file', prefix + '_stale_file']])), + }); + const firstPreview = page.waitForRequest((request) => request.method() === 'POST' && request.url().includes('/imports/openapi/preview')); + const previewButton = page.locator('#openapi-import-preview'); + await previewButton.focus(); + await expect(previewButton).toBeFocused(); + await previewButton.press('Enter'); + const status = page.locator('#openapi-import-status'); + await expect(status).toHaveAttribute('role', 'status'); + await expect(status).toHaveAttribute('aria-live', 'polite'); + await page.evaluate(() => { + const node = document.querySelector('#openapi-import-status'); + window.__openapiStatusHistory = [node.textContent]; + new MutationObserver(() => window.__openapiStatusHistory.push(node.textContent)) + .observe(node, { childList: true, characterData: true, subtree: true }); + }); + await expect(status).toContainText('Uploading'); + await firstPreview; + + // Replace the file while the first preview is still in flight. + await page.locator('#openapi-import-file').setInputFiles({ + name: 'states-current.yaml', + mimeType: 'application/yaml', + buffer: Buffer.from(importDocument(prefix, [[prefix + '-actionable', prefix + '_actionable'], [prefix + '-blocked', prefix + '_blocked']])), + }); + const currentPreview = page.waitForResponse((response) => response.request().method() === 'POST' && response.url().includes('/imports/openapi/preview')); + await page.locator('#openapi-import-preview').click(); + await expect(status).toContainText('Uploading'); + releaseCurrentPreview(); + await currentPreview; + await expect(status).toContainText('Checking existing workspace operations'); + releaseOperations(); + await expect(status).toContainText('Document is ready'); + const enStatusHistory = await page.evaluate(() => window.__openapiStatusHistory); + expect(enStatusHistory.some((message) => message.includes('Parsing the OpenAPI document'))).toBe(true); + await expect(page.locator('[data-testid="openapi-import-operation-readiness"][data-state="actionable"]')).toHaveAccessibleName('Actionable'); + await expect(page.locator('[data-testid="openapi-import-operation-readiness"][data-state="blocked"]')).toHaveAccessibleName('Blocked'); + releaseFirstPreview(); + await firstPreviewFinished; + await expect(status).toContainText('Document is ready'); + await expect(page.locator('.openapi-import-operation').first()).not.toContainText('stale_file'); + + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + await expect(status).toContainText('Review the server plan'); + const reopen = page.locator('#openapi-import-plan-reopen'); + await reopen.click(); + await page.locator('#openapi-import-plan-back').click(); + await page.locator('#openapi-import-partial-mode').check(); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-plan-version"]')).toContainText('plan_ac12_2'); + releaseSelectionRead(); + await expect(page.locator('[data-testid="openapi-import-plan-version"]')).toContainText('plan_ac12_2'); + await expect(page.locator('[data-testid="openapi-import-plan-revalidation-status"]')).toContainText('current'); + expect(planCalls).toBe(2); + + await reopen.click(); + await expect(page.locator('[data-testid="openapi-import-plan-stale"]')).toBeVisible(); + await expect(page.locator('#openapi-import-plan-apply')).toBeDisabled(); + await page.locator('#openapi-import-plan-back').click(); + + await page.locator('#openapi-import-file').setInputFiles({ name: 'invalid.yaml', mimeType: 'application/yaml', buffer: Buffer.from('openapi: [') }); + await page.locator('#openapi-import-preview').click(); + await expect(status).toContainText(localized('not a valid', 'некоррект')); + await page.locator('#openapi-import-file').setInputFiles({ name: 'empty.yaml', mimeType: 'application/yaml', buffer: Buffer.from('') }); + await expect(status).toContainText(localized('empty', 'пуст')); + await page.locator('#openapi-import-file').setInputFiles({ name: 'large.yaml', mimeType: 'application/yaml', buffer: Buffer.alloc(256 * 1024 + 1, 32) }); + await expect(status).toContainText('256'); + await page.locator('#openapi-import-file').setInputFiles({ name: 'no-methods.yaml', mimeType: 'application/yaml', buffer: Buffer.from("openapi: 3.0.3\ninfo: {title: Empty, version: '1'}\npaths: {}\n") }); + await page.locator('#openapi-import-preview').click(); + await expect(status).toContainText(localized('does not contain importable methods', 'нет поддерживаемых методов')); + expect(previewCalls).toBe(4); + expect(staleApplyCalls).toBe(0); + + await page.evaluate(() => window.setLang('ru')); + gateRuOperations = true; + await page.locator('#openapi-import-file').setInputFiles({ + name: 'states-ru.yaml', mimeType: 'application/yaml', + buffer: Buffer.from(importDocument(prefix, [[prefix + '-actionable', prefix + '_actionable'], [prefix + '-blocked', prefix + '_blocked']])), + }); + const ruPreview = page.waitForResponse((response) => response.request().method() === 'POST' && response.url().includes('/imports/openapi/preview')); + await page.locator('#openapi-import-preview').click(); + await expect(status).toContainText('Загружаю'); + releaseRuPreview(); + await ruPreview; + await expect(status).toContainText('Проверяю существующие операции'); + releaseRuOperations(); + await expect(status).toContainText('Документ готов'); + const ruStatusHistory = await page.evaluate(() => window.__openapiStatusHistory); + expect(ruStatusHistory.some((message) => message.includes('Разбираю документ OpenAPI'))).toBe(true); + await expect(page.locator('[data-testid="openapi-import-operation-readiness"][data-state="actionable"]')).toHaveAccessibleName('Можно импортировать'); + await expect(page.locator('[data-testid="openapi-import-operation-readiness"][data-state="blocked"]')).toHaveAccessibleName('Заблокировано'); + await page.locator('#openapi-import-create').click(); + await expect(page.locator('[data-testid="openapi-import-apply-confirmation"]')).toBeVisible(); + await expect(status).toContainText('Проверьте план сервера'); + await page.locator('#openapi-import-plan-reopen').click(); + await expect(page.locator('[data-testid="openapi-import-plan-stale"]')).toContainText('создайте новый план'); + await expect(page.locator('#openapi-import-plan-apply')).toBeDisabled(); + await page.locator('#openapi-import-plan-back').click(); + await page.locator('#openapi-import-file').setInputFiles({ name: 'empty-ru.yaml', mimeType: 'application/yaml', buffer: Buffer.from('') }); + await expect(status).toContainText('пуст'); + await page.locator('#openapi-import-file').setInputFiles({ name: 'large-ru.yaml', mimeType: 'application/yaml', buffer: Buffer.alloc(256 * 1024 + 1, 32) }); + await expect(status).toContainText('256'); + await page.locator('#openapi-import-file').setInputFiles({ name: 'invalid-ru.yaml', mimeType: 'application/yaml', buffer: Buffer.from('openapi: [') }); + await page.locator('#openapi-import-preview').click(); + await expect(status).toContainText('не является корректным'); + await page.locator('#openapi-import-file').setInputFiles({ name: 'no-methods-ru.yaml', mimeType: 'application/yaml', buffer: Buffer.from("openapi: 3.0.3\ninfo: {title: Empty, version: '1'}\npaths: {}\n") }); + await page.locator('#openapi-import-preview').click(); + await expect(status).toContainText('нет методов для импорта'); + expect(previewCalls).toBe(7); + expect(revalidationCalls).toBe(3); +}); + +// AC-13: end-to-end upload regression across valid, invalid, empty, oversized +// and no-method documents, with no Operations created before Apply. +test('[P1] AC-13 real upload round-trip validates YAML and rejects invalid inputs without Operation mutations', async ({ page }) => { + const prefix = uniqueName('preview_upload'); + await openImportModal(page, 'en'); + const workspace = await getCurrentWorkspace(page); + expect(workspace && workspace.id).toBeTruthy(); + const readOperations = async () => page.evaluate(async (workspaceId) => window.CrankApi.listOperations(workspaceId), workspace.id); + const operationSignature = (result) => ({ + total: result.total, + items: result.items.map((item) => ({ id: item.id, name: item.name, operation_id: item.operation_id, version: item.version })), + }); + const baseline = operationSignature(await readOperations()); + let previewPosts = 0; + let operationPosts = 0; + page.on('request', (request) => { + const url = new URL(request.url()); + if (request.method() === 'POST' && url.pathname.endsWith('/imports/openapi/preview')) previewPosts += 1; + if (request.method() === 'POST' && /\/operations\/?$/.test(url.pathname)) operationPosts += 1; + }); + + // A YAML key containing quotes exercises operation-key rendering without CSS-selector interpolation. + const specialPath = '/' + prefix + '-"quoted"-path'; + const validYaml = [ + 'openapi: 3.0.3', + "info: { title: 'Preview local round trip', version: '1' }", + "servers: [{ url: 'https://api.example.test' }]", + 'paths:', + " '" + specialPath + "':", + ' post:', + ' operationId: ' + prefix + '_special', + ' responses:', + " '200': { description: OK }", + '', + ].join('\n'); + await page.locator('#openapi-import-file').setInputFiles({ + name: 'valid.yaml', + mimeType: 'application/yaml', + buffer: Buffer.from(validYaml), + }); + await page.locator('#openapi-import-preview').click(); + await expect(page.locator('#openapi-import-preview-panel')).toBeVisible(); + const row = page.locator('.openapi-import-operation').first(); + await expect(row).toContainText(specialPath); + await expect(row).toContainText('POST'); + await expect(page.locator('[data-openapi-operation]').first()).toBeChecked(); + await expect(row.locator('[data-testid="openapi-import-operation-readiness"]')).toHaveAccessibleName('Actionable'); + + // Malformed documents are rejected by the real preview endpoint. + await page.locator('#openapi-import-file').setInputFiles({ + name: 'invalid.yaml', mimeType: 'application/yaml', buffer: Buffer.from('openapi: [') + }); + await page.locator('#openapi-import-preview').click(); + await expect(page.locator('#openapi-import-status')).toContainText(localized('not a valid', 'некоррект')); + + // Empty and oversized files are rejected locally and must not POST previews. + await page.locator('#openapi-import-file').setInputFiles({ + name: 'empty.yaml', + mimeType: 'application/yaml', + buffer: Buffer.from(''), + }); + await expect(page.locator('#openapi-import-status')).toContainText(localized('empty', 'пуст')); + await page.locator('#openapi-import-preview').click(); + await expect(page.locator('#openapi-import-status')).toContainText(localized('empty', 'пуст')); + await page.locator('#openapi-import-file').setInputFiles({ + name: 'oversized.yaml', mimeType: 'application/yaml', buffer: Buffer.alloc(256 * 1024 + 1, 32), + }); + await expect(page.locator('#openapi-import-status')).toContainText('256'); + await page.locator('#openapi-import-preview').click(); + await expect(page.locator('#openapi-import-status')).toContainText('256'); + + // A syntactically valid document with no supported methods reaches the real endpoint. + await page.locator('#openapi-import-file').setInputFiles({ + name: 'no-methods.yaml', + mimeType: 'application/yaml', + buffer: Buffer.from("openapi: 3.0.3\ninfo: { title: Empty, version: '1' }\npaths: {}\n"), + }); + await page.locator('#openapi-import-preview').click(); + await expect(page.locator('#openapi-import-status')).toContainText(localized('does not contain importable methods', 'нет поддерживаемых методов')); + + expect(previewPosts).toBe(3); + expect(operationPosts).toBe(0); + const after = operationSignature(await readOperations()); + expect(after).toEqual(baseline); +}); diff --git a/apps/ui/tests/e2e/openapi-preview-reference.spec.js b/apps/ui/tests/e2e/openapi-preview-reference.spec.js new file mode 100644 index 0000000..e17cae8 --- /dev/null +++ b/apps/ui/tests/e2e/openapi-preview-reference.spec.js @@ -0,0 +1,273 @@ +// Operator-run AC-11 evidence against a Reference Deployment. This spec is +// intentionally separate from the local/mocked Playwright matrix. +const fs = require('node:fs'); +const { test, expect } = require('@playwright/test'); +const { localized, login } = require('./helpers'); + +// Remote operator credentials must not enter retry artifacts or failure captures. +test.use({ trace: 'off', video: 'off', screenshot: 'off' }); +test.describe.configure({ retries: 0 }); + +const referenceBaseUrl = process.env.PLAYWRIGHT_BASE_URL; +const SAMPLE_COUNT = 20; +const OPERATION_COUNT = 2000; +const MAX_UPLOAD_BYTES = 256 * 1024; +const MAX_P95_MS = 2000; + +function openApiDocument(operationCount) { + const lines = [ + 'openapi: 3.0.3', + 'info:', + ' title: Crank Reference Preview Benchmark', + ' version: "1.0.0"', + 'servers:', + ' - url: https://api.example.test', + 'paths:', + ]; + + for (let index = 0; index < operationCount; index += 1) { + lines.push(` /op-${index}:`); + lines.push(' get:'); + lines.push(' responses:'); + lines.push(' "200":'); + lines.push(' description: OK'); + } + + return Buffer.from(lines.join('\n') + '\n', 'utf8'); +} + +function percentile95(samples) { + const sorted = [...samples].sort((left, right) => left - right); + return sorted[Math.ceil(sorted.length * 0.95) - 1]; +} + +function safeReferenceOrigin(rawUrl) { + const url = new URL(rawUrl); + if (!['http:', 'https:'].includes(url.protocol)) { + throw new Error('PLAYWRIGHT_BASE_URL must use http or https'); + } + if (url.username || url.password || url.search || url.hash) { + throw new Error('PLAYWRIGHT_BASE_URL must not contain credentials, query parameters, or fragments'); + } + if (['localhost', '127.0.0.1', '::1'].includes(url.hostname)) { + throw new Error('AC-11 Reference benchmark requires a remote PLAYWRIGHT_BASE_URL'); + } + return url.origin; +} + +function readReferenceManifest(manifestPath) { + if (!manifestPath) { + throw new Error('CRANK_AC11_REFERENCE_ENV_JSON is required when PLAYWRIGHT_BASE_URL is set'); + } + + let manifest; + try { + manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); + } catch (_error) { + throw new Error('CRANK_AC11_REFERENCE_ENV_JSON must point to a readable valid JSON manifest'); + } + + const deployment = manifest && manifest.deployment; + const loadGenerator = manifest && manifest.load_generator; + const browser = manifest && manifest.browser; + const nonempty = (value) => typeof value === 'string' && value.trim().length > 0; + const finiteNumber = (value) => typeof value === 'number' && Number.isFinite(value); + const versionHasMajor = (value, major) => nonempty(value) && new RegExp(`^${major}(?:\\.|$)`).test(value.trim()); + + if (!deployment || !loadGenerator || !browser) { + throw new Error('Reference manifest requires deployment, load_generator, and browser objects'); + } + for (const [name, host] of [['deployment', deployment], ['load_generator', loadGenerator], ['browser', browser]]) { + if (!nonempty(host.host_id)) throw new Error(`Reference manifest ${name}.host_id is required`); + } + if (deployment.host_id.trim() === loadGenerator.host_id.trim() + || deployment.host_id.trim() === browser.host_id.trim()) { + throw new Error('Reference manifest requires deployment and load generator/browser on separate hosts'); + } + if (!nonempty(deployment.cpu_model) || !nonempty(deployment.storage_type) + || deployment.storage_type.trim().toLowerCase() !== 'ssd' + || !finiteNumber(deployment.cpu_cores) + || !finiteNumber(deployment.ram_gib) || !finiteNumber(deployment.ssd_iops) + || !finiteNumber(deployment.ssd_throughput_mb_s) || !finiteNumber(deployment.ssd_capacity_gb) + || !finiteNumber(deployment.lan_mbps) + || !versionHasMajor(deployment.postgres_version, 16) + || !versionHasMajor(deployment.valkey_version, 8)) { + throw new Error('Reference manifest is missing valid CPU, RAM, database, SSD, or LAN fields'); + } + if (deployment.cpu_cores !== 4 || deployment.ram_gib !== 8 + || deployment.ssd_capacity_gb < 100 || deployment.ssd_iops < 3000 + || deployment.ssd_throughput_mb_s < 100 + || deployment.lan_mbps < 1000) { + throw new Error('Reference deployment must meet 4 CPU / 8 GiB RAM, SSD 3000 IOPS / 100 MB/s, and 1 Gbit LAN'); + } + if (!finiteNumber(loadGenerator.cpu_cores) || !finiteNumber(loadGenerator.ram_gib) + || loadGenerator.cpu_cores !== 4 || loadGenerator.ram_gib !== 8) { + throw new Error('Reference load_generator must have 4 CPU and 8 GiB RAM'); + } + + // Emit only the fields needed for benchmark interpretation. Do not copy + // arbitrary manifest keys (which could contain credentials) into reports. + return { + provenance: 'operator_manifest', + deployment: { + cpu_model: deployment.cpu_model.trim(), + cpu_cores: deployment.cpu_cores, + ram_gib: deployment.ram_gib, + postgres_version: deployment.postgres_version.trim(), + valkey_version: deployment.valkey_version.trim(), + storage_type: 'SSD', + ssd_capacity_gb: deployment.ssd_capacity_gb, + ssd_iops: deployment.ssd_iops, + ssd_throughput_mb_s: deployment.ssd_throughput_mb_s, + lan_mbps: deployment.lan_mbps, + }, + load_generator: { cpu_cores: loadGenerator.cpu_cores, ram_gib: loadGenerator.ram_gib }, + browser_host_separate_from_deployment: true, + }; +} + +test('[P1][reference] AC-11 measures 20 real 2000-operation preview round trips', async ({ page }, testInfo) => { + test.skip(!referenceBaseUrl, 'Set PLAYWRIGHT_BASE_URL to a Reference Deployment to run AC-11 evidence'); + test.setTimeout(300_000); + + expect(process.env.PLAYWRIGHT_SKIP_WEB_SERVER).toBe('1'); + const referenceOrigin = safeReferenceOrigin(referenceBaseUrl); + const referenceManifest = readReferenceManifest(process.env.CRANK_AC11_REFERENCE_ENV_JSON); + const yaml = openApiDocument(OPERATION_COUNT); + expect(yaml.byteLength).toBeLessThan(MAX_UPLOAD_BYTES); + + await login(page); + await page.waitForFunction(() => Boolean(document.querySelector('[data-testid="onboarding-dismiss"]'))); + await page.locator('[data-testid="onboarding-dismiss"]').click(); + await expect(page.locator('#crank-onboarding-panel')).toBeHidden(); + await page.evaluate(() => window.setLang('en')); + await page.getByRole('button', { name: localized('Import OpenAPI', 'Импорт OpenAPI') }).click(); + await expect(page.locator('#openapi-import-modal')).toBeVisible(); + await page.locator('#openapi-import-file').setInputFiles({ + name: 'reference-preview-2000.yaml', + mimeType: 'application/yaml', + buffer: yaml, + }); + + const previewButton = page.locator('#openapi-import-preview'); + const createButton = page.locator('#openapi-import-create'); + const rows = page.locator('.openapi-import-operation'); + const samplesMs = []; + let browserEnvironment; + + // Warm the preview once before timing. Warm-up still uses the real remote + // preview API. + const warmupResponsePromise = page.waitForResponse((response) => + response.request().method() === 'POST' + && response.url().includes('/imports/openapi/preview'), + ); + await previewButton.click(); + const warmupResponse = await warmupResponsePromise; + expect(warmupResponse.status(), 'warm-up preview status').toBe(200); + expect(new URL(warmupResponse.url()).origin).toBe(referenceOrigin); + await expect(page.locator('[data-testid="openapi-import-page-status"]')).toContainText('2000'); + await expect(createButton).toBeEnabled(); + + const previewResponses = []; + page.on('response', (response) => { + if (response.request().method() === 'POST' && response.url().includes('/imports/openapi/preview')) { + previewResponses.push({ status: response.status(), url: response.url() }); + } + }); + + for (let sampleIndex = 0; sampleIndex < SAMPLE_COUNT; sampleIndex += 1) { + await expect(previewButton).toBeEnabled(); + await page.evaluate((index) => { + const measurements = window.__ac11Measurements || (window.__ac11Measurements = []); + const sample = { start: null, elapsed: null }; + measurements[index] = sample; + const ready = () => { + const panel = document.querySelector('#openapi-import-preview-panel'); + const button = document.querySelector('#openapi-import-preview'); + const status = document.querySelector('[data-testid="openapi-import-page-status"]'); + const create = document.querySelector('#openapi-import-create'); + const rowCount = document.querySelectorAll('.openapi-import-operation').length; + if (sample.start === null || !button || button.disabled || !panel || panel.hidden + || !status || !status.textContent.includes('2000') || !create || create.disabled + || rowCount < 1 || rowCount > 100) return; + sample.elapsed = Number((performance.now() - sample.start).toFixed(3)); + observer.disconnect(); + }; + const observer = new MutationObserver(ready); + observer.observe(document.body, { childList: true, subtree: true, attributes: true, characterData: true }); + document.addEventListener('click', (event) => { + if (event.target.closest('#openapi-import-preview')) sample.start = performance.now(); + }, { capture: true, once: true }); + }, sampleIndex); + const responsePromise = page.waitForResponse((response) => + response.request().method() === 'POST' + && response.url().includes('/imports/openapi/preview'), + ); + await previewButton.click(); + const previewResponse = await responsePromise; + expect(previewResponse.status(), `preview sample ${sampleIndex + 1} status`).toBe(200); + expect(new URL(previewResponse.url()).origin).toBe(referenceOrigin); + + await page.waitForFunction((index) => { + const sample = window.__ac11Measurements && window.__ac11Measurements[index]; + return sample && sample.elapsed !== null; + }, sampleIndex, { polling: 'raf' }); + const elapsed = await page.evaluate((index) => window.__ac11Measurements[index].elapsed, sampleIndex); + + await expect(page.locator('#openapi-import-preview-panel')).toBeVisible(); + await expect(page.locator('[data-testid="openapi-import-page-status"]')).toContainText('2000'); + await expect(rows.first()).toBeVisible(); + expect(await rows.count()).toBeGreaterThan(0); + expect(await rows.count()).toBeLessThanOrEqual(100); + await expect(createButton).toBeEnabled(); + + samplesMs.push(elapsed); + browserEnvironment = await page.evaluate(() => ({ + user_agent: navigator.userAgent, + platform: navigator.platform, + language: navigator.language, + hardware_concurrency: navigator.hardwareConcurrency || null, + viewport: { width: innerWidth, height: innerHeight }, + timezone: Intl.DateTimeFormat().resolvedOptions().timeZone, + })); + } + + expect(previewResponses).toHaveLength(SAMPLE_COUNT); + expect(previewResponses.every((item) => item.status === 200)).toBe(true); + const p95Ms = percentile95(samplesMs); + const report = { + benchmark: 'story-2.12-ac-11-reference-preview', + generated_at: new Date().toISOString(), + result: { sample_count: samplesMs.length, p95_ms: p95Ms, threshold_ms: MAX_P95_MS }, + workload: { + operations: OPERATION_COUNT, + yaml_bytes: yaml.byteLength, + max_yaml_bytes: MAX_UPLOAD_BYTES, + preview_http_statuses: previewResponses.map((item) => item.status), + rendered_operation_rows: await rows.count(), + max_rendered_operation_rows: 100, + enabled_interaction: 'Create button enabled after preview', + interaction_enabled: true, + measurement_scope: 'click through real HTTP request, parsing, populated first page, and enabled Create button', + }, + samples_ms: samplesMs, + environment: { + reference_origin: referenceOrigin, + playwright_base_url_configured: true, + playwright_skip_web_server: process.env.PLAYWRIGHT_SKIP_WEB_SERVER === '1', + node_version: process.version, + os_platform: process.platform, + os_arch: process.arch, + browser: browserEnvironment, + reference_manifest: referenceManifest, + }, + }; + + const rawReport = JSON.stringify(report, null, 2); + await testInfo.attach('ac11-reference-preview-report.json', { + body: Buffer.from(rawReport), + contentType: 'application/json', + }); + console.log('AC11_REFERENCE_PREVIEW_REPORT ' + JSON.stringify(report)); + expect(p95Ms, 'Reference preview p95 must be at most 2 seconds').toBeLessThanOrEqual(MAX_P95_MS); +}); diff --git a/apps/ui/tests/e2e/operations.spec.js b/apps/ui/tests/e2e/operations.spec.js index 8d2cb95..ffd5583 100644 --- a/apps/ui/tests/e2e/operations.spec.js +++ b/apps/ui/tests/e2e/operations.spec.js @@ -142,7 +142,9 @@ paths: const request = await previewRequest; expect(request.headers()['content-type']).toMatch(/^multipart\/form-data; boundary=/i); await expect(page.locator('#openapi-import-preview-panel')).toBeVisible(); - await expect(page.locator('.openapi-import-document-findings')).toContainText(/base URL/i); + const documentFindings = page.locator('.openapi-import-document-findings'); + await documentFindings.locator('summary').click(); + await expect(documentFindings).toContainText(/base URL/i); await expect(page.locator('.openapi-import-group').filter({ hasText: 'currency' })).toBeVisible(); const importedOperation = page.locator('.openapi-import-operation').filter({ hasText: 'Получить курсы валют' }); await expect(importedOperation).toBeVisible(); @@ -159,6 +161,7 @@ paths: await page.locator('#openapi-import-search').fill('status'); await expect(page.locator('.openapi-import-operation:visible')).toHaveCount(1); await expect(page.locator('.openapi-import-operation:visible').filter({ hasText: 'Проверить статус' })).toBeVisible(); + await page.locator('#openapi-import-partial-mode').check(); await page.locator('#openapi-import-clear-visible').click(); await expect(page.locator('#openapi-import-selection')).toContainText(localized('Selected: 1', 'Выбрано: 1')); await page.locator('#openapi-import-search').fill(''); @@ -174,7 +177,9 @@ paths: await expect(page.locator('#openapi-import-result')).toContainText(localized('Import plan result', 'Результат плана импорта')); await expect(page.locator('.openapi-import-plan-outcomes')).toContainText(operationId); await expect(page.locator('.openapi-import-plan-outcomes')).toContainText('POST /v1/rates/{date}'); - await expect(importedOperation.locator('.openapi-import-findings')).toContainText(localized('tool description is too short', 'Описание инструмента слишком короткое')); + const operationFindings = importedOperation.locator('.openapi-import-findings'); + await operationFindings.locator('summary').click(); + await expect(operationFindings).toContainText(localized('tool description is too short', 'Описание инструмента слишком короткое')); await expect(page.locator('tbody')).toContainText(new RegExp(operationId, 'i')); await expect(page.locator('tbody')).not.toContainText(new RegExp(statusOperationId, 'i')); await expect(page.locator('body')).not.toContainText(sourceCanary); @@ -272,7 +277,7 @@ test('OpenAPI upload recovers from pagehide and a preview server error', async ( buffer: Buffer.from('openapi: 3.0.3'), }); await page.locator('#openapi-import-preview').click(); - await expect(page.locator('#openapi-import-status')).toContainText(localized('Uploading and parsing', 'Загружаю и разбираю')); + await expect(page.locator('#openapi-import-status')).toContainText(localized('Uploading the document', 'Загружаю документ')); await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }))); await expect(page.locator('#openapi-import-status')).toHaveText(''); diff --git a/crates/crank-import/src/rest/http_methods.rs b/crates/crank-import/src/rest/http_methods.rs index 3633857..9fd3ba8 100644 --- a/crates/crank-import/src/rest/http_methods.rs +++ b/crates/crank-import/src/rest/http_methods.rs @@ -21,5 +21,6 @@ pub(super) fn invalid_path_item() -> ImportFinding { severity: ImportFindingSeverity::Error, message: "Path Item имеет неверную структуру и не был интерпретирован.".to_owned(), operation_key: None, + source_location: None, } } diff --git a/crates/crank-import/src/rest/legacy_payload.rs b/crates/crank-import/src/rest/legacy_payload.rs index e950ea2..7c168da 100644 --- a/crates/crank-import/src/rest/legacy_payload.rs +++ b/crates/crank-import/src/rest/legacy_payload.rs @@ -127,6 +127,8 @@ pub fn candidate_from_operation( key: operation.key.clone(), method: operation.method, path: operation.path.clone(), + status: String::new(), + source_location: operation.source_location.clone(), security_requirements: Default::default(), security_schemes: BTreeMap::new(), operation_id: operation.operation_id.clone(), diff --git a/crates/crank-import/src/rest/mod.rs b/crates/crank-import/src/rest/mod.rs index 14d55fa..76d65b3 100644 --- a/crates/crank-import/src/rest/mod.rs +++ b/crates/crank-import/src/rest/mod.rs @@ -27,10 +27,10 @@ mod swagger2_findings; pub use model::{ ExternalDocumentSnapshot, HISTORICAL_NORMALIZER_VERSION, HISTORICAL_PROJECTION_VERSION, - ImportFinding, ImportFindingSeverity, ImportGroupPreview, ImportOperationCandidate, - ImportPreview, ImportSourcePreview, NORMALIZER_VERSION, NormalizationConfig, NormalizedFinding, - NormalizedIr, NormalizedOperation, NormalizedParameter, NormalizedReference, - NormalizedRequestBodyVariant, NormalizedResponseVariant, NormalizedSchema, + ImportFinding, ImportFindingSeverity, ImportGroupPreview, ImportNameConflict, + ImportOperationCandidate, ImportPreview, ImportSourcePreview, NORMALIZER_VERSION, + NormalizationConfig, NormalizedFinding, NormalizedIr, NormalizedOperation, NormalizedParameter, + NormalizedReference, NormalizedRequestBodyVariant, NormalizedResponseVariant, NormalizedSchema, NormalizedSchemaConstraints, NormalizedSchemaKind, NormalizedSecurityRequirements, NormalizedSecurityScheme, NormalizedSecuritySchemeKind, PROJECTION_VERSION, ResolvedReferenceEdge, ResolvedReferenceGraph, ResolvedReferenceNode, RestImportCandidate, diff --git a/crates/crank-import/src/rest/model.rs b/crates/crank-import/src/rest/model.rs index 648aac6..1bfeca5 100644 --- a/crates/crank-import/src/rest/model.rs +++ b/crates/crank-import/src/rest/model.rs @@ -10,7 +10,7 @@ use serde_json::Value; /// deliberately travel with an import job: changing either contract must not /// silently reinterpret a pending preview. pub const NORMALIZER_VERSION: &str = "normalized-ir-v5"; -pub const PROJECTION_VERSION: &str = "preview-v5"; +pub const PROJECTION_VERSION: &str = "preview-v6"; pub const HISTORICAL_NORMALIZER_VERSION: &str = "normalized-ir-v4"; pub const HISTORICAL_PROJECTION_VERSION: &str = "preview-v4"; @@ -496,6 +496,10 @@ pub struct ImportFinding { pub message: String, #[serde(default, skip_serializing_if = "Option::is_none")] pub operation_key: Option, + /// RFC 6901 source pointer of the finding. Optional so preview payloads + /// persisted before this field was introduced still deserialize. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub source_location: Option, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] @@ -514,6 +518,17 @@ pub struct ImportPreview { pub groups: Vec, #[serde(default)] pub findings: Vec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub conflicts: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct ImportNameConflict { + pub operation_key: String, + pub conflict_type: String, + pub proposed_name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub source_location: Option, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] @@ -528,6 +543,13 @@ pub struct ImportOperationCandidate { pub key: String, pub method: HttpMethod, pub path: String, + /// Workspace-aware readiness is attached by the API after immutable replay. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub status: String, + /// RFC 6901 pointer of the source operation. Optional so preview payloads + /// persisted before this field was introduced still deserialize. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub source_location: Option, #[serde( default, skip_serializing_if = "NormalizedSecurityRequirements::is_empty" @@ -583,6 +605,10 @@ pub struct RestImportOperation { pub key: String, pub method: HttpMethod, pub path: String, + /// Authoritative RFC 6901 pointer of the operation when it was produced by + /// the normalizer. Parser state only; never persisted. + #[serde(skip)] + pub source_location: Option, #[serde( default, skip_serializing_if = "NormalizedSecurityRequirements::is_empty" diff --git a/crates/crank-import/src/rest/normalize_projection.rs b/crates/crank-import/src/rest/normalize_projection.rs index e99b7ad..addb0f1 100644 --- a/crates/crank-import/src/rest/normalize_projection.rs +++ b/crates/crank-import/src/rest/normalize_projection.rs @@ -23,6 +23,7 @@ pub(super) fn preview_from_ir(ir: &crate::rest::model::NormalizedIr) -> ImportPr severity: finding.severity.clone(), message: finding.message.clone(), operation_key: finding.operation_key.clone(), + source_location: Some(finding.location.clone()), }) .collect(); preview_from_operations( @@ -99,6 +100,7 @@ fn preview_from_operations<'a>( source: source.clone(), groups: groups.into_values().collect(), findings, + conflicts: Vec::new(), } } @@ -107,6 +109,7 @@ pub(super) fn operation_from_normalized(operation: &NormalizedOperation) -> Rest key: operation.key.clone(), method: operation.method, path: operation.path.clone(), + source_location: Some(operation.location.clone()), security_requirements: operation.security_requirements.clone(), operation_id: operation.operation_id.clone(), summary: operation.summary.clone(), @@ -162,6 +165,7 @@ pub(super) fn operation_from_normalized(operation: &NormalizedOperation) -> Rest severity: finding.severity.clone(), message: finding.message.clone(), operation_key: finding.operation_key.clone(), + source_location: Some(finding.location.clone()), }) .collect(), internal_finding_locations: Vec::new(), diff --git a/crates/crank-import/src/rest/openapi3.rs b/crates/crank-import/src/rest/openapi3.rs index ca837f2..1e8946a 100644 --- a/crates/crank-import/src/rest/openapi3.rs +++ b/crates/crank-import/src/rest/openapi3.rs @@ -170,6 +170,7 @@ fn parse_document_v2(root: &Value) -> Result Result) -> ImportFinding severity: ImportFindingSeverity::Warning, message: message.into(), operation_key: None, + source_location: None, } } @@ -17,6 +18,7 @@ pub fn document_blocker(code: &str, message: impl Into) -> ImportFinding severity: ImportFindingSeverity::Error, message: message.into(), operation_key: None, + source_location: None, } } @@ -30,6 +32,7 @@ pub fn operation_finding( severity: ImportFindingSeverity::Warning, message: message.into(), operation_key: Some(operation_key.to_owned()), + source_location: None, } } @@ -43,6 +46,7 @@ pub fn operation_info( severity: ImportFindingSeverity::Info, message: message.into(), operation_key: Some(operation_key.to_owned()), + source_location: None, } } @@ -125,7 +129,7 @@ pub fn operation_recommendations(operation: &RestImportOperation) -> Vec, + operation: &RestImportOperation, +) -> Vec { + for finding in &mut findings { + if finding.source_location.is_none() { + finding.source_location = operation.source_location.clone(); + } + } findings } diff --git a/crates/crank-import/src/rest/swagger2.rs b/crates/crank-import/src/rest/swagger2.rs index bc70a2f..2bff41e 100644 --- a/crates/crank-import/src/rest/swagger2.rs +++ b/crates/crank-import/src/rest/swagger2.rs @@ -169,6 +169,7 @@ fn parse_document_v2(root: &Value) -> Result Result Result { }) } -/// Derives the canonical plan digest: the lowercase SHA-256 of the payload -/// serialized to its deterministic byte form. `serde_json::Value` object keys -/// are ordered (BTreeMap-backed map), so `to_vec` is stable across calls and -/// platforms — the digest is therefore reproducible for byte-identical -/// material without requiring a client-supplied digest. -fn plan_digest_from_payload(payload: &Value) -> Result { - if !payload.is_object() { - return Err(RegistryError::InvalidImportPlan { field: "payload" }); - } - let canonical = serde_json::to_vec(payload)?; - if canonical.len() > MAX_IMPORT_PLAN_PAYLOAD_BYTES { - return Err(RegistryError::InvalidImportPlan { field: "payload" }); - } - Ok(format!("{:x}", Sha256::digest(canonical))) -} - fn validate_plan_id(id: &ImportPlanId) -> Result<(), RegistryError> { if !(1..=MAX_IMPORT_PLAN_ID_BYTES).contains(&id.as_str().len()) { return Err(RegistryError::InvalidImportPlan { field: "id" }); @@ -936,6 +962,7 @@ fn plan_replay_outcome( ) -> Result { let stored = map_import_plan(&existing)?; let replay = stored.digest == digest + && stored.payload == *request.payload && stored.job_id == *request.job_id && stored.created_at == created_at && stored.expires_at == expires_at; diff --git a/crates/crank-registry/src/postgres/import_job/catalog.rs b/crates/crank-registry/src/postgres/import_job/catalog.rs new file mode 100644 index 0000000..19f2def --- /dev/null +++ b/crates/crank-registry/src/postgres/import_job/catalog.rs @@ -0,0 +1,68 @@ +use super::*; + +// A bounded metadata read, independent of the size of stored schemas/Drafts. +const MAX_IMPORT_CATALOG_ENTRIES: i64 = 10_000; + +impl PostgresRegistry { + pub async fn list_import_catalog_names( + &self, + workspace_id: &WorkspaceId, + ) -> Result, RegistryError> { + let names = sqlx::query_scalar::<_, String>( + "select name from operations where workspace_id = $1 order by name limit $2", + ) + .bind(workspace_id.as_str()) + .bind(MAX_IMPORT_CATALOG_ENTRIES + 1) + .fetch_all(&self.pool) + .await?; + if names.len() > MAX_IMPORT_CATALOG_ENTRIES as usize { + return Err(RegistryError::InvalidImportPlan { + field: "catalog_revision_limit", + }); + } + Ok(names) + } + /// Deterministic workspace catalog identity for naming and version targets. + /// Referenced authentication state is separately bound in plan snapshots. + pub async fn import_catalog_revision( + &self, + workspace_id: &WorkspaceId, + ) -> Result { + catalog_revision(&self.pool, workspace_id, false).await + } +} + +pub(super) async fn catalog_revision<'c, E>( + executor: E, + workspace_id: &WorkspaceId, + lock: bool, +) -> Result +where + E: Executor<'c, Database = Postgres>, +{ + let query = if lock { + "select jsonb_build_array(id, name, protocol, status, current_draft_version, latest_published_version) as metadata + from operations where workspace_id = $1 order by id limit $2 for share" + } else { + "select jsonb_build_array(id, name, protocol, status, current_draft_version, latest_published_version) as metadata + from operations where workspace_id = $1 order by id limit $2" + }; + let rows = sqlx::query(query) + .bind(workspace_id.as_str()) + .bind(MAX_IMPORT_CATALOG_ENTRIES + 1) + .fetch_all(executor) + .await?; + if rows.len() > MAX_IMPORT_CATALOG_ENTRIES as usize { + return Err(RegistryError::InvalidImportPlan { + field: "catalog_revision_limit", + }); + } + let metadata = rows + .iter() + .map(|row| row.try_get::("metadata")) + .collect::, _>>()?; + Ok(format!( + "{:x}", + Sha256::digest(serde_json::to_vec(&metadata)?) + )) +} diff --git a/crates/crank-registry/src/postgres/import_job/plan_apply.rs b/crates/crank-registry/src/postgres/import_job/plan_apply.rs index d9c5851..cfafa5f 100644 --- a/crates/crank-registry/src/postgres/import_job/plan_apply.rs +++ b/crates/crank-registry/src/postgres/import_job/plan_apply.rs @@ -10,6 +10,7 @@ use std::collections::{BTreeMap, BTreeSet}; mod material; mod mutations; +mod revalidate; mod verify; use material::*; @@ -20,7 +21,7 @@ const PLAN_PAYLOAD_SCHEMA_VERSION: &str = "import-plan-v1"; const APPLY_REPORT_SCHEMA_VERSION: &str = "import-plan-apply-report-v1"; /// Same upper bound as plan creation keeps the report compatible with every /// plan that was accepted: at most this many candidates / names / targets. -const MAX_IMPORT_PLAN_KEYS: usize = 512; +const MAX_IMPORT_PLAN_KEYS: usize = 2_000; const MAX_IMPORT_PLAN_KEY_BYTES: usize = 4_096; const MAX_IMPORT_PLAN_NAME_BYTES: usize = 256; const MAX_IMPORT_PLAN_ID_REF_BYTES: usize = 128; @@ -30,10 +31,38 @@ const MAX_IMPORT_PLAN_IDEMPOTENCY_KEY_BYTES: usize = 128; /// Bound for the serialized apply report. Must accommodate a full accepted /// plan: report entries carry only key/name/ids (already bounded) while the /// plan payload — which carries far more per candidate — is capped at -/// `MAX_IMPORT_PLAN_PAYLOAD_BYTES` (4 MiB) at creation. This keeps every +/// `MAX_IMPORT_PLAN_PAYLOAD_BYTES` (16 MiB) at creation. This keeps every /// accepted plan's exact outcomes inside the report without truncation. const MAX_IMPORT_PLAN_REPORT_BYTES: usize = MAX_IMPORT_PLAN_PAYLOAD_BYTES; +pub(super) fn validate_v2_creation( + request: &CreateImportPlanRequest<'_>, + digest: &str, +) -> Result<(), RegistryError> { + let fingerprint = + request + .payload + .get("fingerprint") + .ok_or(RegistryError::InvalidImportPlan { + field: "fingerprint", + })?; + let validation = ApplyImportPlanRequest { + workspace_id: request.workspace_id, + plan_id: request.id, + plan_digest: digest, + idempotency_key: "creation-validation", + verified_fingerprint: fingerprint, + applied_at: request.created_at, + }; + read_and_validate_plan_material( + request.payload, + &validation, + digest, + request.job_id.as_str(), + )?; + Ok(()) +} + /// Failure of one apply transaction: a typed registry conflict, or the /// application-row uniqueness collision that must be reconciled after the /// transaction is rolled back. @@ -254,6 +283,20 @@ async fn apply_import_plan_transaction( .await .map_err(fail)?; + if plan.schema_version == "import-plan-v2" + && plan.catalog_revision.as_deref() + != Some( + super::catalog::catalog_revision(&mut **tx, request.workspace_id, true) + .await + .map_err(fail)? + .as_str(), + ) + { + return Err(fail(RegistryError::ImportPlanFingerprintStale { + plan_id: plan_id.clone(), + })); + } + // Apply the selected candidates in deterministic order. let mut candidates: Vec<&StoredPlanCandidate> = plan.candidates.iter().collect(); candidates.sort_by(|a, b| a.key.cmp(&b.key)); diff --git a/crates/crank-registry/src/postgres/import_job/plan_apply/material.rs b/crates/crank-registry/src/postgres/import_job/plan_apply/material.rs index aa0fd39..03fde59 100644 --- a/crates/crank-registry/src/postgres/import_job/plan_apply/material.rs +++ b/crates/crank-registry/src/postgres/import_job/plan_apply/material.rs @@ -16,6 +16,16 @@ pub(super) struct StoredPlan { pub(crate) selection: StoredPlanSelection, pub(crate) counts: StoredPlanCounts, pub(crate) candidates: Vec, + #[serde(default)] + pub(crate) catalog_revision: Option, + #[serde(default)] + pub(crate) excluded_reasons: Vec, +} + +#[derive(Deserialize)] +pub(super) struct StoredExcludedReason { + pub(crate) key: String, + pub(crate) reason: String, } #[derive(Clone, Deserialize)] @@ -172,18 +182,21 @@ pub(super) fn read_and_validate_plan_material( { return Err(corrupt()); } + let v2 = payload.get("schema_version").and_then(Value::as_str) == Some("import-plan-v2"); + let selected_limit = if v2 { MAX_IMPORT_PLAN_KEYS } else { 512 }; + let all_limit = if v2 { MAX_IMPORT_PLAN_KEYS } else { 1_024 }; if payload .pointer("/selection/selected") .and_then(Value::as_array) - .is_some_and(|items| items.len() > MAX_IMPORT_PLAN_KEYS) + .is_some_and(|items| items.len() > selected_limit) || payload .pointer("/selection/all") .and_then(Value::as_array) - .is_some_and(|items| items.len() > MAX_IMPORT_PLAN_KEYS * 2) + .is_some_and(|items| items.len() > all_limit) || payload .pointer("/selection/excluded") .and_then(Value::as_array) - .is_some_and(|items| items.len() > MAX_IMPORT_PLAN_KEYS) + .is_some_and(|items| items.len() > selected_limit) { return Err(corrupt()); } @@ -219,12 +232,17 @@ pub(super) fn read_and_validate_plan_material( let plan: StoredPlan = serde_json::from_value(payload.clone()).map_err(|_| corrupt())?; // The typed material must agree with the request it is being applied for. - if plan.schema_version.as_str() != PLAN_PAYLOAD_SCHEMA_VERSION - || plan.plan_reference.as_str() != request.plan_id.as_str() + if !matches!( + plan.schema_version.as_str(), + PLAN_PAYLOAD_SCHEMA_VERSION | "import-plan-v2" + ) || plan.plan_reference.as_str() != request.plan_id.as_str() || plan.job_id != stored_job_id { return Err(corrupt()); } + if plan.schema_version == "import-plan-v2" { + super::super::semantic::validate_v2_metadata(payload).map_err(|_| corrupt())?; + } // Selection closure. if !matches!(plan.selection.mode.as_str(), "full" | "partial") { @@ -248,6 +266,30 @@ pub(super) fn read_and_validate_plan_material( let selected: BTreeSet<&String> = plan.selection.selected.iter().collect(); let excluded: BTreeSet<&String> = plan.selection.excluded.iter().collect(); let all: BTreeSet<&String> = plan.selection.all.iter().collect(); + if plan.schema_version == "import-plan-v2" { + let findings = payload + .pointer("/findings/candidates") + .and_then(Value::as_array) + .ok_or_else(corrupt)?; + let keys = findings + .iter() + .map(|item| { + if !item.get("findings").is_some_and(Value::is_array) { + return Err(corrupt()); + } + item.get("key").and_then(Value::as_str).ok_or_else(corrupt) + }) + .collect::, _>>()?; + let expected = plan + .selection + .all + .iter() + .map(String::as_str) + .collect::>(); + if keys != expected || keys.len() != findings.len() { + return Err(corrupt()); + } + } let mut union = selected.clone(); union.extend(excluded.iter()); if union != all || selected.iter().any(|key| excluded.contains(key)) { @@ -256,6 +298,34 @@ pub(super) fn read_and_validate_plan_material( if plan.selection.mode == "full" && (!excluded.is_empty() || selected != all) { return Err(corrupt()); } + if plan.schema_version == "import-plan-v2" { + let reasons = plan + .excluded_reasons + .iter() + .map(|item| &item.key) + .collect::>(); + if reasons != excluded + || reasons.len() != plan.excluded_reasons.len() + || plan.excluded_reasons.iter().any(|item| { + item.reason.is_empty() || item.reason.len() > MAX_IMPORT_PLAN_REASON_BYTES + }) + || !plan + .excluded_reasons + .windows(2) + .all(|items| items[0].key < items[1].key) + { + return Err(corrupt()); + } + } + if plan.schema_version == "import-plan-v2" + && plan.selection.mode == "partial" + && plan + .candidates + .iter() + .any(|candidate| candidate.state != "actionable") + { + return Err(corrupt()); + } let candidate_keys: BTreeSet<&String> = plan .candidates .iter() diff --git a/crates/crank-registry/src/postgres/import_job/plan_apply/mutations.rs b/crates/crank-registry/src/postgres/import_job/plan_apply/mutations.rs index 24c7d80..71474a6 100644 --- a/crates/crank-registry/src/postgres/import_job/plan_apply/mutations.rs +++ b/crates/crank-registry/src/postgres/import_job/plan_apply/mutations.rs @@ -203,7 +203,13 @@ fn excluded_outcomes(plan: &StoredPlan) -> Vec { outcome: ImportPlanCandidateOutcome::Excluded, operation_id: None, version: None, - reason: Some("not_selected".to_owned()), + reason: Some( + plan.excluded_reasons + .iter() + .find(|item| item.key == *key) + .map(|item| item.reason.clone()) + .unwrap_or_else(|| "not_selected".to_owned()), + ), }) .collect() } diff --git a/crates/crank-registry/src/postgres/import_job/plan_apply/revalidate.rs b/crates/crank-registry/src/postgres/import_job/plan_apply/revalidate.rs new file mode 100644 index 0000000..7265963 --- /dev/null +++ b/crates/crank-registry/src/postgres/import_job/plan_apply/revalidate.rs @@ -0,0 +1,114 @@ +use super::*; + +impl PostgresRegistry { + /// Reopens immutable plan evidence without applying it or writing a report. + /// The result is current validation evidence, never a promise about a later + /// Apply; Apply independently repeats its checks inside its transaction. + pub async fn revalidate_import_plan( + &self, + workspace_id: &WorkspaceId, + plan_id: &ImportPlanId, + verified_fingerprint: &Value, + ) -> Result<(), RegistryError> { + let plan = self + .get_import_plan(workspace_id, plan_id) + .await? + .ok_or_else(|| RegistryError::ImportPlanNotFound { + plan_id: plan_id.as_str().to_owned(), + })?; + let now = OffsetDateTime::now_utc(); + if plan.expires_at <= now { + return Err(RegistryError::ImportPlanExpired { + plan_id: plan_id.as_str().to_owned(), + }); + } + let request = ApplyImportPlanRequest { + workspace_id, + plan_id, + plan_digest: &plan.digest, + idempotency_key: "read-only-revalidation", + verified_fingerprint, + applied_at: &now, + }; + let material = read_and_validate_plan_material( + &plan.payload, + &request, + &plan.digest, + plan.job_id.as_str(), + )?; + let job = self + .get_import_job(workspace_id, &plan.job_id) + .await? + .ok_or_else(|| RegistryError::ImportPlanJobUnavailable { + job_id: plan.job_id.as_str().to_owned(), + })?; + if job.status != ImportJobStatus::Pending || job.expires_at <= now { + return Err(RegistryError::ImportPlanJobTerminal { + job_id: job.id.as_str().to_owned(), + }); + } + verify_job_source_consistency(&job.preview_payload, &material, plan_id.as_str())?; + let mut tx = self.pool.begin().await?; + let mut envelopes = material + .dependencies + .iter() + .chain(std::iter::once(&material.source)) + .map(|source| ImportJobSourceEnvelope { + source_id: ArtifactSourceId::new(source.source_id.clone()), + digest: ArtifactRef::parse(&source.digest).expect("material was validated"), + }) + .collect::>(); + envelopes.sort_by(|a, b| a.source_id.as_str().cmp(b.source_id.as_str())); + for envelope in &envelopes { + lock_and_verify_envelope(&mut tx, workspace_id, envelope).await?; + } + lock_and_verify_auth(&mut tx, workspace_id, &material.candidates).await?; + if material.schema_version == "import-plan-v2" + && material.catalog_revision.as_deref() + != Some( + super::super::catalog::catalog_revision(&mut *tx, workspace_id, true) + .await? + .as_str(), + ) + { + return Err(RegistryError::ImportPlanFingerprintStale { + plan_id: plan_id.as_str().to_owned(), + }); + } + for candidate in &material.candidates { + if let Some(target) = &candidate.target { + let row = sqlx::query("select name, status, current_draft_version, latest_published_version from operations where workspace_id = $1 and id = $2 for share") + .bind(workspace_id.as_str()).bind(&target.operation_id).fetch_optional(&mut *tx).await?; + let matching = match row { + Some(row) => { + row.try_get::("name")? == target.name + && deserialize_enum_text::( + row.try_get("status")?, + "status", + )? == target.expected_state.status + && row.try_get::("current_draft_version")? as u32 + == target.expected_state.current_draft_version + && row + .try_get::, _>("latest_published_version")? + .map(|value| value as u32) + == target.expected_state.latest_published_version + } + None => false, + }; + if !matching { + return Err(RegistryError::ImportPlanTargetStale { + operation_id: target.operation_id.clone(), + }); + } + } else if candidate.state == "actionable" + && operation_name_exists(&mut tx, workspace_id, &candidate.name).await? + { + return Err(RegistryError::ImportPlanNameConflict { + name: candidate.name.clone(), + }); + } + } + tx.rollback().await?; + Ok(()) + } +} diff --git a/crates/crank-registry/src/postgres/import_job/semantic.rs b/crates/crank-registry/src/postgres/import_job/semantic.rs new file mode 100644 index 0000000..b429c0e --- /dev/null +++ b/crates/crank-registry/src/postgres/import_job/semantic.rs @@ -0,0 +1,230 @@ +use super::*; + +/// Derives the canonical plan digest: the lowercase SHA-256 of the payload +/// serialized to its deterministic byte form. `serde_json::Value` object keys +/// are ordered (BTreeMap-backed map), so `to_vec` is stable across calls and +/// platforms — the digest is therefore reproducible for byte-identical +/// material without requiring a client-supplied digest. +pub(super) fn plan_digest_from_payload(payload: &Value) -> Result { + if !payload.is_object() { + return Err(RegistryError::InvalidImportPlan { field: "payload" }); + } + let limit = if payload.get("schema_version").and_then(Value::as_str) == Some("import-plan-v2") { + MAX_IMPORT_PLAN_PAYLOAD_BYTES + } else { + MAX_LEGACY_IMPORT_PLAN_PAYLOAD_BYTES + }; + if serde_json::to_vec(payload)?.len() > limit { + return Err(RegistryError::InvalidImportPlan { field: "payload" }); + } + let canonical = serde_json::to_vec(&canonical_material(payload))?; + Ok(format!("{:x}", Sha256::digest(canonical))) +} + +pub(super) fn validate_v2_sources(payload: &Value, preview: &Value) -> Result<(), RegistryError> { + let dependency_set = + |value: &Value| -> Result, RegistryError> { + Ok(dependencies_from_payload(value)? + .iter() + .map(|source| { + ( + source.source_id.as_str().to_owned(), + source.digest.as_str().to_owned(), + ) + }) + .collect()) + }; + if source_from_payload(payload)? != source_from_payload(preview)? + || dependency_set(payload)? != dependency_set(preview)? + { + return Err(RegistryError::InvalidImportPlan { field: "source" }); + } + Ok(()) +} + +/// Removes only server-generated envelope fields from v2 semantic material. +/// Paths are explicit: equally named fields in a user schema remain semantic. +pub(super) fn canonical_material(payload: &Value) -> Value { + let mut material = payload.clone(); + if payload.get("schema_version").and_then(Value::as_str) != Some("import-plan-v2") { + return material; + } + let object = material.as_object_mut().expect("validated object"); + object.remove("plan_reference"); + object.remove("job_id"); + if let Some(source) = object.get_mut("source").and_then(Value::as_object_mut) { + source.remove("source_id"); + } + if let Some(dependencies) = object.get_mut("dependencies").and_then(Value::as_array_mut) { + for dependency in dependencies.iter_mut() { + if let Some(source) = dependency.as_object_mut() { + source.remove("source_id"); + } + } + dependencies.sort_by_key(Value::to_string); + } + if let Some(candidates) = object.get_mut("candidates").and_then(Value::as_array_mut) { + for candidate in candidates { + let generated = matches!( + candidate + .pointer("/decision/action") + .and_then(Value::as_str), + Some("create" | "rename") + ); + if let Some(operation) = candidate + .get_mut("operation") + .and_then(Value::as_object_mut) + { + if generated { + operation.remove("id"); + } + operation.remove("created_at"); + operation.remove("updated_at"); + operation.remove("published_at"); + } + if let Some(snapshot) = candidate + .get_mut("auth_snapshot") + .and_then(Value::as_object_mut) + { + snapshot.remove("updated_at"); + if let Some(secrets) = snapshot.get_mut("secrets").and_then(Value::as_array_mut) { + for secret in secrets { + if let Some(secret) = secret.as_object_mut() { + secret.remove("updated_at"); + } + } + } + } + } + } + material +} + +pub(super) fn validate_v2_metadata(payload: &Value) -> Result<(), RegistryError> { + let invalid = || RegistryError::InvalidImportPlan { field: "metadata" }; + let revision = payload + .get("catalog_revision") + .and_then(Value::as_str) + .ok_or_else(invalid)?; + if revision.len() != 64 + || !revision + .bytes() + .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) + { + return Err(invalid()); + } + let matrix = payload + .get("support_matrix_version") + .and_then(Value::as_str) + .ok_or_else(invalid)?; + if matrix.is_empty() || matrix.len() > 64 { + return Err(invalid()); + } + let findings = payload + .get("findings") + .and_then(Value::as_object) + .ok_or_else(invalid)?; + if !findings.get("document").is_some_and(Value::is_array) + || !findings.get("candidates").is_some_and(Value::is_array) + { + return Err(invalid()); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::super::plan_digest_from_payload; + use serde_json::{Value, json}; + + fn payload() -> Value { + json!({ + "schema_version": "import-plan-v2", "plan_reference": "plan_a", "job_id": "job_a", + "catalog_revision": "a".repeat(64), "support_matrix_version": "1.0.2", + "source": {"source_id": "src_a", "digest": format!("sha256:{}", "b".repeat(64))}, + "dependencies": [{"source_id": "dep_a", "digest": format!("sha256:{}", "c".repeat(64))}], + "findings": {"document": [], "candidates": []}, + "selection": {"mode": "full", "selected": ["GET /a"], "excluded": [], "all": ["GET /a"]}, + "candidates": [{ + "key": "GET /a", "decision": {"action": "create"}, + "operation": {"id": "op_a", "created_at": "time_a", "updated_at": "time_a", + "input_schema": {"properties": {"id": {"default": "semantic_id"}, "created_at": {"default": "semantic_time"}}}}, + "auth_snapshot": {"profile_id": "auth_a", "updated_at": "time_a", "secrets": [ + {"id": "secret_a", "current_version": 1, "status": "active", "updated_at": "time_a"} + ]} + }] + }) + } + + #[test] + fn equivalent_v2_material_ignores_only_identity_envelope_and_runtime_instants() { + let first = payload(); + let mut second = first.clone(); + second["plan_reference"] = json!("plan_b"); + second["job_id"] = json!("job_b"); + second["source"]["source_id"] = json!("src_b"); + second["dependencies"][0]["source_id"] = json!("dep_b"); + second["candidates"][0]["operation"]["id"] = json!("op_b"); + second["candidates"][0]["operation"]["created_at"] = json!("time_b"); + second["candidates"][0]["operation"]["updated_at"] = json!("time_b"); + second["candidates"][0]["auth_snapshot"]["updated_at"] = json!("time_b"); + second["candidates"][0]["auth_snapshot"]["secrets"][0]["updated_at"] = json!("time_b"); + assert_eq!( + plan_digest_from_payload(&first).unwrap(), + plan_digest_from_payload(&second).unwrap() + ); + } + + #[test] + fn v2_semantic_changes_and_schema_fields_named_like_runtime_fields_change_digest() { + let first = payload(); + for pointer in [ + "/catalog_revision", + "/support_matrix_version", + "/source/digest", + "/candidates/0/decision/action", + "/candidates/0/auth_snapshot/secrets/0/current_version", + "/candidates/0/operation/input_schema/properties/id/default", + "/candidates/0/operation/input_schema/properties/created_at/default", + ] { + let mut changed = first.clone(); + *changed.pointer_mut(pointer).unwrap() = json!("changed"); + assert_ne!( + plan_digest_from_payload(&first).unwrap(), + plan_digest_from_payload(&changed).unwrap(), + "{pointer}" + ); + } + let mut target = first.clone(); + target["candidates"][0]["decision"]["action"] = json!("new_version"); + let mut changed_target = target.clone(); + changed_target["candidates"][0]["operation"]["id"] = json!("different_existing_target"); + assert_ne!( + plan_digest_from_payload(&target).unwrap(), + plan_digest_from_payload(&changed_target).unwrap() + ); + } + + #[test] + fn legacy_payload_digest_still_covers_runtime_and_identity_fields() { + let mut first = payload(); + first["schema_version"] = json!("import-plan-v1"); + let mut second = first.clone(); + second["plan_reference"] = json!("other"); + assert_ne!( + plan_digest_from_payload(&first).unwrap(), + plan_digest_from_payload(&second).unwrap() + ); + } + + #[test] + fn v2_payload_budget_grows_without_changing_the_legacy_budget() { + let mut large = + json!({"schema_version": "import-plan-v1", "evidence": "x".repeat(5 * 1024 * 1024)}); + assert!(plan_digest_from_payload(&large).is_err()); + large["schema_version"] = json!("import-plan-v2"); + assert!(plan_digest_from_payload(&large).is_ok()); + large["evidence"] = json!("x".repeat(16 * 1024 * 1024)); + assert!(plan_digest_from_payload(&large).is_err()); + } +} diff --git a/crates/crank-registry/tests/integration/import_plan.rs b/crates/crank-registry/tests/integration/import_plan.rs index 36da024..80979f2 100644 --- a/crates/crank-registry/tests/integration/import_plan.rs +++ b/crates/crank-registry/tests/integration/import_plan.rs @@ -10,6 +10,7 @@ use time::format_description::well_known::Rfc3339; mod apply; mod create; +mod preview_v2; pub(super) fn parse_ts(value: &str) -> OffsetDateTime { OffsetDateTime::parse(value, &Rfc3339).unwrap() } diff --git a/crates/crank-registry/tests/integration/import_plan/preview_v2.rs b/crates/crank-registry/tests/integration/import_plan/preview_v2.rs new file mode 100644 index 0000000..96b355c --- /dev/null +++ b/crates/crank-registry/tests/integration/import_plan/preview_v2.rs @@ -0,0 +1,787 @@ +//! Story 2.12 evidence for v2 semantic digests, catalog drift and Apply. + +use super::super::common::{TestDatabase, test_operation}; +use super::{create_pending_openapi_job, create_workspace, parse_ts}; +use crank_artifacts::ArtifactRef; +use crank_core::{OperationStatus, WorkspaceId}; +use crank_registry::{ + ApplyImportPlanRequest, ArtifactSourceId, CreateImportJobRequest, CreateImportPlanRequest, + ImportJobId, ImportJobKind, ImportJobSourceEnvelope, ImportJobStatus, ImportPlanApplyStatus, + ImportPlanCandidateOutcome, ImportPlanId, RegistryError, +}; +use serde_json::{Value, json}; +use sha2::{Digest, Sha256}; +use time::{Duration, OffsetDateTime}; + +const SOURCE_ID: &str = "src_openapi_test"; +const SOURCE_DIGEST: &str = + "sha256:abababababababababababababababababababababababababababababababab"; + +fn fingerprint() -> Value { + json!({"importer": "registry-preview-v2-test", "preview_digest": "fp-v2-1"}) +} + +fn operation( + id: &str, + name: &str, + created_at: &str, + updated_at: &str, +) -> crank_registry::RegistryOperation { + let mut operation = test_operation(id, 1, OperationStatus::Draft); + operation.name = name.to_owned(); + operation.display_name = "Candidate display name".to_owned(); + operation.execution_config.auth_profile_ref = None; + operation.created_at = parse_ts(created_at); + operation.updated_at = parse_ts(updated_at); + operation +} + +fn v2_payload( + plan_id: &str, + job_id: &str, + source_id: &str, + operation: crank_registry::RegistryOperation, + catalog_revision: &str, +) -> Value { + let key = "candidate"; + json!({ + "schema_version": "import-plan-v2", + "plan_reference": plan_id, + "job_id": job_id, + "fingerprint": fingerprint(), + "catalog_revision": catalog_revision, + "support_matrix_version": "1.0.2", + "source": { "source_id": source_id, "digest": SOURCE_DIGEST }, + "dependencies": [], + "excluded_reasons": [], + "findings": { "document": [], "candidates": [{ "key": key, "findings": [] }] }, + "selection": { + "mode": "full", "all": [key], "selected": [key], "excluded": [] + }, + "counts": { "selected": 1, "excluded": 0, "actionable": 1, "blocked": 0 }, + "candidates": [{ + "key": key, + "name": operation.name, + "state": "actionable", + "decision": { "action": "create" }, + "findings": [], + "operation": operation + }] + }) +} + +async fn store_plan( + registry: &crank_registry::PostgresRegistry, + workspace_id: &WorkspaceId, + job_id: &ImportJobId, + plan_id: &str, + payload: &Value, + created_at: OffsetDateTime, +) -> (ImportPlanId, String) { + let plan_id = ImportPlanId::new(plan_id); + let created = registry + .create_import_plan(CreateImportPlanRequest { + id: &plan_id, + workspace_id, + job_id, + payload, + created_at: &created_at, + expires_at: &(created_at + Duration::minutes(30)), + }) + .await + .unwrap(); + (plan_id, created.digest) +} + +async fn activate_source(raw: &sqlx::PgPool, workspace_id: &WorkspaceId, now: OffsetDateTime) { + let hex = "ab".repeat(32); + sqlx::query( + "insert into artifact_blobs (digest, artifact_ref, size_bytes, created_at, updated_at) + values ($1, 'sha256:' || $1, 16, $2, $2)", + ) + .bind(&hex) + .bind(now) + .execute(raw) + .await + .unwrap(); + sqlx::query( + "insert into artifact_sources ( + workspace_id, source_id, blob_digest, mime_type, sensitivity, lifecycle, + created_at, updated_at + ) values ($1, $2, $3, 'application/yaml', 'public', 'active', $4, $4)", + ) + .bind(workspace_id.as_str()) + .bind(SOURCE_ID) + .bind(&hex) + .bind(now) + .execute(raw) + .await + .unwrap(); +} + +async fn create_job_with_source( + registry: &crank_registry::PostgresRegistry, + workspace_id: &WorkspaceId, + job_id: &str, + source_id: &str, + now: OffsetDateTime, +) -> ImportJobId { + let job_id = ImportJobId::new(job_id); + let source_id = ArtifactSourceId::new(source_id); + let digest = ArtifactRef::from_digest_hex(&"ab".repeat(32)).unwrap(); + let preview_payload = json!({ + "source": {"source_id": source_id.as_str(), "digest": digest.as_str()}, + "preview": {"source": "integration-test"} + }); + registry + .create_import_job(CreateImportJobRequest { + id: &job_id, + workspace_id, + kind: ImportJobKind::OpenApi, + source_format: "openapi", + source_version: Some("3.1.0"), + status: ImportJobStatus::Pending, + source: &ImportJobSourceEnvelope { source_id, digest }, + preview_payload: &preview_payload, + created_at: &now, + expires_at: &(now + Duration::hours(1)), + }) + .await + .unwrap(); + job_id +} + +fn raw_digest(payload: &Value) -> String { + format!("{:x}", Sha256::digest(serde_json::to_vec(payload).unwrap())) +} + +#[tokio::test] +async fn v2_digest_ignores_job_plan_generated_operation_ids_and_runtime_timestamps() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let ws = create_workspace(®istry, "ws_v2_digest").await; + let first_time = + OffsetDateTime::from_unix_timestamp(OffsetDateTime::now_utc().unix_timestamp()).unwrap(); + let second_time = first_time + Duration::minutes(2); + let first_job = + create_job_with_source(®istry, &ws, "job_v2_digest_a", "src_v2_a", first_time).await; + let second_job = + create_job_with_source(®istry, &ws, "job_v2_digest_b", "src_v2_b", second_time).await; + let revision = registry.import_catalog_revision(&ws).await.unwrap(); + let first_payload = v2_payload( + "plan_v2_digest_a", + first_job.as_str(), + "src_v2_a", + operation( + "op_generated_a", + "candidate_tool", + "2026-03-25T10:00:00Z", + "2026-03-25T10:00:00Z", + ), + &revision, + ); + let second_payload = v2_payload( + "plan_v2_digest_b", + second_job.as_str(), + "src_v2_b", + operation( + "op_generated_b", + "candidate_tool", + "2026-03-25T10:02:00Z", + "2026-03-25T10:02:00Z", + ), + &revision, + ); + + let (_, first_digest) = store_plan( + ®istry, + &ws, + &first_job, + "plan_v2_digest_a", + &first_payload, + first_time, + ) + .await; + let (_, second_digest) = store_plan( + ®istry, + &ws, + &second_job, + "plan_v2_digest_b", + &second_payload, + second_time, + ) + .await; + assert_eq!( + first_digest, second_digest, + "server identities and runtime instants must not change semantic identity" + ); + assert_eq!( + registry + .get_import_plan(&ws, &ImportPlanId::new("plan_v2_digest_a")) + .await + .unwrap() + .unwrap() + .payload, + first_payload, + "canonical hashing must leave immutable v2 evidence untouched" + ); + let mut replay_with_new_generated_id = first_payload.clone(); + replay_with_new_generated_id["candidates"][0]["operation"]["id"] = json!("op_generated_retry"); + let plan_id = ImportPlanId::new("plan_v2_digest_a"); + let conflict = registry + .create_import_plan(CreateImportPlanRequest { + id: &plan_id, + workspace_id: &ws, + job_id: &first_job, + payload: &replay_with_new_generated_id, + created_at: &first_time, + expires_at: &(first_time + Duration::minutes(30)), + }) + .await + .expect_err("replay identity still compares immutable raw payload after semantic hashing"); + assert!(matches!(conflict, RegistryError::ImportPlanConflict { .. })); + database.cleanup().await; +} + +#[tokio::test] +async fn v2_digest_changes_for_selection_name_and_conflict_decision() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let now = OffsetDateTime::now_utc(); + let ws = create_workspace(®istry, "ws_v2_semantics").await; + let job = create_pending_openapi_job( + ®istry, + &ws, + "job_v2_semantics", + now, + now + Duration::hours(1), + ) + .await; + let revision = registry.import_catalog_revision(&ws).await.unwrap(); + let base = v2_payload( + "plan_semantic_base", + job.as_str(), + SOURCE_ID, + operation( + "op_base", + "candidate_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ), + &revision, + ); + let mut changed_selection = base.clone(); + changed_selection["plan_reference"] = json!("plan_semantic_selection"); + changed_selection["selection"]["mode"] = json!("partial"); + changed_selection["selection"]["all"] = json!(["candidate", "other"]); + changed_selection["selection"]["excluded"] = json!(["other"]); + changed_selection["counts"]["excluded"] = json!(1); + changed_selection["excluded_reasons"] = json!([{"key": "other", "reason": "not_selected"}]); + changed_selection["findings"]["candidates"] = json!([ + {"key": "candidate", "findings": []}, {"key": "other", "findings": []} + ]); + let mut changed_name = base.clone(); + changed_name["plan_reference"] = json!("plan_semantic_name"); + changed_name["candidates"][0]["name"] = json!("renamed_tool"); + changed_name["candidates"][0]["operation"]["name"] = json!("renamed_tool"); + let mut changed_decision = base.clone(); + changed_decision["plan_reference"] = json!("plan_semantic_decision"); + changed_decision["candidates"][0]["decision"] = + json!({"action": "rename", "confirmed_name": "candidate_tool"}); + let mut changed_support_matrix = base.clone(); + changed_support_matrix["plan_reference"] = json!("plan_semantic_support"); + changed_support_matrix["support_matrix_version"] = json!("1.0.3"); + + let (_, digest) = store_plan(®istry, &ws, &job, "plan_semantic_base", &base, now).await; + let (_, selection_digest) = store_plan( + ®istry, + &ws, + &job, + "plan_semantic_selection", + &changed_selection, + now, + ) + .await; + let (_, name_digest) = store_plan( + ®istry, + &ws, + &job, + "plan_semantic_name", + &changed_name, + now, + ) + .await; + let (_, decision_digest) = store_plan( + ®istry, + &ws, + &job, + "plan_semantic_decision", + &changed_decision, + now, + ) + .await; + let (_, support_matrix_digest) = store_plan( + ®istry, + &ws, + &job, + "plan_semantic_support", + &changed_support_matrix, + now, + ) + .await; + assert_ne!(digest, selection_digest, "selection changes are semantic"); + assert_ne!( + digest, name_digest, + "the confirmed operation name is semantic" + ); + assert_ne!( + digest, decision_digest, + "conflict resolution choices are semantic" + ); + assert_ne!( + digest, support_matrix_digest, + "the support matrix version is semantic evidence" + ); + database.cleanup().await; +} + +#[tokio::test] +async fn legacy_v1_digest_and_stored_payload_remain_unchanged_and_readable() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let now = OffsetDateTime::now_utc(); + let ws = create_workspace(®istry, "ws_v1_compat").await; + let job = create_pending_openapi_job( + ®istry, + &ws, + "job_v1_compat", + now, + now + Duration::hours(1), + ) + .await; + let plan_id = ImportPlanId::new("plan_v1_compat"); + let payload = json!({ + "schema_version": "import-plan-v1", "plan_reference": plan_id.as_str(), "job_id": job.as_str(), + "fingerprint": {"legacy": true}, "source": {"source_id": SOURCE_ID, "digest": SOURCE_DIGEST}, + "dependencies": [], "selection": {"mode": "full", "all": ["legacy"], "selected": ["legacy"], "excluded": []}, + "counts": {"selected": 1, "excluded": 0, "actionable": 1, "blocked": 0}, + "candidates": [{"key": "legacy", "name": "legacy_tool", "state": "actionable", "decision": {"action": "create"}}] + }); + let created = registry + .create_import_plan(CreateImportPlanRequest { + id: &plan_id, + workspace_id: &ws, + job_id: &job, + payload: &payload, + created_at: &now, + expires_at: &(now + Duration::minutes(30)), + }) + .await + .unwrap(); + assert_eq!( + created.digest, + raw_digest(&payload), + "legacy v1 keeps byte-for-byte digest rules" + ); + let read = registry + .get_import_plan(&ws, &plan_id) + .await + .unwrap() + .expect("stored v1 plan remains readable"); + assert_eq!(read.payload, payload); + assert_eq!(read.digest, created.digest); + database.cleanup().await; +} + +#[tokio::test] +async fn catalog_revision_ignores_timestamps_and_foreign_workspace_but_tracks_semantics() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let raw = database.raw_pool().await; + let ws = create_workspace(®istry, "ws_catalog_revision").await; + let foreign = create_workspace(®istry, "ws_catalog_foreign").await; + let mut local_op = operation( + "op_catalog_local", + "local_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ); + registry + .create_operation(&ws, &local_op, None) + .await + .unwrap(); + let baseline = registry.import_catalog_revision(&ws).await.unwrap(); + + sqlx::query("update operations set updated_at = $1 where workspace_id = $2 and id = $3") + .bind(parse_ts("2026-10-03T11:00:00Z")) + .bind(ws.as_str()) + .bind(local_op.id.as_str()) + .execute(&raw) + .await + .unwrap(); + assert_eq!( + registry.import_catalog_revision(&ws).await.unwrap(), + baseline, + "runtime timestamps are excluded" + ); + + let foreign_op = operation( + "op_catalog_foreign", + "foreign_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ); + registry + .create_operation(&foreign, &foreign_op, None) + .await + .unwrap(); + assert_eq!( + registry.import_catalog_revision(&ws).await.unwrap(), + baseline, + "foreign scope is excluded" + ); + + sqlx::query( + "update operations set name = 'renamed_local_tool' where workspace_id = $1 and id = $2", + ) + .bind(ws.as_str()) + .bind(local_op.id.as_str()) + .execute(&raw) + .await + .unwrap(); + let renamed = registry.import_catalog_revision(&ws).await.unwrap(); + assert_ne!(renamed, baseline, "catalog names affect the revision"); + sqlx::query( + "update operations set current_draft_version = 2 where workspace_id = $1 and id = $2", + ) + .bind(ws.as_str()) + .bind(local_op.id.as_str()) + .execute(&raw) + .await + .unwrap(); + let versioned = registry.import_catalog_revision(&ws).await.unwrap(); + assert_ne!( + versioned, renamed, + "catalog version pointers affect the revision" + ); + sqlx::query("update operations set status = 'published' where workspace_id = $1 and id = $2") + .bind(ws.as_str()) + .bind(local_op.id.as_str()) + .execute(&raw) + .await + .unwrap(); + let status_changed = registry.import_catalog_revision(&ws).await.unwrap(); + assert_ne!( + status_changed, versioned, + "catalog lifecycle affects the revision" + ); + // Avoid accidental use of stale local fixture state if this case grows. + local_op.name = "renamed_local_tool".to_owned(); + database.cleanup().await; +} + +#[tokio::test] +async fn revalidation_and_apply_reject_catalog_drift_without_plan_mutation() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let raw = database.raw_pool().await; + let now = OffsetDateTime::now_utc(); + let ws = create_workspace(®istry, "ws_v2_drift").await; + let job = create_pending_openapi_job( + ®istry, + &ws, + "job_v2_drift", + now, + now + Duration::hours(1), + ) + .await; + activate_source(&raw, &ws, now).await; + let fp = fingerprint(); + let revision = registry.import_catalog_revision(&ws).await.unwrap(); + let plan_id_text = "plan_v2_drift"; + let payload = v2_payload( + plan_id_text, + job.as_str(), + SOURCE_ID, + operation( + "op_v2_planned", + "planned_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ), + &revision, + ); + let (plan, digest) = store_plan(®istry, &ws, &job, plan_id_text, &payload, now).await; + registry + .revalidate_import_plan(&ws, &plan, &fp) + .await + .unwrap(); + + let catalog_change = operation( + "op_v2_catalog_change", + "catalog_change_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ); + registry + .create_operation(&ws, &catalog_change, None) + .await + .unwrap(); + assert!( + matches!( + registry.revalidate_import_plan(&ws, &plan, &fp).await, + Err(RegistryError::ImportPlanFingerprintStale { .. }) + ), + "read-only revalidation must flag catalog drift" + ); + + let request = ApplyImportPlanRequest { + workspace_id: &ws, + plan_id: &plan, + plan_digest: &digest, + idempotency_key: "idem_v2_drift", + verified_fingerprint: &fp, + applied_at: &now, + }; + assert!( + matches!( + registry.apply_import_plan(&request).await, + Err(RegistryError::ImportPlanFingerprintStale { .. }) + ), + "fresh Apply must independently reject the stale catalog revision" + ); + assert!( + registry + .get_operation_summary(&ws, &crank_core::OperationId::new("op_v2_planned")) + .await + .unwrap() + .is_none(), + "catalog drift must fail before creating the planned operation" + ); + assert_eq!( + registry + .get_import_plan_application(&ws, "idem_v2_drift") + .await + .unwrap(), + None, + "a stale apply must not persist application evidence" + ); + database.cleanup().await; +} + +#[tokio::test] +async fn v2_apply_creates_operation_and_reports_the_confirmed_candidate() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let raw = database.raw_pool().await; + let now = OffsetDateTime::now_utc(); + let ws = create_workspace(®istry, "ws_v2_apply").await; + let job = create_pending_openapi_job( + ®istry, + &ws, + "job_v2_apply", + now, + now + Duration::hours(1), + ) + .await; + activate_source(&raw, &ws, now).await; + let fp = fingerprint(); + let revision = registry.import_catalog_revision(&ws).await.unwrap(); + let payload = v2_payload( + "plan_v2_apply", + job.as_str(), + SOURCE_ID, + operation( + "op_v2_apply", + "v2_apply_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ), + &revision, + ); + let (plan, digest) = store_plan(®istry, &ws, &job, "plan_v2_apply", &payload, now).await; + let request = ApplyImportPlanRequest { + workspace_id: &ws, + plan_id: &plan, + plan_digest: &digest, + idempotency_key: "idem_v2_apply", + verified_fingerprint: &fp, + applied_at: &now, + }; + let result = registry.apply_import_plan(&request).await.unwrap(); + assert!(!result.replayed); + assert_eq!(result.report.status, ImportPlanApplyStatus::Applied); + assert_eq!(result.report.counts.created, 1); + assert_eq!(result.report.outcomes[0].key, "candidate"); + assert_eq!( + result.report.outcomes[0].outcome, + ImportPlanCandidateOutcome::Created + ); + assert_eq!( + result.report.outcomes[0].operation_id.as_deref(), + Some("op_v2_apply") + ); + assert_eq!( + registry + .get_operation_summary(&ws, &crank_core::OperationId::new("op_v2_apply")) + .await + .unwrap() + .unwrap() + .current_draft_version, + 1 + ); + database.cleanup().await; +} + +#[tokio::test] +async fn partial_v2_apply_preserves_the_reason_for_an_excluded_candidate() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let raw = database.raw_pool().await; + let now = OffsetDateTime::now_utc(); + let ws = create_workspace(®istry, "ws_v2_excluded_reason").await; + let job = create_pending_openapi_job( + ®istry, + &ws, + "job_v2_excluded_reason", + now, + now + Duration::hours(1), + ) + .await; + activate_source(&raw, &ws, now).await; + let fp = fingerprint(); + let revision = registry.import_catalog_revision(&ws).await.unwrap(); + let mut payload = v2_payload( + "plan_v2_excluded_reason", + job.as_str(), + SOURCE_ID, + operation( + "op_v2_excluded_reason", + "selected_tool", + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ), + &revision, + ); + payload["selection"] = json!({ + "mode": "partial", "all": ["candidate", "unsupported"], + "selected": ["candidate"], "excluded": ["unsupported"] + }); + payload["counts"] = json!({"selected": 1, "excluded": 1, "actionable": 1, "blocked": 0}); + payload["excluded_reasons"] = json!([{"key": "unsupported", "reason": "unsupported_schema"}]); + payload["findings"]["candidates"] = json!([ + {"key": "candidate", "findings": []}, + {"key": "unsupported", "findings": [{"code": "unsupported_schema"}]} + ]); + let (plan, digest) = store_plan( + ®istry, + &ws, + &job, + "plan_v2_excluded_reason", + &payload, + now, + ) + .await; + let request = ApplyImportPlanRequest { + workspace_id: &ws, + plan_id: &plan, + plan_digest: &digest, + idempotency_key: "idem_v2_excluded_reason", + verified_fingerprint: &fp, + applied_at: &now, + }; + let result = registry.apply_import_plan(&request).await.unwrap(); + assert_eq!(result.report.status, ImportPlanApplyStatus::Applied); + assert_eq!(result.report.counts.excluded, 1); + let excluded = result + .report + .outcomes + .iter() + .find(|item| item.key == "unsupported") + .unwrap(); + assert_eq!(excluded.outcome, ImportPlanCandidateOutcome::Excluded); + assert_eq!(excluded.reason.as_deref(), Some("unsupported_schema")); + assert!( + registry + .get_operation_summary(&ws, &crank_core::OperationId::new("op_v2_excluded_reason")) + .await + .unwrap() + .is_some() + ); + database.cleanup().await; +} + +#[tokio::test] +async fn plan_store_accepts_the_full_two_thousand_candidate_limit() { + let database = TestDatabase::new().await; + let registry = database.registry().await; + let raw = database.raw_pool().await; + let now = OffsetDateTime::now_utc(); + let ws = create_workspace(®istry, "ws_v2_limit").await; + let job = create_pending_openapi_job( + ®istry, + &ws, + "job_v2_limit", + now, + now + Duration::hours(1), + ) + .await; + activate_source(&raw, &ws, now).await; + let revision = registry.import_catalog_revision(&ws).await.unwrap(); + let mut keys = Vec::with_capacity(2_000); + let mut candidates = Vec::with_capacity(2_000); + let mut candidate_findings = Vec::with_capacity(2_000); + for index in 0..2_000 { + let key = format!("candidate-{index:04}"); + let name = format!("candidate_{index:04}_tool"); + let operation = operation( + &format!("op_limit_{index:04}"), + &name, + "2026-10-03T10:00:00Z", + "2026-10-03T10:00:00Z", + ); + keys.push(key.clone()); + candidates.push(json!({ + "key": key, "name": name, "state": "actionable", "decision": {"action": "create"}, + "findings": [], "operation": operation + })); + candidate_findings.push(json!({"key": key, "findings": []})); + } + let payload = json!({ + "schema_version": "import-plan-v2", "plan_reference": "plan_v2_limit", "job_id": job.as_str(), + "fingerprint": fingerprint(), "catalog_revision": revision, "support_matrix_version": "1.0.2", + "source": {"source_id": SOURCE_ID, "digest": SOURCE_DIGEST}, "dependencies": [], + "excluded_reasons": [], + "findings": {"document": [], "candidates": candidate_findings}, + "selection": {"mode": "full", "all": keys, "selected": keys, "excluded": []}, + "counts": {"selected": 2_000, "excluded": 0, "actionable": 2_000, "blocked": 0}, + "candidates": candidates + }); + let encoded = serde_json::to_vec(&payload).unwrap(); + assert!( + encoded.len() < 16 * 1024 * 1024, + "fixture itself must remain under the payload cap" + ); + let (plan_id, _) = store_plan(®istry, &ws, &job, "plan_v2_limit", &payload, now).await; + let stored = registry + .get_import_plan(&ws, &plan_id) + .await + .unwrap() + .unwrap(); + assert_eq!( + stored.payload["candidates"].as_array().unwrap().len(), + 2_000 + ); + assert_eq!( + stored.payload["selection"]["selected"] + .as_array() + .unwrap() + .len(), + 2_000 + ); + registry + .revalidate_import_plan(&ws, &plan_id, &fingerprint()) + .await + .expect("the maximum valid candidate set must pass registry material validation"); + database.cleanup().await; +} diff --git a/docs/openapi-import.md b/docs/openapi-import.md index 22ec627..f19fea8 100644 --- a/docs/openapi-import.md +++ b/docs/openapi-import.md @@ -8,11 +8,13 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger 2. Нажмите **Импорт OpenAPI** рядом с кнопкой **Новая операция**. 3. Загрузите ровно один UTF-8 `.yaml`, `.yml` или `.json` файл размером от 1 B до 256 KiB. Вставка текста не поддерживается. 4. Нажмите **Разобрать документ**. + Preview принимает до 2 000 methods; документ с большим числом кандидатов отклоняется целиком с typed ошибкой, без скрытого усечения. 5. Проверьте preview: сгенерированный contract сохраняет parameter locations, body formats, варианты успешного ответа и effective security requirements. + API помечает метод `actionable`, `unresolved` или `blocked` по typed findings и доступным security choices; окончательное разрешение выбранного Auth Profile происходит при создании плана. 6. Выберите нужные группы и методы. 7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную. 8. Для уже существующей операции подтвердите решение отдельно: пропустить точную операцию, создать отдельную операцию с указанным вами свободным именем или добавить новую черновую версию к выбранной REST-операции. Автоматический подбор имени при применении плана не выполняется. -9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию полный план требует, чтобы каждый метод можно было применить; для частичного импорта явно оставьте только нужные методы. +9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию действует полный режим: любой blocker запрещает Apply всего документа. Для частичного импорта явно включите режим и выберите только методы без blocker findings с разрешёнными зависимостями и аутентификацией. 10. Для защищённых методов выберите security alternative (OR-варианты preview; неподдерживаемые варианты, включая AND/OAuth, показаны заблокированными) и, если требуется аутентификация, совместимый Auth Profile текущего workspace — по безопасным метаданным `id/name/kind` из preview. Вариант без схем — анонимный вызов без профиля. Статус привязки показывает только API: `Unresolved` до проверки, `Resolved` после подтверждения планом, `Blocked` при отказе; UI не вычисляет resolved локально. Незакрытое обязательное требование или недоступный профиль оставляет метод заблокированным. 11. Подтвердите план и примените его. Создание плана не меняет операции. Применение выполняет все выбранные изменения одной транзакцией и показывает результат для каждого метода. @@ -26,7 +28,11 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger При неизвестном результате Apply, например после разрыва соединения, повторите запрос с теми же ссылкой на план, digest и ключом идемпотентности. Повтор после commit возвращает сохранённый отчёт и не создаёт ещё одну версию; тот же ключ с другим digest даёт конфликт. Пока Apply выполняется, повторное нажатие кнопки не отправляет вторую логическую операцию. -Если с момента создания плана изменились источник или внешние документы, версия импортера либо состояние выбранной операции, а также конфигурация выбранного Auth Profile или версия его секрета, Apply отклоняет план без частичных изменений и предлагает заново разобрать документ. Отозванный или недоступный профиль также приводит к отказу. Срок жизни плана ограничен сроком исходного preview job. +Если с момента создания плана изменились источник или внешние документы, версия импортера, workspace catalog либо состояние выбранной операции, а также конфигурация выбранного Auth Profile или версия его секрета, Apply отклоняет план без частичных изменений и предлагает заново разобрать документ. Read-only `GET /api/admin/workspaces/{workspace_id}/imports/openapi/plans/{plan_id}` проверяет сохранённый план при повторном открытии и возвращает `current` или `stale` с `revalidation_required`; проверка не создаёт операции и не делает запрос к изменяемому внешнему `$ref`. Отозванный или недоступный профиль также приводит к отказу. Срок жизни плана ограничен сроком исходного preview job. + +Новые планы `import-plan-v2` содержат source/external snapshot digests, версии normalizer/projection и support matrix, catalog revision, полный список кандидатов и selections, findings, решения по конфликтам и причины исключений. Digest вычисляется из semantic material: случайные идентификаторы plan/job/source/новой операции и время создания в него не входят. Сохранённый payload остаётся неизменяемым, а новый выбор или решение создаёт новую запись. Старые `import-plan-v1` продолжают проверяться по исходному полному digest payload. + +Workspace catalog для revision и naming читается целиком до 10 000 записей; превышение лимита даёт ошибку вместо усечения. Revision учитывает релевантные метаданные операций, а состояние выбранных Auth Profile и Secret проверяется по безопасным snapshot-метаданным без чтения raw/ciphertext credentials. Для `import-plan-v2` предел сохранённого payload — 16 MiB при общем пределе 2 000 candidates; исторический `import-plan-v1` сохраняет свой предел 4 MiB. ## Что создается @@ -81,10 +87,46 @@ Semantic loss получает blocker с source location: такой candidate Один endpoint с несколькими request formats остаётся одним Tool. Поля `content_type` и `body` выбирают одну schema и соответствующую сериализацию; неизвестный selector или body другой ветви отклоняются до отправки запроса. Для единственного формата selector не нужен. Подробный inline-file contract описан в [REST](protocols/rest.md). -Новые imports используют `normalized-ir-v5` / `preview-v5`. Исторические v2/v3/v4 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs. +Новые imports используют `normalized-ir-v5` / `preview-v6`: source-derived candidate, finding и naming conflict включают безопасный RFC 6901 `source_location`; typed findings сохраняют стабильный `code`. Схемы и маппинги принадлежат candidate с его source pointer и проверяемой provenance в IR/reference graph. Производные группы, counts и summary связаны с исходником через membership candidates; единственный pointer или finding code для такой агрегации был бы ложной provenance. Исторические v2/v3/v4/v5 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs. Другие форматы спецификаций и протоколов в Community-импорт не входят. +## Проверка больших preview на Reference Deployment + +Локальная проверка пагинации использует mock API и измеряет только browser handler; она не подтверждает требование AC-11 о полной интерактивности ≤2 s p95. Для операторской проверки нужен отдельный Reference Deployment: Linux x86_64, сервисы с PostgreSQL 16 и Valkey 8 на 4 vCPU/8 GiB, SSD не менее 100 GB, 3000 IOPS и 100 MB/s, LAN не менее 1 Gbit/s, и отдельный эквивалентный load-generator с браузером. Перед запуском сохраните подтверждённые параметры без секретов в JSON-манифесте, например: + +```json +{ + "deployment": { + "host_id": "reference-server", "cpu_model": "record actual model", + "cpu_cores": 4, "ram_gib": 8, "postgres_version": "16.0", + "valkey_version": "8.0", "storage_type": "SSD", + "ssd_capacity_gb": 100, "ssd_iops": 3000, + "ssd_throughput_mb_s": 100, "lan_mbps": 1000 + }, + "load_generator": { "host_id": "reference-runner", "cpu_cores": 4, "ram_gib": 8 }, + "browser": { "host_id": "reference-runner" } +} +``` + +На load-generator задайте `PLAYWRIGHT_BASE_URL` для удалённого origin, `PLAYWRIGHT_SKIP_WEB_SERVER=1`, абсолютный путь `CRANK_AC11_REFERENCE_ENV_JSON` и учётные данные через `CRANK_E2E_ADMIN_EMAIL`/`CRANK_E2E_ADMIN_PASSWORD` в окружении; затем выполните из `apps/ui`: + +```sh +npx playwright test tests/e2e/openapi-preview-reference.spec.js --workers=1 +``` + +Harness отправляет реальный `openapi.yaml` с 2 000 operations (157 023 B), делает warm-up и 20 независимых preview-запросов без mock routes. Каждый замер начинается при нажатии Preview и заканчивается после ответа API, разбора и отображения первой страницы с доступной кнопкой создания плана. JSON attachment/stdout сохраняет все 20 samples, p95, DOM bound и sanitized сведения об окружении. Отсутствующий URL пропускает только отдельный операторский тест; при заданном URL отсутствующий или неподходящий манифест вызывает ошибку. Сам манифест — декларация оператора; результат требует фактического запуска в указанной инфраструктуре. + +Локальное ограниченное evidence: `cd apps/ui && npx playwright test tests/e2e/openapi-preview-partial.spec.js --grep 'AC-11' --workers=1` выводит `AC11_LOCAL_SHARED_HOST_METRICS` с сырыми samples. На shared host Linux x86_64 (Intel Core i5-4300U, 4 logical CPUs), headless Chromium 149, viewport 1280×720, mock fixture 2 000 candidates показал максимум 100 строк preview и 100 строк плана. Время ниже — длительность browser event handlers (`performance.now()`, ms), без API и LAN: + +```json +{ + "search_filter_ms": [7, 26, 12.7, 9.6, 5.3, 5.2, 6.5, 7.8, 5.5, 7.8, 5.6, 9.8, 8.2, 5.2, 7.9, 11.6, 6.9, 5.3, 6.6, 6], + "preview_page_change_ms": [50.1, 30.1, 23.3, 18.8, 21.3, 24.2, 30, 20.6, 69, 23.9, 22.3, 19.5, 18.8, 20.3, 25.1, 20.8, 20.6, 21.2, 22.4, 24.8], + "plan_page_change_ms": [2.8, 1.9, 1.9, 4.1, 2.9, 3.6, 2.9, 3.9, 2.4, 1.8, 4, 4.7, 1.9, 2, 1.7, 2.1, 1.8, 2.1, 1.7, 3.3] +} +``` + ## Нормативная матрица и regression corpus Машинная матрица версии `1.0.2` хранится в [`crates/crank-import/tests/support-matrix.yaml`](../crates/crank-import/tests/support-matrix.yaml); corpus version — `1.0.3`. Матрица фиксирует контракт отдельно для OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0. Acceptance test запускает нормализатор на отдельном probe для каждой строки, включая все 100 успешных кодов в каждом формате, и сверяет сохранённую semantics или точный blocker; выполненные probes списываются со всех строк версии, поэтому неподвергнутая проверкой строка матрицы падает gate. Версия corpus `1.0.3` добавляет hostile fixture `hostile-security-scope.json`: document-level требование безопасности блокирует только унаследовавшего его secured candidate (`GET /secure`, location `/security/0`), а операция с явным `security: []` (`GET /public`) остаётся actionable без глобального blocker; oversized hostile JSON остаётся тем же canonical JSON с ожидаемым parser rejection. diff --git a/docs/schemas/metrics-registry-v1.json b/docs/schemas/metrics-registry-v1.json index a2d597b..23a669d 100644 --- a/docs/schemas/metrics-registry-v1.json +++ b/docs/schemas/metrics-registry-v1.json @@ -1,14 +1,14 @@ { "schema_version": 1, - "budget": {"logical_series": 5353, "rendered_series": 16978, "max_logical_series": 5400, "max_rendered_series": 17000}, + "budget": {"logical_series": 5423, "rendered_series": 17198, "max_logical_series": 5470, "max_rendered_series": 17220}, "global_labels": [ {"name": "service", "class": "process_constant", "domain": ["admin-api", "mcp-server"]}, {"name": "version", "class": "process_constant", "domain": ["validated_release_identity"]}, {"name": "environment", "class": "process_constant", "domain": ["validated_startup_value"]} ], "metrics": [ - {"name": "crank_http_requests_total", "kind": "counter", "unit": "count", "help": "Total HTTP requests.", "processes": ["admin_api", "mcp_server"], "labels": [{"name": "route", "class": "product_closed", "domain": ["unmatched", "/health", "/ready", "/api/auth/login", "/api/auth/bootstrap/status", "/api/auth/bootstrap/complete", "/api/auth/logout", "/api/auth/session", "/api/auth/session/csrf", "/api/auth/profile", "/api/auth/password", "/api/admin/capabilities", "/api/admin/workspaces", "/api/admin/workspaces/{workspace_id}", "/api/admin/workspaces/{workspace_id}/onboarding", "/api/admin/workspaces/{workspace_id}/onboarding/events", "/api/admin/workspaces/{workspace_id}/onboarding/reset-selection", "/api/admin/workspaces/{workspace_id}/operations", "/api/admin/workspaces/{workspace_id}/imports/openapi/preview", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/create", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/plans", "/api/admin/workspaces/{workspace_id}/imports/openapi/{plan_id}/apply", "/api/admin/workspaces/{workspace_id}/operations/analyze-quality", "/api/admin/workspaces/{workspace_id}/operations/import", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/export", "/api/admin/workspaces/{workspace_id}/agents", "/api/admin/workspaces/{workspace_id}/agents/tool-search/preview", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}/revoke", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}", "/api/admin/workspaces/{workspace_id}/auth-profiles", "/api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}", "/api/admin/workspaces/{workspace_id}/upstreams", "/api/admin/workspaces/{workspace_id}/upstreams/{upstream_id}", "/api/admin/workspaces/{workspace_id}/secrets", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}/rotate", "/api/admin/workspaces/{workspace_id}/export", "/api/admin/workspaces/{workspace_id}/logs", "/api/admin/workspaces/{workspace_id}/logs/export.csv", "/api/admin/workspaces/{workspace_id}/logs/{log_id}", "/api/admin/workspaces/{workspace_id}/approvals", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/approve", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/deny", "/api/admin/workspaces/{workspace_id}/usage", "/api/admin/workspaces/{workspace_id}/usage/export.csv", "/api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}", "/v1/{workspace_slug}/{agent_slug}", "/v1/{workspace_slug}/{agent_slug}/approvals", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/approve", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/deny"]},{"name": "method", "class": "product_closed", "domain": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "CONNECT", "TRACE", "OTHER"]},{"name": "status_class", "class": "product_closed", "domain": ["1xx", "2xx", "3xx", "4xx", "5xx", "other"]}], "buckets_seconds": [], "max_logical_series": 4140, "max_rendered_series": 4140}, - {"name": "crank_http_request_duration_seconds", "kind": "histogram", "unit": "seconds", "help": "HTTP request duration in seconds.", "processes": ["admin_api", "mcp_server"], "labels": [{"name": "route", "class": "product_closed", "domain": ["unmatched", "/health", "/ready", "/api/auth/login", "/api/auth/bootstrap/status", "/api/auth/bootstrap/complete", "/api/auth/logout", "/api/auth/session", "/api/auth/session/csrf", "/api/auth/profile", "/api/auth/password", "/api/admin/capabilities", "/api/admin/workspaces", "/api/admin/workspaces/{workspace_id}", "/api/admin/workspaces/{workspace_id}/onboarding", "/api/admin/workspaces/{workspace_id}/onboarding/events", "/api/admin/workspaces/{workspace_id}/onboarding/reset-selection", "/api/admin/workspaces/{workspace_id}/operations", "/api/admin/workspaces/{workspace_id}/imports/openapi/preview", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/create", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/plans", "/api/admin/workspaces/{workspace_id}/imports/openapi/{plan_id}/apply", "/api/admin/workspaces/{workspace_id}/operations/analyze-quality", "/api/admin/workspaces/{workspace_id}/operations/import", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/export", "/api/admin/workspaces/{workspace_id}/agents", "/api/admin/workspaces/{workspace_id}/agents/tool-search/preview", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}/revoke", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}", "/api/admin/workspaces/{workspace_id}/auth-profiles", "/api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}", "/api/admin/workspaces/{workspace_id}/upstreams", "/api/admin/workspaces/{workspace_id}/upstreams/{upstream_id}", "/api/admin/workspaces/{workspace_id}/secrets", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}/rotate", "/api/admin/workspaces/{workspace_id}/export", "/api/admin/workspaces/{workspace_id}/logs", "/api/admin/workspaces/{workspace_id}/logs/export.csv", "/api/admin/workspaces/{workspace_id}/logs/{log_id}", "/api/admin/workspaces/{workspace_id}/approvals", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/approve", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/deny", "/api/admin/workspaces/{workspace_id}/usage", "/api/admin/workspaces/{workspace_id}/usage/export.csv", "/api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}", "/v1/{workspace_slug}/{agent_slug}", "/v1/{workspace_slug}/{agent_slug}/approvals", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/approve", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/deny"]},{"name": "method", "class": "product_closed", "domain": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "CONNECT", "TRACE", "OTHER"]}], "buckets_seconds": [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60], "max_logical_series": 690, "max_rendered_series": 11040}, + {"name": "crank_http_requests_total", "kind": "counter", "unit": "count", "help": "Total HTTP requests.", "processes": ["admin_api", "mcp_server"], "labels": [{"name": "route", "class": "product_closed", "domain": ["unmatched", "/health", "/ready", "/api/auth/login", "/api/auth/bootstrap/status", "/api/auth/bootstrap/complete", "/api/auth/logout", "/api/auth/session", "/api/auth/session/csrf", "/api/auth/profile", "/api/auth/password", "/api/admin/capabilities", "/api/admin/workspaces", "/api/admin/workspaces/{workspace_id}", "/api/admin/workspaces/{workspace_id}/onboarding", "/api/admin/workspaces/{workspace_id}/onboarding/events", "/api/admin/workspaces/{workspace_id}/onboarding/reset-selection", "/api/admin/workspaces/{workspace_id}/operations", "/api/admin/workspaces/{workspace_id}/imports/openapi/preview", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/create", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/plans", "/api/admin/workspaces/{workspace_id}/imports/openapi/plans/{plan_id}", "/api/admin/workspaces/{workspace_id}/imports/openapi/{plan_id}/apply", "/api/admin/workspaces/{workspace_id}/operations/analyze-quality", "/api/admin/workspaces/{workspace_id}/operations/import", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/export", "/api/admin/workspaces/{workspace_id}/agents", "/api/admin/workspaces/{workspace_id}/agents/tool-search/preview", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}/revoke", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}", "/api/admin/workspaces/{workspace_id}/auth-profiles", "/api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}", "/api/admin/workspaces/{workspace_id}/upstreams", "/api/admin/workspaces/{workspace_id}/upstreams/{upstream_id}", "/api/admin/workspaces/{workspace_id}/secrets", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}/rotate", "/api/admin/workspaces/{workspace_id}/export", "/api/admin/workspaces/{workspace_id}/logs", "/api/admin/workspaces/{workspace_id}/logs/export.csv", "/api/admin/workspaces/{workspace_id}/logs/{log_id}", "/api/admin/workspaces/{workspace_id}/approvals", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/approve", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/deny", "/api/admin/workspaces/{workspace_id}/usage", "/api/admin/workspaces/{workspace_id}/usage/export.csv", "/api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}", "/v1/{workspace_slug}/{agent_slug}", "/v1/{workspace_slug}/{agent_slug}/approvals", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/approve", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/deny"]},{"name": "method", "class": "product_closed", "domain": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "CONNECT", "TRACE", "OTHER"]},{"name": "status_class", "class": "product_closed", "domain": ["1xx", "2xx", "3xx", "4xx", "5xx", "other"]}], "buckets_seconds": [], "max_logical_series": 4200, "max_rendered_series": 4200}, + {"name": "crank_http_request_duration_seconds", "kind": "histogram", "unit": "seconds", "help": "HTTP request duration in seconds.", "processes": ["admin_api", "mcp_server"], "labels": [{"name": "route", "class": "product_closed", "domain": ["unmatched", "/health", "/ready", "/api/auth/login", "/api/auth/bootstrap/status", "/api/auth/bootstrap/complete", "/api/auth/logout", "/api/auth/session", "/api/auth/session/csrf", "/api/auth/profile", "/api/auth/password", "/api/admin/capabilities", "/api/admin/workspaces", "/api/admin/workspaces/{workspace_id}", "/api/admin/workspaces/{workspace_id}/onboarding", "/api/admin/workspaces/{workspace_id}/onboarding/events", "/api/admin/workspaces/{workspace_id}/onboarding/reset-selection", "/api/admin/workspaces/{workspace_id}/operations", "/api/admin/workspaces/{workspace_id}/imports/openapi/preview", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/create", "/api/admin/workspaces/{workspace_id}/imports/openapi/{job_id}/plans", "/api/admin/workspaces/{workspace_id}/imports/openapi/plans/{plan_id}", "/api/admin/workspaces/{workspace_id}/imports/openapi/{plan_id}/apply", "/api/admin/workspaces/{workspace_id}/operations/analyze-quality", "/api/admin/workspaces/{workspace_id}/operations/import", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate", "/api/admin/workspaces/{workspace_id}/operations/{operation_id}/export", "/api/admin/workspaces/{workspace_id}/agents", "/api/admin/workspaces/{workspace_id}/agents/tool-search/preview", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}/revoke", "/api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}", "/api/admin/workspaces/{workspace_id}/auth-profiles", "/api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}", "/api/admin/workspaces/{workspace_id}/upstreams", "/api/admin/workspaces/{workspace_id}/upstreams/{upstream_id}", "/api/admin/workspaces/{workspace_id}/secrets", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}", "/api/admin/workspaces/{workspace_id}/secrets/{secret_id}/rotate", "/api/admin/workspaces/{workspace_id}/export", "/api/admin/workspaces/{workspace_id}/logs", "/api/admin/workspaces/{workspace_id}/logs/export.csv", "/api/admin/workspaces/{workspace_id}/logs/{log_id}", "/api/admin/workspaces/{workspace_id}/approvals", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/approve", "/api/admin/workspaces/{workspace_id}/approvals/{approval_id}/deny", "/api/admin/workspaces/{workspace_id}/usage", "/api/admin/workspaces/{workspace_id}/usage/export.csv", "/api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}", "/api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}", "/v1/{workspace_slug}/{agent_slug}", "/v1/{workspace_slug}/{agent_slug}/approvals", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/approve", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}", "/v1/{workspace_slug}/{agent_slug}/approvals/{approval_id}/deny"]},{"name": "method", "class": "product_closed", "domain": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "CONNECT", "TRACE", "OTHER"]}], "buckets_seconds": [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60], "max_logical_series": 700, "max_rendered_series": 11200}, {"name": "crank_http_inflight", "kind": "gauge", "unit": "count", "help": "HTTP requests currently being processed.", "processes": ["admin_api", "mcp_server"], "labels": [], "buckets_seconds": [], "max_logical_series": 1, "max_rendered_series": 1}, {"name": "crank_mcp_requests_total", "kind": "counter", "unit": "count", "help": "Total MCP JSON-RPC requests.", "processes": ["mcp_server"], "labels": [{"name": "method", "class": "product_closed", "domain": ["initialize", "initialized", "ping", "tools_list", "tools_call", "notification", "unsupported", "response", "invalid"]},{"name": "response_mode", "class": "product_closed", "domain": ["json", "sse", "unknown"]},{"name": "outcome", "class": "product_closed", "domain": ["success", "client_error", "server_error", "jsonrpc_error", "tool_error", "aborted", "other"]}], "buckets_seconds": [], "max_logical_series": 189, "max_rendered_series": 189}, {"name": "crank_mcp_request_duration_seconds", "kind": "histogram", "unit": "seconds", "help": "MCP JSON-RPC request duration in seconds.", "processes": ["mcp_server"], "labels": [{"name": "method", "class": "product_closed", "domain": ["initialize", "initialized", "ping", "tools_list", "tools_call", "notification", "unsupported", "response", "invalid"]},{"name": "outcome", "class": "product_closed", "domain": ["success", "client_error", "server_error", "jsonrpc_error", "tool_error", "aborted", "other"]}], "buckets_seconds": [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60], "max_logical_series": 63, "max_rendered_series": 1008},