35 KiB
title, type, created, status, baseline_revision, review_loop_iteration, followup_review_recommended, context, warnings, deferred
| title | type | created | status | baseline_revision | review_loop_iteration | followup_review_recommended | context | warnings | deferred | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2.12 — Предоставить полный preview и явный partial mode | feature | 2026-10-03 | done | d1ba0bd0e4 |
0 | true |
|
|
|
Intent
Problem: Preview теряет source locations, не показывает deterministic naming conflicts и рендерит все строки; partial импорт получается неявно. Plan digest зависит от случайного ID, а catalog drift не обозначается при повторном открытии.
Approach: Завершить полный детерминированный preview и immutable plan evidence, добавить явный partial mode, bounded UI и read-only plan revalidation. Проверить все AC Story 2.12 на API и пользовательской поверхности.
Boundaries & Constraints
Always: API вычисляет actionable из typed findings/security и verified references. Full mode запрещает Apply при любом blocker всего документа. Partial включается явно, selected candidates должны быть actionable с замкнутыми разрешёнными references; excluded/blocked сохраняют причины в plan/report. Сохранять immutable source/старые plans, workspace isolation, redaction, auth authority и request revision guards. Поддержать до 2000 candidates с bounded rendering и findings, RU/EN и keyboard/live statuses. Только verified external snapshots, без повторного mutable remote fetch. Read-only revalidation не создаёт Operations/versions/bindings/profiles. Canonical digest не включает random plan/job/source row IDs, время, request ID; semantic state, source/external digests, catalog revision и selections входит. Legacy сохранённые планы продолжают проверяться по своему контракту.
Never: Записывать или откатывать sprint-status.yaml. Выполнять whole-epic corpus qualification Story 2.14, onboarding Story 2.15 или расширять atomic Apply Story 2.13 сверх необходимых совместимых проверок этой story. Raw credentials в artifacts/DOM/logs/plans. Выдавать mock/local latency за Reference Deployment proof.
I/O & Edge-Case Matrix
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|---|---|---|---|
| Full/blocker | Один либо document blocker, full mode | Полный count/affected candidates; Apply запрещён, мутаций нет | Safe finding code/location |
| Partial | Явный mode и subset | Только API-actionable с resolved references; excluded/blocked причины в plan/report | Незамкнутый/blocked subset отвергается |
| Determinism | Те же digests/config/catalog/selections, иные request IDs/time | Те же ordered candidates/findings/summary/semantic digest | Changed selection/name/auth/decision меняет digest |
| Naming | Duplicate/invalid/taken name | Conflict type/location и deterministic rename proposal, разрешённый выбор | Snapshot неизменен |
| Stale | Catalog/Auth Profile drift либо старый response | Read-only revalidation показывает stale и снимает прежнюю authority | Re-preview guidance; mutation отсутствует |
| Large | 2000 candidates, bounded findings | Search/filter/groups и bounded pagination, сохранение selection между страницами | Измерение интерактивности p95 ≤2 s с явным environment |
| Upload | valid/invalid/empty/oversized/no-methods RU/EN | Реальные методы, точные безопасные outcomes; до Apply нет Operations | Replacement/context guards |
Code Map
crates/crank-import/src/rest/model.rs:493— ImportFinding и ImportOperationCandidate теряют locations; NormalizedIr/reference_graph сохраняет source pointers/digests.normalize_projection.rs:12— mapping IR → preview;naming.rs— reuse deterministic names;normalize.rs— ordering/typed readiness.apps/admin-api/src/service/imports.rs:55— cap 512; verified upload preview и safe profile choices.imports/verified_preview.rs— immutable replay/fingerprint normalizer/projection/IR/preview digests.dto.rs:544— response view, add bounded typed metadata.apps/admin-api/src/service/imports/import_plan.rs:7— resolve_plan_selection, security bindings, name conflicts, persisted payload including random plan_reference.imports/plan_apply.rs— source/auth drift and safe recovery.routes/imports.rs,app.rs— existing scoped plan routes, add read-only reopen/revalidation route.crates/crank-registry/src/postgres/import_job.rs:94— immutable persistence, canonical payload digest;import_job/plan_apply/material.rs— stored plan validation and limits,verify.rs— apply revalidation. Existing registry catalog reads permit deterministic workspace revision over relevant catalog/auth state; avoid unrelated DB schema abstraction.apps/ui/js/openapi-import.js:778— renderPreview renders all rows; :1728 implicit partial. Reuse decisions/security guards, mapping details, filters and confirmation.apps/ui/index.html— controls;js/i18n.jsRU/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:
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.crates/crank-import/src/rest/model.rs,normalize_projection.rsand minimal constructors — expose source locations/stable codes without semantic loss; backward replay compatibility.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.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.docs/openapi-import.md, checklist and story — document actual contracts, record executed acceptance/latency evidence and limits.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 — serverattach_preview_readinessиglobal_blockerplan 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 якобы отделён от записи — registrycreate_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 явно помечает provenanceoperator_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 verifyPASS, 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остаётся собственностью оркестратора и не изменён.