# Исходный подробный контракт этапа 2 Снимок локального плана `_bmad-output/planning-artifacts/epics.md`. Исходная ревизия: `78dc060b8a5086b1cc7a1bec77385a0f2471fbf3`. Дата переноса: 2026-10-04. Технический текст ниже сохранён дословно, чтобы перенос не изменял обязательные критерии. Основные описания этапов и задач в Gitea написаны на русском языке. ## Epic 2: Надёжное создание Tools из реальных OpenAPI Пользователь загружает OpenAPI/Swagger, получает детерминированный preview, исправляет findings и атомарно создаёт пригодные к публикации Operations без silent loss. ### Story 2.1: Реализовать безопасное immutable artifact storage As an оператор закрытого контура, I want хранить загруженные bytes в отдельном защищённом content-addressed store, So that последующие слои получают неизменяемый source без доверия к пользовательским путям. **Requirements:** FR-7, FR-9 **Depends on:** Epic 1 production foundation **Acceptance Criteria:** **Given** bounded source bytes **When** `crank-artifacts` сохраняет artifact **Then** SHA-256 становится единственным opaque physical reference, запись проходит через private temporary file, file fsync, atomic no-clobber publish и directory fsync **And** повторная или конкурентная запись одинаковых bytes идемпотентно использует один immutable blob. **Given** read operation по opaque reference **When** blob существует **Then** store повторно вычисляет и проверяет digest до возврата bytes **And** missing, truncated или corrupted blob возвращает typed integrity error без raw path/source в diagnostics. **Given** hostile filename, traversal, absolute path, symlink или root replacement race **When** выполняется write/read/delete/list candidate **Then** операция не выходит из configured artifact root и не следует symlink **And** caller не может создать новый `file://` reference либо передать filesystem path вместо digest. **Given** crash, disk-full, interrupted publish или stale temporary file **When** store восстанавливается либо запускает bounded housekeeping primitives **Then** опубликованный blob остаётся либо полностью durable, либо отсутствует, временные файлы распознаются безопасно **And** store не принимает policy-решение об удалении referenced blob без подтверждения registry. **Given** legacy absolute `file://` reference **When** compatibility reader явно настроен оператором **Then** read разрешён только внутри canonical validated legacy root и только с expected digest **And** reference не переписывается и исходный файл не удаляется этой story. **Given** artifact crate test suite **When** запускаются unit и filesystem integration tests **Then** покрыты known digest, concurrent dedupe, corruption, crash boundaries, disk-full seam, traversal, symlink/root races, stale temp и legacy-root escape **And** `cargo test -p crank-artifacts` и workspace formatting/lint gates проходят. ### Story 2.2: Добавить workspace-scoped metadata artifacts As an администратор workspace, I want artifact metadata быть транзакционными и изолированными по workspace, So that дедупликация не раскрывает чужие source metadata, а последующий reconciliation получает строгий PostgreSQL contract. **Requirements:** FR-7, FR-9 **Depends on:** Story 2.1 **Acceptance Criteria:** **Given** действующая migration authority **When** добавляется forward-only registry schema version **Then** metadata хранит scoped source id, workspace owner, digest/ref, size, MIME, sensitivity, lifecycle state и timestamps **And** прежние migration sources не изменяются, schema guard и clean/upgrade migration tests проходят. **Given** один physical digest связан с несколькими workspace **When** metadata создаётся, читается или перечисляется **Then** ownership relations независимы и все repository operations требуют authoritative workspace scope **And** foreign id/ref возвращает обычный scoped not-found без existence, size или MIME oracle. **Given** одна и та же source identity либо digest replayed **When** repository создаёт или изменяет scoped relation **Then** identical replay идемпотентен, conflicting replay возвращает typed conflict, а lifecycle timestamps и detach transition проверяются транзакционно **And** schema заранее содержит bounded blob lifecycle/claim fields, необходимые Stories 2.3 и 2.4, без запуска filesystem cleanup из этой story. **Given** metadata существует, но blob отсутствует или повреждён **When** repository/service запрашивает source **Then** typed availability/integrity outcome блокирует дальнейшую обработку **And** система не подменяет source mutable external content и не удаляет metadata молча. **Given** scoped metadata с корректным, отсутствующим или повреждённым blob **When** service выполняет verified read **Then** корректные bytes возвращаются только после digest/size verification, а typed availability/integrity outcome блокирует дальнейшую обработку **And** metadata сохраняется без external refetch, substitution или раскрытия raw source/path. **Given** registry metadata integration suite **When** выполняются clean/V11→V12/replay/tamper/rollback, scoped CRUD/list/detach и verified-read scenarios **Then** exact normalized schema guard отклоняет drift каждого V12 column/default/constraint/index и неожиданный V12-owned object без substring matching **And** migration, replay, cross-workspace, missing/corrupt и pagination tests проходят последовательно и детерминированно. ### Story 2.3: Artifact filesystem reconciliation As an оператор закрытого контура, I want bounded filesystem reconciliation artifacts, So that orphan candidates можно безопасно и resumable обнаруживать без полного inventory. **Requirements:** FR-7, FR-9 **Depends on:** Stories 2.1, 2.2 **Scope:** bounded filesystem scan, opaque continuation, capability revalidation, quarantine/delete primitives и filesystem fault classification. **Acceptance Criteria:** обязательны все пять групп из [Shared acceptance scope for Stories 2.3 and 2.4](#shared-acceptance-scope-for-stories-23-and-24) ниже в части filesystem contract. Это общие критерии двух stories, а не отсутствие AC у Story 2.3; индивидуальные подробности сохраняет canonical spec. ### Story 2.4: Artifact claim recovery As an оператор закрытого контура, I want bounded claim/recheck/finalize recovery coordination, So that referenced blobs не удаляются, а crash/race outcomes безопасно возобновляются. **Requirements:** FR-7, FR-9 **Depends on:** Stories 2.1, 2.2, 2.3 **Scope:** PostgreSQL claim/recheck/finalize protocol, startup recovery и bounded Admin coordinator. #### Shared acceptance scope for Stories 2.3 and 2.4 Обе завершённые stories вместе сохраняют исходный общий scope acceptance criteria ниже; их разделение не меняет requirements или outcome. **Acceptance Criteria:** **Given** published bytes без metadata либо detached digest старше grace period **When** reconciliation выполняет bounded streaming scan **Then** filesystem traversal не строит полный tree inventory и останавливает syscall work при `scan_budget` либо `result_limit` **And** opaque continuation указывает позицию до первого unreturned/retryable item, поэтому неизменный traversal выдаёт eligible set exact-once без starvation. **Given** orphan candidate claimed по digest **When** одновременно появляется active source relation **Then** транзакционный global reference recheck отклоняет stale claim до физической мутации **And** capability revalidates root, shard, quarantine name/path и inode непосредственно перед idempotent unlink. **Given** unlink/quarantine mutation выполнена, но DB commit либо directory fsync завершился ошибкой или неопределённо **When** текущий или следующий reconciliation восстанавливается **Then** outcome типизирован как retryable/uncertain и сохраняет безопасный continuation до failed item либо явно начинает новый bounded cycle **And** claim после возможного unlink не освобождается в `idle`; already-absent recovery идемпотентно доводит PostgreSQL state до `absent`. **Given** interrupted quarantine/delete, malformed namespace entry или exhausted batch **When** startup recovery идёт до final orphan sweep **Then** каждый item классифицируется как restored, deleted-duplicate, retryable, uncertain, integrity-blocked либо safety-blocked без пропуска последующей работы **And** report содержит только bounded low-cardinality counts и usable continuation, без digest, workspace, source или filesystem path. **Given** reconciliation fault/race suite **When** выполняются multi-page exact-once, multi-orphan post-delete continuation, attach-vs-cleanup, inode/name/path races, crash windows и fsync/DB failure injections **Then** ни один active/referenced blob не удаляется, failed item не теряется, а restart завершает recoverable transitions детерминированно **And** artifact, registry и Admin API integration suites вместе с workspace verification gates проходят. ### Story 2.5: Ввести bounded multipart upload и verified OpenAPI preview As an администратор, I want загрузить OpenAPI YAML или JSON через безопасный Admin API contract, So that preview и последующий import ссылаются на одни и те же проверенные bytes. **Requirements:** FR-7, FR-9 **Depends on:** Stories 2.1, 2.2, 2.3, 2.4 **Acceptance Criteria:** **Given** authenticated workspace-scoped OpenAPI preview endpoint **When** администратор передаёт один `.yaml`, `.yml` или `.json` файл через multipart **Then** authorization/workspace, multipart shape, filename, media type, byte size (не более 256 KiB) и UTF-8 проверяются до artifact publish и parsing **And** empty, oversized, malformed, duplicate-part или unsupported input отклоняется stable localized 4xx/413 outcome без metadata, import job или Draft Operations. **Given** допустимый upload **When** Admin API создаёт source snapshot **Then** orchestration выполняет durable blob write, scoped metadata commit и verified read, после чего parser получает именно сохранённые bytes **And** import job хранит scoped source identity и digest, а не raw source или caller path. **Given** preview уже создан **When** apply либо повторный preview использует source **Then** source читается по scoped metadata и digest проверяется заново **And** draft/input нельзя построить только из сохранённого preview JSON при отсутствующем или изменённом artifact. **Given** invalid parser input, storage/registry failure, cancellation или client disconnect **When** request завершается ошибкой **Then** частично созданные business entities отсутствуют, orphan обрабатывается lifecycle protocol **And** RU/EN envelope содержит bounded code, Request ID и Trace ID без source, parser details и filesystem path. **Given** canary в examples/descriptions и полный request trace **When** upload успешно или ошибочно проходит HTTP boundary **Then** raw document отсутствует в logs, traces, metrics и response diagnostics **And** request можно сопоставить в интерфейсе и GlitchTip по canonical Trace ID. **Given** outer Admin API integration suite **When** тестируется реальный multipart router и service stack **Then** покрыты valid YAML/JSON, malformed multipart, limits, unsupported encoding/MIME, scope isolation, restart, corruption, cancellation и no-Draft guarantees **And** legacy JSON test-only compatibility path не считается доказательством production contract. ### Story 2.6: Завершить OpenAPI upload UX и release evidence As an администратор, I want понятный, локализованный и race-safe интерфейс загрузки OpenAPI, So that я вижу актуальный результат файла и могу безопасно восстановиться после ошибки. **Requirements:** FR-7, FR-9 **Depends on:** Story 2.5 **Acceptance Criteria:** **Given** OpenAPI upload UI на RU и EN **When** пользователь выбирает, валидирует, загружает, заменяет или отменяет файл **Then** присутствуют keyboard-accessible idle, validating, uploading, error, cancelled и success states **And** показываются только bounded metadata, Request ID/Trace ID и actionable recovery, без raw source и внутренних путей. **Given** file replacement, workspace/language change, navigation либо параллельный запрос **When** старый response приходит позже нового **Then** AbortController и monotonic identity/revision guard запрещают stale state update **And** новый файл и authoritative workspace остаются выбранными. **Given** network, validation, integrity или service failure **When** пользователь повторяет действие **Then** retry не создаёт duplicate source relation или Draft Operations **And** focus, screen-reader status и reduced-motion соответствуют общему UI contract. **Given** production documentation **When** оператор настраивает artifact root, upload limits, backup/restore и reconciliation **Then** docs точно описывают multipart contract, lifecycle, legacy compatibility, security boundaries и redacted observability **And** не заявляют гарантий, не доказанных текущими tests/evidence. **Given** real-stack Playwright и release gates **When** выполняются valid upload, replacement race, cancel, RU/EN, accessibility, restart и failure recovery scenarios **Then** UI обращается к production multipart endpoint без test-only bypass и подтверждает canonical Trace ID **And** artifact/registry/Admin API/Playwright suites, `just verify` и `just verify-ui` проходят либо внешний инфраструктурный blocker задокументирован с воспроизводимой командой. ### Story 2.7: Преобразовать OpenAPI в детерминированный NormalizedIR As an администратор, I want получить устойчивый анализ структуры загруженного API, So that одинаковый документ всегда создаёт одинаковый preview и ни одна исходная конструкция не теряется молча. **Requirements:** FR-7, FR-8 **Acceptance Criteria:** **Given** verified source artifact **When** `crank-import` начинает parsing **Then** формат определяется по содержимому и поддерживает OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0 в YAML/JSON **And** extension файла не используется как единственный источник версии или формата. **Given** parsing operation **When** документ обрабатывается **Then** parser остаётся pure относительно PostgreSQL, artifact metadata и Operations **And** не создаёт Draft, ImportPlan или частичный domain state. **Given** syntactically valid document **When** создаётся `NormalizedIR` **Then** он содержит source digest/version, API metadata, server/base-path candidates, paths, methods, operation identifiers, tags и source locations **And** каждый элемент имеет устойчивый source-construct ID для findings и coverage ledger. **Given** Swagger 2.0 либо OpenAPI 3.x document **When** эквивалентные верхнеуровневые concepts нормализуются **Then** различия версий отображаются в typed IR, а не в untyped JSON blob **And** source-specific semantics сохраняются до последующих mapping stages. **Given** каждый распознанный source construct **When** normalization завершается **Then** construct связан с normalized representation либо explicit finding со stable code, severity и source location **And** отсутствие mapping без finding считается validator failure. **Given** duplicate или отсутствующий `operationId` **When** формируются internal candidate identities **Then** importer применяет детерминированное naming rule из method/path/source order и создаёт явный finding **And** повторный анализ не меняет имена из-за map ordering или runtime randomness. **Given** unsupported specification version, invalid root shape или документ без методов **When** выполняется parsing **Then** возвращается bounded structured blocker finding **And** процесс не panic-ит, не создаёт пустой успешный import и не выводит raw parser internals. **Given** structural error, ограниченный одним endpoint **When** остальные endpoints могут быть проанализированы **Then** IR сохраняет валидные candidates и blocker finding повреждённого endpoint **And** общий preview не разрешает Apply без explicit partial selection из последующей story. **Given** unresolved local или external reference **When** parsing завершается до reference-resolution stage **Then** IR содержит typed unresolved reference и source location **And** parser не выполняет network или filesystem access самостоятельно. **Given** malicious YAML/JSON shape **When** document превышает configured depth, node, alias, string или collection limits **Then** parsing прерывается bounded error без unbounded CPU/memory growth **And** diagnostic сохраняет валидный UTF-8/JSON и не включает исходный документ целиком. **Given** одинаковые source bytes и importer configuration **When** normalization запускается многократно и конкурентно **Then** canonical IR и ordered findings совпадают byte-for-byte **And** source digest однозначно идентифицирует результат анализа. **Given** importer test suite **When** выполняются fixture, property и fuzz regression tests **Then** покрыты три версии specifications, YAML/JSON, duplicate IDs, empty/no-method documents, hostile nesting, aliases, malformed endpoints и deterministic ordering **And** `crank-import` соблюдает architecture boundaries и проходит `just verify`. ### Story 2.8: Безопасно разрешать references и schema composition As an администратор, I want импортировать API со связанными schemas и разрешёнными external references, So that сложные контракты сохраняют семантику и не создают SSRF или TOCTOU. **Requirements:** FR-9 **Acceptance Criteria:** **Given** local `$ref` внутри source artifact **When** reference resolver обрабатывает JSON Pointer **Then** target разрешается относительно immutable source snapshot с корректным escaping **And** missing target, invalid pointer или type mismatch создаёт finding с source/target location без panic. **Given** external references по умолчанию **When** документ содержит HTTP/HTTPS reference **Then** network fetch не выполняется и reference получает explicit blocker/unsupported finding **And** администратор видит, что требуется operator-controlled allowlist либо offline bundle. **Given** explicitly allowlisted external reference **When** resolver загружает document **Then** используется shared OutboundPolicy с более узким scheme/host/port/path/size contract, actual-address validation и disabled system proxy/implicit redirects **And** credential из OpenAPI document или source URL не принимается автоматически. **Given** разрешённый external document **When** preview загружает его успешно **Then** bytes сохраняются как immutable content-addressed artifact с digest и ownership metadata **And** NormalizedIR ссылается только на snapshot artifact, а не на mutable remote URL. **Given** remote content изменилось после preview **When** ImportPlan применяется позднее **Then** Apply использует сохранённые snapshot digests и не выполняет повторный network fetch **And** получение новых remote bytes требует нового preview и нового plan digest. **Given** относительная external reference chain **When** resolver вычисляет следующий target **Then** URL нормализуется относительно текущего snapshot origin в пределах allowlist и bounded hop/depth/count limits **And** traversal к `file:`, loopback, private service или иному запрещённому origin блокируется. **Given** recursive или cyclic references **When** resolver строит schema graph **Then** recursion представляется typed graph reference в пределах supported semantics **And** превышение cycle/depth/expanded-size limits создаёт blocker finding без бесконечной рекурсии или schema duplication. **Given** `allOf` composition **When** branches совместимы **Then** required fields, properties, constraints и source provenance объединяются детерминированно **And** conflicting constraints создают явный blocker вместо last-write-wins. **Given** `oneOf`, `anyOf` или discriminator **When** capability schema может сохранить конструкцию без semantic loss **Then** alternatives и discriminator mapping остаются typed в resolved IR **And** неподдерживаемая комбинация блокирует affected candidate с точным finding, а не упрощается молча. **Given** OpenAPI 3.0 и 3.1 имеют различную `$ref` sibling semantics **When** resolver обрабатывает sibling fields **Then** применяется правило фактической specification version **And** результат и finding подтверждены отдельными fixtures. **Given** один reference target повреждён или недоступен **When** остальные candidates анализируются **Then** affected dependency graph получает blocker finding, остальные candidates остаются в preview **And** Apply всего документа остаётся запрещён без explicit partial selection. **Given** concurrent previews разных workspace **When** они используют одинаковые URLs или bytes **Then** resolution cache и ownership metadata включают полный security scope **And** timing, error или cache response не раскрывает другому workspace наличие snapshot. **Given** reference/composition test suite **When** выполняются fixtures и negative tests **Then** покрыты local refs, escaped pointers, external allow/deny, redirects, DNS rebinding, relative chains, TOCTOU, cycles, recursion, `allOf` conflicts, `oneOf`/`anyOf` и discriminators **And** raw remote content и credentials отсутствуют в logs/errors, а `just verify` проходит. ### Story 2.9: Сохранить полный поддерживаемый HTTP contract As an администратор, I want получить из каждого поддерживаемого endpoint точный Operation candidate, So that созданный Tool принимает и возвращает те же данные, которые определены исходным API. **Requirements:** FR-8 **Acceptance Criteria:** **Given** resolved OpenAPI endpoint **When** importer определяет HTTP method **Then** поддерживаются `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` и `OPTIONS` **And** `TRACE`, `CONNECT` и неизвестные methods получают explicit unsupported finding. **Given** parameters на path-level и operation-level **When** они нормализуются **Then** path, query, header и cookie parameters объединяются согласно правилам specification version **And** operation-level override не создаёт duplicate либо silent replacement. **Given** каждый parameter **When** строится Operation input schema и request mapping **Then** сохраняются location, required, default, enum, nullable, format и применимые serialization semantics **And** одинаковые имена в разных locations не конфликтуют во внутренней typed model. **Given** path parameter **When** исходная specification ошибочно не помечает его required либо не содержит соответствующего path placeholder **Then** candidate получает blocker finding **And** importer не создаёт URL template с неоднозначной подстановкой. **Given** OpenAPI request body **When** content type поддерживается **Then** JSON, `application/x-www-form-urlencoded` и `multipart/form-data` преобразуются в typed input schema и deterministic mapping **And** required body, required fields и content type сохраняются. **Given** multipart body **When** schema содержит text, scalar, array или binary/file fields **Then** importer сохраняет field names, required status, MIME metadata и bounded upload expectations **And** unsupported multipart encoding получает finding вместо silent fallback к JSON. **Given** XML request/response media type **When** он обнаружен **Then** affected content variant получает explicit unsupported finding в соответствии с release scope **And** XML не преобразуется неявно в JSON или text. **Given** endpoint с одним или несколькими успешными `2xx` responses **When** строится output contract **Then** сохраняются status codes, content types и все поддерживаемые success schemas **And** importer не выбирает произвольно первый response и не теряет остальные branches. **Given** `204 No Content`, `HEAD` либо success response без body **When** строится output schema **Then** candidate получает явный no-content outcome без требования JSON body **And** runtime mapping не классифицирует корректный пустой response как schema error. **Given** API/server/base-path metadata **When** строится REST target template **Then** scheme, host, port и base path нормализуются без embedded credential и проходят typed validation **And** фактическое execution по-прежнему подчиняется OutboundPolicy из Story 1.9. **Given** descriptions, examples или defaults из source document **When** они включаются в candidate preview **Then** значения bounded и не влияют на executable mapping без явного typed contract **And** secret-like examples создают finding и не попадают в generated headers/Auth Profile. **Given** unsupported parameter style, schema keyword, content type или response shape **When** candidate формируется **Then** coverage ledger содержит точный source construct и finding severity **And** blocker semantic loss не может быть помечена как actionable Draft. **Given** одинаковый resolved IR **When** HTTP mapping запускается повторно **Then** Operation candidates, input/output schemas и mappings совпадают детерминированно **And** каждый candidate можно сериализовать и валидировать без обращения к исходному parser state. **Given** HTTP-contract test suite **When** выполняется representative matrix **Then** покрыты все обязательные methods, четыре parameter locations, JSON/form/multipart, multiple 2xx, 204, defaults/enums/nullability/formats и unsupported XML **And** каждый fixture доказывает expected semantics либо expected finding, а `just verify` проходит. ### Story 2.10: Привязать security schemes через безопасный import API **Depends on:** Story 2.9, Story 1.10 **Work type:** implementation **Deliverable:** Привязать security schemes через безопасный import API. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an администратор, I want сопоставлять OpenAPI security requirements с Auth Profiles через import API, So that безопасно сохраняю authentication contract без импорта credentials. **Requirements:** FR-10 **Acceptance Criteria:** **Given** OpenAPI 3.x `components.securitySchemes` или Swagger 2.0 `securityDefinitions` **When** importer анализирует schemes **Then** bearer HTTP, basic HTTP и API key в header/query/cookie преобразуются в typed security metadata **And** source names, locations и применимые format hints сохраняются без credential values. **Given** global security requirement **When** Operation не задаёт собственный override **Then** candidate наследует global requirement согласно specification semantics **And** operation-level requirement или explicit no-auth корректно заменяет global rule. **Given** security requirement с несколькими alternatives **When** source определяет OR-семантику **Then** preview сохраняет все допустимые alternatives и позволяет выбрать поддерживаемый вариант **And** importer не объединяет alternatives в ложное обязательное AND. **Given** security requirement, требующий несколько schemes одновременно **When** source определяет AND-семантику **Then** candidate сохраняет составное требование, если runtime contract его поддерживает **And** иначе affected Operation получает blocker finding с перечислением несохраняемой semantics. **Given** bearer, basic или API-key requirement **When** формируется preview **Then** администратору предлагается выбрать совместимый Auth Profile из текущего workspace либо оставить явный unresolved binding **And** unresolved required authentication блокирует actionable Draft/Apply для affected Operation. **Given** выбранный Auth Profile **When** создаётся candidate или ImportPlan **Then** сохраняется только typed `AuthProfileRef` и scheme metadata **And** raw secret, password, token, API key, hash или encrypted ciphertext не копируется в source snapshot, IR, findings, plan или Operation export. **Given** OAuth2, OpenID Connect, mutual TLS или неизвестная scheme **When** release scope не поддерживает автоматическое mapping **Then** importer создаёт explicit manual-configuration/unsupported finding **And** не извлекает client secret, token URL credential, example token или vendor-extension secret. **Given** OpenAPI document содержит literal credential в example, default, extension, URL userinfo или header example **When** security analysis выполняется **Then** значение не используется как credential и создаёт redacted secret finding **And** raw value не появляется в preview UI, logs, traces, metrics или diagnostics. **Given** Auth Profile был отозван, удалён или принадлежит другому workspace **When** preview либо Apply проверяет binding **Then** reference отклоняется до создания Draft **And** ошибка не раскрывает metadata foreign profile. **Given** исходная security scheme изменилась после preview **When** старый ImportPlan пытаются применить к новому source **Then** plan digest mismatch блокирует Apply **And** требуется новый preview и явное подтверждение Auth Profile mappings. **Given** security scheme test suite **When** выполняются fixtures и negative tests **Then** покрыты global/operation overrides, no-auth, bearer/basic/API-key locations, OR/AND requirements, OAuth/OpenID/unknown schemes, secret-like examples, revoked и cross-workspace refs **And** redaction tests и `just verify` проходят. ### Story 2.11: Выбирать security mappings в OpenAPI UI **Depends on:** Story 2.10 **Work type:** implementation **Deliverable:** Выбирать security mappings в OpenAPI UI. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an администратор, I want выбирать profile и security alternative в OpenAPI UI, So that вижу unresolved/resolved/blocker state без раскрытия secrets. **Requirements:** FR-10 **Acceptance Criteria:** **Given** preview сохраняет OR alternatives и required authentication **When** администратор выбирает alternative либо совместимый Auth Profile текущего workspace **Then** UI передаёт выбор существующему import API и показывает authoritative resolved/unresolved/blocker status **And** raw credentials не вводятся в mapping state и не копируются в IR/plan. **Given** смена alternative, удалённый/отозванный profile либо stale preview response **When** API повторно валидирует binding **Then** UI показывает safe blocker/revalidation guidance, не выдаёт предыдущий resolved state за текущий **And** OR/AND semantics, workspace validation и secret redaction остаются ответственностью API Story 2.10. **Given** security-mapping UI на RU и EN **When** пользователь выбирает profile, меняет alternative или получает unsupported scheme **Then** UI показывает required/unresolved/resolved status, safe profile metadata и blocker findings **And** loading, empty, error и stale-response states не раскрывают secrets. ### Story 2.12: Предоставить полный preview и явный partial mode **Depends on:** Story 2.11 **Work type:** implementation **Deliverable:** Предоставить полный preview и явный partial mode. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an администратор, I want до импорта просмотреть все будущие Operations и проблемы документа, So that могу осознанно исправить контракт либо импортировать только безопасную выбранную часть. **Requirements:** FR-7 **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** подготовлен исполняемый Reference benchmark/evidence template для проверки интерактивности ≤2 s p95 на Reference Deployment LAN при отдельной приёмке; development done требует bounded-rendering tests и готовый протокол, а не внешний замер. **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 проходят. ### Story 2.13: Атомарно применять ImportPlan и обрабатывать re-import **Depends on:** Story 2.12 **Work type:** implementation **Deliverable:** Атомарно применять ImportPlan и обрабатывать re-import. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an администратор, I want применить подтверждённый ImportPlan с выбранной conflict policy, So that импорт создаёт ровно ожидаемые Draft Operations и безопасно переживает retries и concurrency. **Requirements:** FR-11 **Acceptance Criteria:** **Given** request на Apply **When** Admin API принимает plan reference, digest и idempotency key **Then** проверяются workspace ownership, Admin authorization, immutable plan digest и bounded request contract **And** raw candidate data от клиента не используется вместо сохранённого ImportPlan. **Given** валидный ImportPlan **When** начинается Apply **Then** повторно проверяются source/external artifact digests, importer/support-matrix version, selected candidates, dependency closure, Auth Profile refs и актуальные conflicts **And** stale либо повреждённый plan блокируется до mutation с re-preview guidance. **Given** default full-import plan **When** хотя бы один selected candidate больше не actionable **Then** весь Apply отклоняется без создания или изменения Operations **And** report перечисляет точные revalidation failures. **Given** explicit partial ImportPlan **When** он применяется **Then** одной transaction обрабатывается ровно подтверждённый selected set **And** excluded candidates не создаются неявно и сохраняются в report с причиной исключения. **Given** candidate без существующего Operation conflict **When** Apply создаёт результат **Then** создаются новая Operation и её Draft Version с contract из plan **And** созданный Draft не становится доступным в Agent/MCP до отдельной публикации. **Given** conflict policy `skip` **When** соответствующая Operation уже существует **Then** существующее состояние не изменяется, candidate получает outcome `skipped` **And** report связывает outcome с exact existing identity без раскрытия foreign-scope metadata. **Given** conflict policy `rename` **When** выбранное новое имя свободно и валидно **Then** создаётся отдельная Operation с подтверждённым именем **And** runtime не генерирует другое имя во время Apply. **Given** conflict policy `new_version` **When** target Operation принадлежит workspace и совместима с versioning contract **Then** создаётся новая Draft Version без изменения текущей Published Version **And** предыдущие versions, Agent bindings и Invocation History остаются immutable. **Given** concurrent Apply одного либо пересекающихся plans **When** возникает uniqueness/revision conflict **Then** PostgreSQL locks/conditional predicates допускают один согласованный commit **And** проигравший Apply возвращает deterministic conflict/re-preview outcome без частичной mutation. **Given** повтор Apply с тем же scoped idempotency key и тем же plan digest **When** первоначальный Apply уже committed **Then** возвращается тот же immutable result report без создания дополнительных versions **And** тот же key с другим digest возвращает conflict. **Given** crash до transaction commit **When** клиент повторяет Apply **Then** отсутствует частично видимое domain state, а replay может выполнить plan заново **And** orphan artifact cleanup не удаляет snapshots действующего plan. **Given** crash после commit, но до HTTP response **When** клиент повторяет request **Then** idempotency record возвращает committed result **And** Operations и versions не дублируются. **Given** успешный или отклонённый Apply **When** формируется итоговый report **Then** report immutable и содержит plan/source digests, counts и outcomes `created`, `versioned`, `renamed`, `skipped`, `rejected` для каждого candidate **And** report bounded, redacted и доступен в human-readable и machine-readable form. **Given** Apply UI на RU и EN **When** пользователь подтверждает import, ожидает результат или получает stale/conflict outcome **Then** UI показывает exact candidate counts, destructive/versioning consequences, loading, success, partial, conflict и retry guidance **And** duplicate click или stale response не запускает второй логический Apply. **Given** Apply integration suite **When** выполняются transaction, crash и concurrency tests **Then** покрыты все conflict policies, full/partial atomicity, idempotent replay, changed digest, Auth Profile revocation, concurrent plans и Draft isolation **And** проходят registry/Admin API/Playwright tests и `just verify`. ### Story 2.14: Зафиксировать OpenAPI support matrix и regression corpus **Depends on:** Story 2.13 **Work type:** implementation **Deliverable:** Зафиксировать OpenAPI support matrix и regression corpus. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As a владелец релиза, I want иметь исполняемую матрицу поддержки и репрезентативный corpus OpenAPI, So that качество importer измеряется по сохраняемой семантике, а не по числу созданных Operations. **Requirements:** FR-12 **Acceptance Criteria:** **Given** normative support matrix **When** описывается OpenAPI/Swagger construct **Then** запись содержит specification/version, construct ID, status `supported` или `unsupported`, точную сохраняемую semantics и expected finding **And** неопределённый `partial` status без явного пользовательского выбора запрещён. **Given** обязательный baseline matrix **When** проверяется полнота **Then** она включает все REST methods кроме `TRACE`/`CONNECT`, path/query/header/cookie parameters, JSON/form/multipart bodies, все `2xx` responses, local и allowlisted external refs, common composition и bearer/basic/API-key schemes **And** XML и другие non-goals перечислены с explicit unsupported outcome. **Given** versioned regression corpus **When** он формируется **Then** corpus содержит не менее 50 checksummed реальных или синтетических OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0 specifications **And** provenance/license либо synthetic origin каждого fixture документированы. **Given** corpus fixture **When** harness выполняет preview **Then** fixture содержит expected candidates, schemas/mappings, findings, actionable/blocker statuses и canonical digest **And** любое отличие создаёт readable deterministic diff. **Given** selected end-to-end fixtures **When** harness выполняет полный workflow **Then** документ загружается через реальный upload contract, preview формирует ImportPlan, Apply создаёт Draft, а representative Operation проходит validate/publish/test/MCP call **And** bypass parser/import APIs не считается end-to-end evidence. **Given** все Operations в утверждённом representative corpus **When** вычисляется import quality **Then** ≥95% становятся actionable Draft без blocker finding **And** denominator, exclusions и raw counts фиксируются в immutable result artifact. **Given** source construct coverage ledger **When** corpus run завершается **Then** каждый construct соответствует expected normalized semantics либо explicit expected finding **And** silent loss относительно support matrix равен нулю и блокирует gate независимо от actionable percentage. **Given** defect importer **When** исправление принимается **Then** сначала добавляется минимальный воспроизводящий fixture и failing regression **And** fixture остаётся в corpus после исправления. **Given** hostile-input subset **When** выполняются security/reliability cases **Then** покрыты empty, malformed, oversized, deep/alias-heavy documents, reference cycles, external-ref policy, duplicate IDs, composition conflicts и secret-like examples **And** harness доказывает bounded resources, no mutation on blocker и redacted outputs. **Given** изменение support matrix, importer semantics или corpus expectation **When** создаётся pull request **Then** matrix/corpus version повышается, diff требует review, а новый checksum включается в evidence **And** существующий expectation нельзя переписать без объяснения compatibility impact. **Given** corpus execution в CI **When** suites запускаются повторно или параллельно **Then** результаты не зависят от network, wall-clock ordering или shared mutable database **And** обязательные tests не flaky и используют immutable/offline fixtures. **Given** опубликованная compatibility documentation **When** пользователь проверяет возможности importer **Then** human-readable matrix генерируется либо проверяется против machine-readable source **And** маркетинговое описание не шире исполняемого evidence. **Given** завершение Epic 2 verification **When** запускаются importer, artifact, registry, API, Playwright и corpus suites **Then** FR-7…FR-12 связаны с immutable evidence, `just verify` проходит **And** Capability Inventory обновлена без преждевременного статуса production-ready. ### Story 2.15: Добавить OpenAPI-ветку в guided onboarding **Depends on:** Story 2.14 **Work type:** implementation **Deliverable:** Добавить OpenAPI-ветку в guided onboarding и подготовить единый документ приёмочного тестирования всех восьми эпиков. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As a новый self-hosted администратор, I want начать onboarding с готового `openapi.yaml`, So that получаю первый MCP Tool call без ручного переноса REST-контракта. **Requirements:** FR-7, FR-11, FR-33 **Acceptance Criteria:** **Given** onboarding из Story 1.16 **When** пользователь выбирает OpenAPI path **Then** UI ведёт в существующий bounded upload/preview flow и сохраняет onboarding return context **And** не создаёт отдельный importer или упрощённый parser path. **Given** preview с actionable endpoints **When** пользователь выбирает endpoint и conflict/partial policy **Then** onboarding показывает methods, findings, exact proposed Operation и последствия apply **And** blocker/unsupported finding нельзя скрыть ради продолжения checklist. **Given** import требует Auth Profile **When** security scheme сопоставляется **Then** пользователь создаёт/выбирает только secret reference через canonical Auth Profile UI **And** raw credential не попадает в OpenAPI artifact или onboarding state. **Given** atomic ImportPlan apply завершён **When** создано несколько Draft Operations **Then** пользователь явно выбирает одну actionable Draft для test/publish, остальные остаются в обычном import report **And** onboarding не публикует endpoint автоматически. **Given** refresh, conflict либо исправление source **When** import повторяется **Then** checklist восстанавливается из authoritative ImportPlan/Operation state и не создаёт duplicate version **And** changed source digest требует новый preview/confirmation. **Given** OpenAPI onboarding events **When** пользователь достигает publication и первого MCP call **Then** local rollups различают eligible import, import-to-publish и Agent activation без raw specification/user IDs **And** data egress остаётся opt-in. **Given** real-stack Playwright suite **When** новый пользователь загружает representative `openapi.yaml` **Then** он проходит preview → apply → test → publish → Agent/key → public MCP call с RU/EN, refresh и failure recovery **And** `just verify` проходит без test-only bypass; поставлен `docs/acceptance-test-plan.md` с трассируемыми сценариями всех восьми эпиков и пятиучастниковым Reference usability protocol, median ≤15 минут и evidence template. Исполнение человеческого протокола относится к отдельной приёмке и не требуется для development done.