Merge bmad-loop/20261001-210704-f6bc/2-12-preview-partial-mode into main (bmad-loop)

This commit is contained in:
bsodfather committed 2026-10-03 15:04:15 +03:00
commit 3e801da4d9
56 files changed
+5801 -376

No files matched your search

@@ -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
@@ -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-contract>
## 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 |
</intent-contract>
## 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` остаётся собственностью оркестратора и не изменён.
@@ -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-<n>` 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.
+5 -1
View File
@@ -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)),
+13
View File
@@ -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<OpenApiImportPlanCandidateView>,
}
#[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<String>,
pub counts: OpenApiImportPlanCounts,
pub candidates: Vec<OpenApiImportPlanCandidateView>,
}
#[derive(Clone, Debug, Serialize)]
pub struct CreatedOperationResponse {
pub operation_id: String,
+14
View File
@@ -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<WorkspacePlanPath>,
State(state): State<AppState>,
) -> Result<Json<Value>, 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<WorkspacePlanPath>,
State(state): State<AppState>,
+174 -5
View File
@@ -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<ImportNameConflict> {
let operations = preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
.collect::<Vec<_>>();
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::<BTreeSet<_>>();
let mut proposals = catalog_names.iter().cloned().collect::<BTreeSet<_>>();
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::<String>();
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>) -> 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::<Vec<_>>();
@@ -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::<BTreeSet<_>>();
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");
}
}
+60 -130
View File
@@ -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<String> = 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::<BTreeMap<_, _>>();
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::<Vec<_>>(),
},
"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::<Vec<_>>(),
"counts": plan_counts_value,
"candidates": planned.iter().map(plan_candidate_payload).collect::<Result<Vec<_>, _>>()?,
});
@@ -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<String>,
) -> Result<BTreeMap<String, &'input OpenApiImportPlanDecision>, 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,
@@ -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<String>,
) -> Result<BTreeMap<String, &'input OpenApiImportPlanDecision>, 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(())
}
@@ -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<OpenApiImportPlanRevalidationResponse, ApiError> {
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"));
}
@@ -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"));
}
@@ -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]
@@ -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
@@ -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;
@@ -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()
);
}
@@ -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")]
@@ -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;
@@ -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);
}
@@ -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,
@@ -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() {
@@ -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::<Vec<_>>();
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"
);
}
@@ -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<u8>) -> 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(&registry, &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::<Vec<_>>();
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(&registry, &workspace_id).await, before);
let before = catalog_counts(&registry, &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(&registry, &workspace_id).await, before);
let before = catalog_counts(&registry, &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(&registry, &workspace_id).await, before);
let before = catalog_counts(&registry, &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(&registry, &workspace_id).await, before);
let before = catalog_counts(&registry, &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(&registry, &workspace_id).await, before);
}
@@ -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);
}
+110
View File
@@ -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;
+18
View File
@@ -433,7 +433,16 @@
<button class="btn-secondary" id="openapi-import-clear-visible" type="button" data-i18n="openapi.clear_visible">Снять видимые</button>
</div>
</div>
<label class="openapi-import-partial-toggle">
<input id="openapi-import-partial-mode" type="checkbox">
<span data-i18n="openapi.partial_mode">Enable partial import</span>
</label>
<div class="openapi-import-groups" id="openapi-import-groups"></div>
<nav class="openapi-import-pagination" id="openapi-import-pagination" data-testid="openapi-import-pagination" data-i18n-aria-label="openapi.pagination.label" aria-label="Pagination" hidden>
<button class="btn-secondary" id="openapi-import-page-previous" type="button" data-i18n="openapi.pagination.previous">Previous</button>
<span id="openapi-import-page-status" data-testid="openapi-import-page-status" role="status" aria-live="polite" aria-atomic="true"></span>
<button class="btn-secondary" id="openapi-import-page-next" type="button" data-i18n="openapi.pagination.next">Next</button>
</nav>
<div class="openapi-import-footer">
<span id="openapi-import-selection" data-i18n="openapi.selection.empty">Выбрано: 0</span>
<button class="btn-primary" id="openapi-import-create" type="button" data-i18n="openapi.plan.create">Просмотреть план импорта</button>
@@ -441,11 +450,20 @@
<section class="openapi-import-plan-confirmation" id="openapi-import-plan-confirmation" data-testid="openapi-import-apply-confirmation" aria-labelledby="openapi-import-plan-title" hidden>
<h3 id="openapi-import-plan-title" data-i18n="openapi.plan.confirm_title">Подтвердите план импорта</h3>
<p class="openapi-import-plan-intro" data-i18n="openapi.plan.confirm_intro">Перед применением проверьте точный план сервера.</p>
<p class="openapi-import-plan-version" id="openapi-import-plan-version" data-testid="openapi-import-plan-version"></p>
<p class="openapi-import-plan-revalidation" id="openapi-import-plan-revalidation-status" data-testid="openapi-import-plan-revalidation-status" role="status" aria-live="polite" aria-atomic="true"></p>
<p class="openapi-import-plan-stale" id="openapi-import-plan-stale" data-testid="openapi-import-plan-stale" hidden></p>
<p class="openapi-import-plan-blocked-help" id="openapi-import-plan-blocked-help" data-i18n="openapi.plan.blocked_help" hidden>Исправьте решения для заблокированных операций и создайте план заново.</p>
<div class="openapi-import-plan-counts" id="openapi-import-plan-counts" data-testid="openapi-import-apply-counts"></div>
<nav class="openapi-import-pagination" id="openapi-import-plan-pagination" data-testid="openapi-import-plan-pagination" data-i18n-aria-label="openapi.pagination.plan_label" aria-label="Plan candidates" hidden>
<button class="btn-secondary" id="openapi-import-plan-page-previous" type="button" data-i18n="openapi.pagination.previous">Previous</button>
<span id="openapi-import-plan-page-status" data-testid="openapi-import-plan-page-status" role="status" aria-live="polite" aria-atomic="true"></span>
<button class="btn-secondary" id="openapi-import-plan-page-next" type="button" data-i18n="openapi.pagination.next">Next</button>
</nav>
<div class="openapi-import-plan-candidates" id="openapi-import-plan-candidates"></div>
<p class="openapi-import-plan-versioning" id="openapi-import-versioning-consequences" data-testid="openapi-import-versioning-consequences" hidden></p>
<div class="openapi-import-plan-actions">
<button class="btn-secondary" id="openapi-import-plan-reopen" type="button" data-testid="openapi-import-plan-reopen" data-i18n="openapi.plan.reopen">Reopen and check current plan</button>
<button class="btn-secondary" id="openapi-import-plan-back" type="button" data-i18n="openapi.plan.back">Назад к выбору</button>
<button class="btn-primary" id="openapi-import-plan-apply" type="button" data-testid="openapi-import-plan-apply" data-i18n="openapi.plan.apply">Применить импорт</button>
</div>
+7
View File
@@ -447,6 +447,13 @@
signal: options && options.signal,
});
},
revalidateOpenApiImportPlan: function(workspaceId, planReference, options) {
return request(API_BASE + '/workspaces/' + encodeURIComponent(workspaceId) + '/imports/openapi/plans/' + encodeURIComponent(planReference), {
method: 'GET',
headers: headers({ 'Accept-Language': localStorage.getItem('crank_lang') === 'ru' ? 'ru' : 'en' }),
signal: options && options.signal,
});
},
applyOpenApiImportPlan: function(workspaceId, planReference, payload, options) {
return request(API_BASE + '/workspaces/' + encodeURIComponent(workspaceId) + '/imports/openapi/' + encodeURIComponent(planReference) + '/apply', {
method: 'POST',
+44 -2
View File
@@ -2134,10 +2134,25 @@ Object.assign(TRANSLATIONS.en, {
'openapi.method.all': 'All methods',
'openapi.select_visible': 'Select visible',
'openapi.clear_visible': 'Clear visible',
'openapi.partial_mode': 'Enable partial import',
'openapi.pagination.previous': 'Previous',
'openapi.pagination.next': 'Next',
'openapi.pagination.label': 'Preview pages',
'openapi.pagination.plan_label': 'Import plan candidates',
'openapi.pagination.result_label': 'Import results',
'openapi.findings.summary': 'Findings: {count}',
'openapi.pagination.status': 'Page {page} of {pages} · {total} matching operations',
'openapi.create': 'Create drafts',
'openapi.plan.create': 'Review import plan',
'openapi.plan.confirm_title': 'Confirm import plan',
'openapi.plan.confirm_intro': 'Review the exact server plan before applying it.',
'openapi.plan.reopen': 'Reopen and check current plan',
'openapi.plan.version': 'Review {version} · reference {reference} · digest {digest}',
'openapi.plan.revalidation_pending': 'Checking this saved plan…',
'openapi.plan.revalidation_current': 'The saved plan is current.',
'openapi.plan.revalidation_stale': 'The saved plan is stale.',
'openapi.plan.revalidation_error': 'The saved plan could not be verified.',
'openapi.plan.revalidation_guidance': 'Return to the preview and create a new plan before applying.',
'openapi.plan.back': 'Back to selection',
'openapi.plan.back_fix': 'Back to fix decisions',
'openapi.plan.apply': 'Apply import',
@@ -2189,8 +2204,11 @@ Object.assign(TRANSLATIONS.en, {
'openapi.selection.empty': 'Selected: 0',
'openapi.selection': 'Selected: {selected} of {total}, shown: {visible}',
'openapi.group.selection': 'selected {selected} of {total}, shown {visible}',
'openapi.group.select': 'Select group',
'openapi.group.select': 'Select group on this page',
'openapi.operation.fields': 'inputs: {input} · outputs: {output}',
'openapi.operation.readiness_actionable': 'Actionable',
'openapi.operation.readiness_blocked': 'Blocked',
'openapi.operation.readiness_unresolved': 'Authentication required',
'openapi.mapping.path': 'Path',
'openapi.mapping.query': 'Query',
'openapi.mapping.header': 'Header',
@@ -2199,6 +2217,8 @@ Object.assign(TRANSLATIONS.en, {
'openapi.source.summary': '{name} · {size} · methods: {count}',
'openapi.status.file_ready': 'File is ready for preview.',
'openapi.status.previewing': 'Uploading and parsing the document…',
'openapi.status.uploading': 'Uploading the document…',
'openapi.status.parsing': 'Parsing the OpenAPI document…',
'openapi.status.preview_ready': 'Document is ready. Select methods to import.',
'openapi.status.creating': 'Creating drafts…',
'openapi.status.created': 'Created: {created}; skipped: {skipped}.',
@@ -2243,6 +2263,7 @@ Object.assign(TRANSLATIONS.en, {
'openapi.result.fix': 'Fix in wizard',
'openapi.result.open': 'Open in wizard',
'openapi.result.skipped': 'Skipped',
'openapi.result.skipped_count': 'Skipped: {count} candidates',
});
@@ -2301,10 +2322,25 @@ Object.assign(TRANSLATIONS.ru, {
'openapi.method.all': 'Все методы',
'openapi.select_visible': 'Выбрать видимые',
'openapi.clear_visible': 'Снять видимые',
'openapi.partial_mode': 'Включить частичный импорт',
'openapi.pagination.previous': 'Назад',
'openapi.pagination.next': 'Далее',
'openapi.pagination.label': 'Страницы предпросмотра',
'openapi.pagination.plan_label': 'Кандидаты плана импорта',
'openapi.pagination.result_label': 'Результаты импорта',
'openapi.findings.summary': 'Замечаний: {count}',
'openapi.pagination.status': 'Страница {page} из {pages} · операций по фильтру: {total}',
'openapi.create': 'Создать черновики',
'openapi.plan.create': 'Проверить план импорта',
'openapi.plan.confirm_title': 'Подтвердите план импорта',
'openapi.plan.confirm_intro': 'Перед применением проверьте точный план сервера.',
'openapi.plan.reopen': 'Повторно открыть и проверить план',
'openapi.plan.version': 'Проверка {version} · ссылка {reference} · digest {digest}',
'openapi.plan.revalidation_pending': 'Проверяем сохранённый план…',
'openapi.plan.revalidation_current': 'Сохранённый план актуален.',
'openapi.plan.revalidation_stale': 'Сохранённый план устарел.',
'openapi.plan.revalidation_error': 'Не удалось проверить сохранённый план.',
'openapi.plan.revalidation_guidance': 'Вернитесь к предпросмотру и создайте новый план перед применением.',
'openapi.plan.back': 'Назад к выбору',
'openapi.plan.back_fix': 'Назад к исправлению решений',
'openapi.plan.apply': 'Применить импорт',
@@ -2356,8 +2392,11 @@ Object.assign(TRANSLATIONS.ru, {
'openapi.selection.empty': 'Выбрано: 0',
'openapi.selection': 'Выбрано: {selected} из {total}, показано: {visible}',
'openapi.group.selection': 'выбрано {selected} из {total}, показано {visible}',
'openapi.group.select': 'Выбрать группу',
'openapi.group.select': 'Выбрать группу на этой странице',
'openapi.operation.fields': 'входов: {input} · выходов: {output}',
'openapi.operation.readiness_actionable': 'Можно импортировать',
'openapi.operation.readiness_blocked': 'Заблокировано',
'openapi.operation.readiness_unresolved': 'Требуется авторизация',
'openapi.mapping.path': 'Path',
'openapi.mapping.query': 'Query',
'openapi.mapping.header': 'Header',
@@ -2366,6 +2405,8 @@ Object.assign(TRANSLATIONS.ru, {
'openapi.source.summary': '{name} · {size} · методов: {count}',
'openapi.status.file_ready': 'Файл готов к разбору.',
'openapi.status.previewing': 'Загружаю и разбираю документ…',
'openapi.status.uploading': 'Загружаю документ…',
'openapi.status.parsing': 'Разбираю документ OpenAPI…',
'openapi.status.preview_ready': 'Документ готов. Выберите методы для импорта.',
'openapi.status.creating': 'Создаю черновики…',
'openapi.status.created': 'Создано: {created}; пропущено: {skipped}.',
@@ -2410,6 +2451,7 @@ Object.assign(TRANSLATIONS.ru, {
'openapi.result.fix': 'Исправить в мастере',
'openapi.result.open': 'Открыть в мастере',
'openapi.result.skipped': 'Пропущено',
'openapi.result.skipped_count': 'Пропущено кандидатов: {count}',
});
File diff suppressed because it is too large. Load diff
@@ -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();
}
File diff suppressed because it is too large. Load diff
@@ -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);
});
+8 -3
View File
@@ -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('');
@@ -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,
}
}
@@ -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(),
+4 -4
View File
@@ -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,
+27 -1
View File
@@ -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<String>,
/// 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<SourceLocation>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -514,6 +518,17 @@ pub struct ImportPreview {
pub groups: Vec<ImportGroupPreview>,
#[serde(default)]
pub findings: Vec<ImportFinding>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub conflicts: Vec<ImportNameConflict>,
}
#[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<SourceLocation>,
}
#[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<SourceLocation>,
#[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<SourceLocation>,
#[serde(
default,
skip_serializing_if = "NormalizedSecurityRequirements::is_empty"
@@ -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(),
+2
View File
@@ -170,6 +170,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
key: format!("{} {}", method_name.to_uppercase(), path),
method,
path: path.clone(),
source_location: None,
security_requirements,
operation_id: operation_value
.get("operationId")
@@ -280,6 +281,7 @@ pub fn parse_document_legacy_v1(root: &Value) -> Result<RestImportDocument, Impo
key: format!("{} {}", method_name.to_uppercase(), path),
method,
path: path.clone(),
source_location: None,
security_requirements: Default::default(),
operation_id: operation
.get("operationId")
+2
View File
@@ -155,6 +155,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: operation.security_requirements.clone(),
security_schemes: security_schemes.clone(),
operation_id: operation.operation_id.clone(),
@@ -8,6 +8,7 @@ pub fn document_finding(code: &str, message: impl Into<String>) -> 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<String>) -> 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<ImportF
),
));
}
findings
with_operation_location(findings, operation)
}
pub fn candidate_recommendations(
@@ -179,6 +183,18 @@ pub fn candidate_recommendations(
));
}
with_operation_location(findings, operation)
}
fn with_operation_location(
mut findings: Vec<ImportFinding>,
operation: &RestImportOperation,
) -> Vec<ImportFinding> {
for finding in &mut findings {
if finding.source_location.is_none() {
finding.source_location = operation.source_location.clone();
}
}
findings
}
+2
View File
@@ -169,6 +169,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
key: format!("{} {}", method_name.to_uppercase(), path),
method,
path: path.clone(),
source_location: None,
security_requirements,
operation_id: operation_value
.get("operationId")
@@ -281,6 +282,7 @@ pub fn parse_document_legacy_v1(root: &Value) -> Result<RestImportDocument, Impo
key: format!("{} {}", method_name.to_uppercase(), path),
method,
path: path.clone(),
source_location: None,
security_requirements: Default::default(),
operation_id: operation
.get("operationId")
+23 -3
View File
@@ -196,7 +196,16 @@ fn ac_2_manifest_covers_fifty_provenanced_specs_with_exact_expectations() {
"corpus fixtures are single-operation exact oracles"
);
let expected = &document.expected_preview["operations"][0];
let actual_candidate = serde_json::to_value(candidates[0]).unwrap();
let mut actual_candidate = serde_json::to_value(candidates[0]).unwrap();
// Corpus snapshots freeze the pre-location semantic candidate.
// Source provenance is covered by dedicated preview assertions.
actual_candidate
.as_object_mut()
.unwrap()
.remove("source_location");
for finding in actual_candidate["findings"].as_array_mut().unwrap() {
finding.as_object_mut().unwrap().remove("source_location");
}
assert_eq!(
actual_candidate,
expected["candidate"],
@@ -224,13 +233,24 @@ fn ac_2_manifest_covers_fifty_provenanced_specs_with_exact_expectations() {
"candidate canonical digest in {}",
document.file
);
let mut actual_preview = serde_json::to_value(&preview).unwrap();
for group in actual_preview["groups"].as_array_mut().unwrap() {
for candidate in group["operations"].as_array_mut().unwrap() {
candidate.as_object_mut().unwrap().remove("source_location");
for finding in candidate["findings"].as_array_mut().unwrap() {
finding.as_object_mut().unwrap().remove("source_location");
}
}
}
for finding in actual_preview["findings"].as_array_mut().unwrap() {
finding.as_object_mut().unwrap().remove("source_location");
}
assert_eq!(
hex(canonical_json(&serde_json::to_value(&preview).unwrap())),
hex(canonical_json(&actual_preview)),
document.expected_preview["canonical_preview_digest"],
"preview canonical digest in {}",
document.file
);
let actual_preview = serde_json::to_value(&preview).unwrap();
assert_eq!(
actual_preview,
document.expected_preview["canonical_preview"],
+40
View File
@@ -96,6 +96,19 @@ definitions:
assert_eq!(operation.draft.input_mapping.rules.len(), 2);
}
#[test]
fn historical_preview_without_locations_still_deserializes() {
let old = serde_json::to_value(preview_document_legacy_v1(OPENAPI3).unwrap()).unwrap();
let replay: crank_import::rest::ImportPreview = serde_json::from_value(old).unwrap();
assert!(replay.groups[0].operations[0].source_location.is_none());
assert!(
replay.groups[0].operations[0]
.findings
.iter()
.all(|finding| finding.source_location.is_none())
);
}
#[test]
fn previews_swagger2_and_resolves_local_definitions() {
let preview = preview_document(SWAGGER2).unwrap();
@@ -511,6 +524,26 @@ paths:
assert!(codes.contains(&"missing_summary"));
assert!(codes.contains(&"missing_description"));
assert!(codes.contains(&"missing_response_schema"));
assert_eq!(
operation
.source_location
.as_ref()
.map(|location| location.pointer.as_str()),
Some("/paths/~1items/get")
);
assert!(operation.findings.iter().any(|finding| {
finding.code == "missing_operation_id"
&& finding
.source_location
.as_ref()
.is_some_and(|location| location.pointer == "/paths/~1items/get/operationId")
}));
assert!(
operation
.findings
.iter()
.all(|finding| finding.source_location.is_some())
);
}
#[test]
@@ -656,6 +689,13 @@ paths:
.filter(|finding| finding.code == "unsupported_http_method")
.count();
assert_eq!(unsupported, 2);
assert!(preview.findings.iter().any(|finding| {
finding.code == "unsupported_http_method"
&& finding
.source_location
.as_ref()
.is_some_and(|location| location.pointer == "/paths/~1health/trace")
}));
}
#[test]
+5 -4
View File
@@ -9,8 +9,8 @@ use crate::labels::{
pub const METRIC_SCHEMA_VERSION: u32 = 1;
pub const MAX_METRIC_FAMILIES: usize = 128;
pub const MAX_PRODUCT_LABELS_PER_FAMILY: usize = 4;
pub const MAX_LOGICAL_SERIES_PER_PROCESS: usize = 5_400;
pub const MAX_RENDERED_SERIES_PER_PROCESS: usize = 17_000;
pub const MAX_LOGICAL_SERIES_PER_PROCESS: usize = 5_470;
pub const MAX_RENDERED_SERIES_PER_PROCESS: usize = 17_220;
pub const MAX_EXPOSITION_BYTES: usize = 8 * 1024 * 1024;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -184,6 +184,7 @@ pub const HTTP_ROUTE_DOMAIN: &[&str] = &[
"/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",
@@ -306,7 +307,7 @@ const METRIC_SCHEMA: &[MetricDefinition] = &[
],
&[],
BOTH,
69 * 10 * 6,
HTTP_ROUTE_DOMAIN.len() * 10 * 6,
"Total HTTP requests.",
),
metric(
@@ -320,7 +321,7 @@ const METRIC_SCHEMA: &[MetricDefinition] = &[
],
DURATION_BUCKETS_SECONDS,
BOTH,
69 * 10,
HTTP_ROUTE_DOMAIN.len() * 10,
"HTTP request duration in seconds.",
),
metric(
+8 -8
View File
@@ -46,16 +46,16 @@ fn schema_v1_is_complete_deterministic_and_inside_the_frozen_budget() {
#[test]
fn frozen_budget_edges_are_exact() {
assert!(validate_budget(5_399, 16_999).is_ok());
assert!(validate_budget(5_400, 17_000).is_ok());
assert!(validate_budget(5_401, 16_000).is_err());
assert!(validate_budget(5_200, 17_001).is_err());
assert_eq!(crank_metrics::max_exemplar_slots(), 10_850);
assert!(validate_budget(5_469, 17_219).is_ok());
assert!(validate_budget(5_470, 17_220).is_ok());
assert!(validate_budget(5_471, 16_000).is_err());
assert!(validate_budget(5_200, 17_221).is_err());
assert_eq!(crank_metrics::max_exemplar_slots(), 10_990);
}
#[test]
fn every_registered_route_round_trips_without_dynamic_segments() {
assert_eq!(HTTP_ROUTE_DOMAIN.len(), 69);
assert_eq!(HTTP_ROUTE_DOMAIN.len(), 70);
for route in HTTP_ROUTE_DOMAIN {
assert_eq!(HttpRoute::from_matched_path(route).as_str(), *route);
assert!(!route.contains("trace_id"));
@@ -68,8 +68,8 @@ fn canonical_schema_validation_reports_its_category() {
assert_eq!(
schema_budget(),
Ok(crank_metrics::SchemaBudget {
logical_series: 5_353,
rendered_series: 16_978
logical_series: 5_423,
rendered_series: 17_198
})
);
}
@@ -1,5 +1,8 @@
mod catalog;
mod legacy_auth;
mod plan_apply;
mod semantic;
use semantic::plan_digest_from_payload;
use super::*;
use crate::{
@@ -14,7 +17,8 @@ const APPLICATION_RESULT_KEY: &str = "_crank_application_result";
const IMPORT_JOB_CLEANUP_BATCH: u32 = 128;
const MAX_IMPORT_JOB_DOCUMENTS: usize = 32;
const MAX_IMPORT_PLAN_ID_BYTES: usize = 128;
const MAX_IMPORT_PLAN_PAYLOAD_BYTES: usize = 4 * 1024 * 1024;
const MAX_IMPORT_PLAN_PAYLOAD_BYTES: usize = 16 * 1024 * 1024;
const MAX_LEGACY_IMPORT_PLAN_PAYLOAD_BYTES: usize = 4 * 1024 * 1024;
const DANGLING_OPENAPI_SOURCE_GRACE: time::Duration = time::Duration::minutes(5);
impl PostgresRegistry {
@@ -119,6 +123,25 @@ impl PostgresRegistry {
});
}
let digest = plan_digest_from_payload(request.payload)?;
let v2 = request
.payload
.get("schema_version")
.and_then(Value::as_str)
== Some("import-plan-v2");
if v2 {
semantic::validate_v2_metadata(request.payload)?;
plan_apply::validate_v2_creation(&request, &digest)?;
if request
.payload
.get("plan_reference")
.and_then(Value::as_str)
!= Some(request.id.as_str())
|| request.payload.get("job_id").and_then(Value::as_str)
!= Some(request.job_id.as_str())
{
return Err(RegistryError::InvalidImportPlan { field: "identity" });
}
}
let mut transaction = self.pool.begin().await?;
@@ -195,12 +218,31 @@ impl PostgresRegistry {
job_id: request.job_id.as_str().to_owned(),
});
}
if v2 {
semantic::validate_v2_sources(request.payload, &preview_payload)?;
}
sqlx::query("select id from workspaces where id = $1 for update")
.bind(request.workspace_id.as_str())
.fetch_one(&mut *transaction)
.await?;
if v2
&& request
.payload
.get("catalog_revision")
.and_then(Value::as_str)
!= Some(
catalog::catalog_revision(&mut *transaction, request.workspace_id, true)
.await?
.as_str(),
)
{
return Err(RegistryError::ImportPlanFingerprintStale {
plan_id: request.id.as_str().to_owned(),
});
}
// Authoritative re-check: any concurrent insert of this (workspace, id)
// must also hold the workspace lock, so a winner cannot appear between
// the fast-path check and the insert.
@@ -878,22 +920,6 @@ fn map_import_plan(row: &PgRow) -> Result<ImportPlan, RegistryError> {
})
}
/// 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<String, RegistryError> {
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<ImportPlan, RegistryError> {
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;
@@ -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<Vec<String>, 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<String, RegistryError> {
catalog_revision(&self.pool, workspace_id, false).await
}
}
pub(super) async fn catalog_revision<'c, E>(
executor: E,
workspace_id: &WorkspaceId,
lock: bool,
) -> Result<String, RegistryError>
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::<Value, _>("metadata"))
.collect::<Result<Vec<_>, _>>()?;
Ok(format!(
"{:x}",
Sha256::digest(serde_json::to_vec(&metadata)?)
))
}
@@ -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));
@@ -16,6 +16,16 @@ pub(super) struct StoredPlan {
pub(crate) selection: StoredPlanSelection,
pub(crate) counts: StoredPlanCounts,
pub(crate) candidates: Vec<StoredPlanCandidate>,
#[serde(default)]
pub(crate) catalog_revision: Option<String>,
#[serde(default)]
pub(crate) excluded_reasons: Vec<StoredExcludedReason>,
}
#[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::<Result<BTreeSet<_>, _>>()?;
let expected = plan
.selection
.all
.iter()
.map(String::as_str)
.collect::<BTreeSet<_>>();
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::<BTreeSet<_>>();
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()
@@ -203,7 +203,13 @@ fn excluded_outcomes(plan: &StoredPlan) -> Vec<ImportPlanCandidateReport> {
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()
}
@@ -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::<Vec<_>>();
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::<String, _>("name")? == target.name
&& deserialize_enum_text::<OperationStatus>(
row.try_get("status")?,
"status",
)? == target.expected_state.status
&& row.try_get::<i32, _>("current_draft_version")? as u32
== target.expected_state.current_draft_version
&& row
.try_get::<Option<i32>, _>("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(())
}
}
@@ -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<String, RegistryError> {
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<std::collections::BTreeSet<(String, String)>, 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());
}
}
@@ -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()
}
@@ -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(&registry, "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(&registry, &ws, "job_v2_digest_a", "src_v2_a", first_time).await;
let second_job =
create_job_with_source(&registry, &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(
&registry,
&ws,
&first_job,
"plan_v2_digest_a",
&first_payload,
first_time,
)
.await;
let (_, second_digest) = store_plan(
&registry,
&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(&registry, "ws_v2_semantics").await;
let job = create_pending_openapi_job(
&registry,
&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(&registry, &ws, &job, "plan_semantic_base", &base, now).await;
let (_, selection_digest) = store_plan(
&registry,
&ws,
&job,
"plan_semantic_selection",
&changed_selection,
now,
)
.await;
let (_, name_digest) = store_plan(
&registry,
&ws,
&job,
"plan_semantic_name",
&changed_name,
now,
)
.await;
let (_, decision_digest) = store_plan(
&registry,
&ws,
&job,
"plan_semantic_decision",
&changed_decision,
now,
)
.await;
let (_, support_matrix_digest) = store_plan(
&registry,
&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(&registry, "ws_v1_compat").await;
let job = create_pending_openapi_job(
&registry,
&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(&registry, "ws_catalog_revision").await;
let foreign = create_workspace(&registry, "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(&registry, "ws_v2_drift").await;
let job = create_pending_openapi_job(
&registry,
&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(&registry, &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(&registry, "ws_v2_apply").await;
let job = create_pending_openapi_job(
&registry,
&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(&registry, &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(&registry, "ws_v2_excluded_reason").await;
let job = create_pending_openapi_job(
&registry,
&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(
&registry,
&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(&registry, "ws_v2_limit").await;
let job = create_pending_openapi_job(
&registry,
&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(&registry, &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;
}
+45 -3
View File
@@ -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.
+3 -3
View File
@@ -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},