# Epic 2 Context: Надёжное создание Tools из реальных OpenAPI ## Goal Дать self-hosted администратору безопасный и воспроизводимый путь от OpenAPI/Swagger к пригодным к публикации Draft Operations: сохранить проверенный immutable snapshot, получить детерминированный preview со всеми findings, явно разрешить ограничения и конфликты, затем атомарно применить выбранный ImportPlan без silent loss, утечки секретов и частичных мутаций. Отдельных UX/design и product brief artifacts в planning-каталоге нет; UX-ограничения ниже собраны из PRD и Epic 2 требований. ## Stories - Story 2.1: Реализовать безопасное immutable artifact storage - Story 2.2: Добавить workspace-scoped metadata artifacts - Story 2.3: Реализовать bounded filesystem reconciliation artifacts - Story 2.4: Реализовать artifact claim/recovery coordinator - Story 2.5: Ввести bounded multipart upload и verified OpenAPI preview - Story 2.6: Завершить OpenAPI upload UX и release evidence - Story 2.7: Преобразовать OpenAPI в детерминированный NormalizedIR - Story 2.8: Безопасно разрешать references и schema composition - Story 2.9: Сохранить полный поддерживаемый HTTP contract - Story 2.10: Привязать security schemes через безопасный import API - Story 2.11: Выбирать security mappings в OpenAPI UI - Story 2.12: Предоставить полный preview и явный partial mode - Story 2.13: Атомарно применять ImportPlan и обрабатывать re-import - Story 2.14: Зафиксировать OpenAPI support matrix и regression corpus - Story 2.15: Добавить OpenAPI-ветку в guided onboarding ## Story numbering migration — 2026-09-13 Номера изменены без изменения scope и порядка зависимостей. Для новых запусков и ссылок использовать только текущую колонку. Старые specs перенаправляют на canonical files. Архивные журналы, commits и worktree paths не переименованы: остановленные loop runs со старой нумерацией не возобновлять против нового спринта. HTTP contract теперь Story 2.9; 2026-09-13 коммит `f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8` интегрирован в `main` fast-forward, статус спринта согласован с завершённым spec: `done`. | Historical ID | Current ID | Outcome | |---|---|---| | 2.1a | 2.1 | Artifact store | | 2.1b | 2.2 | Scoped metadata | | 2.1e / 2.1b2a | 2.3 | Filesystem reconciliation | | 2.1f / 2.1b2b | 2.4 | Claim recovery | | 2.1c | 2.5 | Upload / preview API | | 2.1d | 2.6 | Upload UX / evidence | | 2.2 | 2.7 | NormalizedIR | | 2.3 | 2.8 | References / composition | | 2.4 | 2.9 | HTTP contract | | 2.5 | 2.10 / 2.11 | Security schemes API / mapping UI | | 2.6 | 2.12 | Preview / partial mode | | 2.7 | 2.13 | Apply / re-import | | 2.8 | 2.14 | Matrix / corpus | | 2.9 | 2.15 | Guided onboarding | Первоначальная объединённая Story 2.1 (OpenAPI source, до декомпозиции) соответствует текущим 2.1–2.6, а не только новой Story 2.1. Общие пять AC для 2.3/2.4 наследуются обеими stories; их индивидуальные specs уточняют границы ответственности. ## Requirements & Constraints - Upload принимает один UTF-8 `.yaml`, `.yml` или `.json` через bounded multipart contract (до 256 KiB). Пустые, oversized, malformed, неподдержанные и не содержащие методов документы отклоняются до создания Draft или другой бизнес-мутации. - Поддерживаются OpenAPI 3.0/3.1 и Swagger 2.0; сохраняются REST methods (кроме `TRACE`/`CONNECT`), path/query/header/cookie parameters, required/default/enum/nullable/format, JSON/form/multipart bodies и все успешные `2xx` responses, включая `204` и несколько success schemas. XML получает явный unsupported finding. - Local и разрешённые external references, `allOf`/`oneOf`/`anyOf`, recursion и discriminators либо сохраняются, либо блокируют создание объяснимым finding. External fetch выключен по умолчанию, ограничен operator-controlled allowlist/offline bundle и bounded depth/size/cycle policy. - Preview не изменяет Operations, versions, Agent bindings или Auth Profiles. Полный Apply возможен только без blocker findings; partial mode требует явного выбора actionable candidates с замкнутыми dependencies. Конфликты ограничены `skip`, `rename` и `new_version`. - Bearer/basic/api-key schemes связываются только с typed `AuthProfileRef`; OAuth/unknown schemes требуют ручной настройки. Raw credentials не попадают в artifacts, plans, Draft, logs, traces, metrics, diagnostics или exports. - Apply атомарен, идемпотентен и безопасен при retry/concurrency; bounded redacted report перечисляет outcome каждого candidate (`created`, `versioned`, `renamed`, `skipped`, `rejected`). Silent semantic loss запрещён. - Versioned normative support matrix и checksummed corpus содержат не менее 50 fixtures OpenAPI 3.0/3.1 и Swagger 2.0; не менее 95% Operations representative corpus становятся actionable Draft. Исправленный import defect закрепляется regression fixture; E2E использует реальный upload → preview → plan → apply путь. ## Technical Decisions - Канонический pipeline: `ParsedDocument → typed NormalizedIR + complete Findings → immutable ImportPlan → transactional Apply`. Каждый source construct получает stable ID и mapping либо explicit finding; canonical output и plan digest не зависят от времени, map ordering или request IDs. - `crank-artifacts` хранит bounded immutable bytes под opaque SHA-256 reference через private temp file, fsync, atomic no-clobber publish и directory fsync. PostgreSQL хранит workspace ownership, digest/ref, size, MIME, sensitivity и lifecycle/reference state; verified read повторно проверяет digest и размер. - Artifact metadata всегда scoped по authoritative workspace. Reconciliation bounded/resumable, использует grace period и reference recheck и безопасно восстанавливается после unlink/quarantine/DB/fsync uncertainty; referenced data не удаляется без подтверждённого reference accounting. - `crank-import` pure относительно PostgreSQL, artifacts и Operations. Parser получает только verified snapshot; разрешённые external snapshots immutable и входят в plan digest, поэтому изменение remote content требует нового preview и устраняет TOCTOU. - Применяются hexagonal modular-monolith boundaries и единая migration authority. Apply повторно проверяет source/external digests, importer/support-matrix version, catalog revision, dependencies, auth refs и conflicts перед одной PostgreSQL transaction с conditional predicates/locks. - Общий `OutboundPolicy` применяется к external references: deny-before-allow после DNS resolution, system proxy и implicit redirects выключены, network/input/output limits bounded. Boundary errors typed/localized и содержат безопасные Request ID/Trace ID. - Matrix, corpus, preview/plan и apply reports — immutable evidence; release evidence индексируется signed JSON-Schema Evidence Manifest. Документация не обещает больше, чем доказано executable matrix/corpus. ## UX & Interaction Patterns - Upload flow на RU/EN имеет idle, validating, uploading, parsing/loading, success, cancelled, empty/no-methods, error и recovery states; показывает только bounded metadata, findings, actionable recovery и Request ID/Trace ID. - Preview показывает methods, paths, names, mappings, schemas, security, conflicts и source locations; для больших результатов использует search/filter/grouping и bounded pagination/virtualized rendering (до 2 000 candidates). Blockers видимы, partial/conflict consequences требуют явного подтверждения. - Replacement, refresh, navigation, workspace/language change и concurrent requests защищены AbortController и monotonic identity/revision guards. Duplicate Apply click и stale response не создают повторную мутацию и не меняют authoritative selection. - UI соблюдает keyboard navigation, visible focus, semantic labels, screen-reader status, contrast, non-color meaning и reduced-motion. Guided onboarding переиспользует canonical upload/preview flow, позволяет выбрать Draft для test/publish и не публикует автоматически. ## Cross-Story Dependencies - Epic 2 начинается после Epic 1 foundation: typed configuration, migration authority, correlation/metrics contracts, Admin authorization/Auth Profiles, Operation lifecycle и shared runtime/outbound policy должны быть доступны. - Artifact/upload цепочка упорядочена как `2.1 → 2.2 → 2.3 → 2.4 → 2.5 → 2.6`. Normalization и semantic branches питают preview/apply: `2.7 → 2.8 → 2.9 → 2.10 → 2.11 → 2.12 → 2.13`; Story 2.14 квалифицирует весь workflow и фиксирует evidence. 2.10 владеет security semantics/revalidation API, 2.11 использует этот API для mapping UI; обе сохраняют исходный immutable contract. - Story 2.15 зависит от guided onboarding Epic 1 и готового bounded import workflow, не создаёт отдельный parser и не обходит Auth Profile/ImportPlan. Созданные Drafts используют обычные publication и Agent-binding flows последующих эпиков.