Files
crank/_bmad-output/implementation-artifacts/epic-2-context.md
T

11 KiB
Raw Blame History

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 последующих эпиков.