11 KiB
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 и все успешные2xxresponses, включая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-importpure относительно 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 последующих эпиков.