Files
crank/_bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md
T

14 KiB
Raw Blame History

title, type, created, status, baseline_commit, review_loop_iteration, context
title type created status baseline_commit review_loop_iteration context
2.8 — Безопасно разрешать references и schema composition feature 2026-08-29 done 6c2a3712d8 0
_bmad-output/implementation-artifacts/epic-2-context.md

Intent

Problem: NormalizedIR сохраняет $ref и composition как placeholders, поэтому даже локальные ссылки блокируют Apply, а preview упрощает composition до первой ветки и теряет семантику.

Approach: Добавить bounded graph resolver: чистый crank-import разрешает local и переданные immutable external snapshots, а Admin API отдельно и до normalization получает allowlisted snapshots через общий SSRF-safe outbound boundary. Resolved IR сохраняет provenance, recursion, alternatives и точные findings; Apply использует только закреплённые digests без повторного network fetch.

Boundaries & Constraints

Always: RFC 6901 escaping и OAS 3.0/3.1 sibling semantics version-specific; external fetch default-off и разрешён только отдельными operator URL-prefix rules поверх deny-before-allow actual-address policy. HTTP(S) без userinfo, proxy и redirects; hop/depth/count/document/expanded-node limits обязательны. Все external bytes становятся workspace-scoped immutable artifacts до preview; graph и findings canonical, redacted и детерминированы. Compatible allOf объединяется с provenance, recursion остаётся graph edge, oneOf/anyOf/discriminator сохраняются typed либо дают blocker affected candidate.

Ask First: Новая внешняя dependency, изменение публичного import HTTP DTO, ослабление SSRF/default-deny, изменение crank-schema wire contract либо отказ от replay существующих legacy-v1 jobs.

Never: Network I/O из crank-import или во время Apply/registry transaction; повторный fetch при Apply; credential из URL/OpenAPI; unbounded recursive expansion; last-write-wins при allOf; first-branch collapse в v2+; global cross-workspace cache; raw URL/content/digest/parser error в публичных errors, logs, traces или metrics.

I/O & Edge-Case Matrix

Scenario Input / State Expected Output / Behavior Error Handling
Local reference Schema/object ref с escaped pointer Target разрешён относительно primary snapshot; source/target provenance сохранён Missing/invalid/type mismatch — точный blocker без panic
External default HTTP(S) ref без import allowlist Ни DNS, ни request не выполняются external_reference_disabled с безопасной location
External allowed Canonical URL проходит prefix и outbound policy Chain загружена bounded, сохранена как artifacts и входит в dependency digest set Redirect/private IP/forbidden origin/limit — blocker, все созданные snapshots detached
Replay/TOCTOU Remote изменился после preview Apply проверяет и использует прежние snapshot digests Missing/changed snapshot — fail-closed до Draft mutation
Recursion Self/mutual cycle в schema graph Typed edge указывает на stable node, без дублирования Graph limit excess — blocker affected candidates
Composition allOf/oneOf/anyOf/discriminator Compatible merge либо lossless typed alternatives с provenance Conflict/unsupported projection — explicit blocker, siblings остаются

Code Map

  • crates/crank-import/src/rest/{model.rs,normalize.rs,normalize_schema.rs,normalize_coverage.rs} — расширить versioned IR графом, snapshot identity, discriminator/constraints, resolver limits и exact coverage; сохранить crate pure.
  • crates/crank-import/src/rest/{openapi3.rs,swagger2.rs,schema.rs,payload.rs} — разрешить object/schema refs до projection; убрать modern first-branch loss, legacy-v1 оставить изолированным.
  • crates/crank-adapter-rest/src/client.rs — переиспользовать policy DNS resolver/no-proxy/no-redirect в отдельном bounded GET boundary, не меняя REST execution semantics.
  • crates/crank-config/src/{process.rs,schema.rs,validation.rs} — добавить отдельный default-off import external-reference contract: URL prefixes и graph/fetch limits; провести generated config contract.
  • apps/admin-api/src/service/imports.rs — materialize/dedupe dependency snapshots до normalization, одинаково передать verified bundle в preview/apply и redacted cleanup paths.
  • crates/crank-registry/src/{model,postgres}/, crates/crank-registry/src/migrations/ — workspace-scoped import-job dependency set; атомарно verify/detach все digests при Apply/expiry.
  • crates/crank-import/tests/**, crates/crank-adapter-rest/tests/integration/**, apps/admin-api/tests/integration/openapi_{import,source}.rs — reuse determinism/redaction/no-mutation suites; добавить graph, SSRF, TOCTOU и composition fixtures.

Tasks & Acceptance

Execution:

  • crank-import resolver/model/projection — построить canonical bounded resolved graph для local и supplied snapshots, composition/provenance и operation-scoped findings без I/O.
  • crank-adapter-rest, crank-config — реализовать отдельный operator-controlled external-reference fetch contract на существующей actual-address security policy.
  • crank-registry, apps/admin-api — закрепить полный dependency snapshot set за job и reparse/apply только из verified artifacts с корректным lifecycle cleanup.
  • Tests/fixtures — покрыть OAS 3.0/3.1/Swagger2, pointer escaping/type mismatch, default deny, redirects/DNS/private IP/relative chains, TOCTOU, cycles/limits, composition conflicts/discriminators, determinism, redaction и legacy replay.

Acceptance Criteria:

  • Given один повреждённый dependency graph, when preview завершается, then только зависимые candidates получают blocker, независимые остаются видимыми, а полный Apply не создаёт Draft.
  • Given одинаковые primary/external bytes, digests и config, when resolution выполняется повторно или конкурентно, then resolved IR, dependency set, preview и ordered findings совпадают byte-for-byte.
  • Given preview либо любой failure/expiry/apply path, when lifecycle завершается, then все dependency artifacts остаются workspace-isolated и либо атомарно referenced, либо detached без orphan leak.

Spec Change Log

Design Notes

External I/O — orchestration concern Admin API; resolver принимает immutable {canonical_origin, digest, bytes} inputs. URL используется только при сборе цепочки, а resolved graph адресует external nodes snapshot digest + RFC 6901 pointer. Новая parser/projection семантика получает новые version identifiers; существующий legacy-v1 replay не меняется.

Verification

Результат проверки матрицы:

  • Local reference — RFC 6901 escaping, object/schema refs, missing pointer и type mismatch проверены в reference_resolution; создание Draft после успешного local resolution проверено интеграционно в Admin API.
  • External default/allowed — отсутствие request при default-off, URL-prefix boundary, actual-address policy, redirect/userinfo rejection и bounded response проверены в external_reference_fetcher; relative chain и deterministic dependency ordering проверены в reference_resolution.
  • Replay/TOCTOU — Admin API получает snapshot ровно один раз, Apply читает artifact без network fetch; missing/detached dependency завершает Apply до Draft mutation.
  • Recursion — self-cycle остаётся stable recursive edge; depth и expanded-node limits дают blocker без unbounded expansion.
  • Composition — compatible/conflicting allOf, обе ветви oneOf/anyOf, discriminator, OAS 3.0/3.1 sibling semantics и invalid composition покрыты и прошли.

Фактические результаты:

  • crank-import: 64 теста прошли; review-regressions дополнительно покрывают RFC 3986 dot-segments/absolute paths, percent-decoding, literal payload exclusions, OAS 3.1 external siblings, compatible constraint intersections и parameter override semantics.
  • crank-adapter-rest: 23 теста прошли, включая subprocess proxy regression.
  • crank-registry: 82 теста прошли, 1 production-size million-row test штатно ignored.
  • admin-api: 76 интеграционных тестов прошли; среди них selected-only blocker isolation, full-selection atomic failure, relative two-snapshot chain без refetch, total-chain timeout cleanup, failed dependency lifecycle, telemetry redaction и normalized-ir-v2 TTL replay.
  • config-contract-check, cargo fmt --check, workspace clippy -D warnings, rust-boundaries и git diff --check прошли.
  • rust-code-health сообщает только о двух известных baseline-файлах Story 2.1 (crank-artifacts/src/housekeeping.rs, crank-artifacts/tests/artifact_store.rs); все изменённые Story 2.8 Rust-файлы меньше 1000 строк.

Commands:

  • cargo test -p crank-import --all-targets — graph/composition/version matrix зелёная.
  • cargo test -p crank-adapter-rest --all-targets — SSRF, redirect, DNS и bounded-fetch regressions зелёные.
  • cargo test -p crank-registry --test integration -- --test-threads=1 — dependency ownership/lifecycle/transaction guarantees зелёные.
  • cargo test -p admin-api --test integration -- --test-threads=1 — snapshot replay, TOCTOU, redaction и no-Draft guarantees зелёные.
  • just config-contract-check && cargo fmt --all -- --check && cargo clippy --workspace --all-targets --all-features -- -D warnings — contracts и lint чисты.
  • just rust-boundaries && just rust-code-health — dependency direction и module limits сохранены.

Suggested Review Order

Оркестрация preview и Apply

  • Главный поток закрепляет snapshots до preview и проверяет их перед Apply. imports.rs:47

  • Ошибки replay атомарно завершают job и сохраняют completed-race semantics. external_references.rs:76

  • Внешняя цепочка материализуется в общем deadline с cancellation cleanup. external_references.rs:119

Чистый resolver и schema semantics

  • Pure resolver строит deterministic bounded graph только из verified snapshots. reference.rs:100

  • URI resolution объединяет RFC 3986 canonicalization и RFC 6901 fragment lookup. reference.rs:427

  • allOf объединяется пересечением совместимых ограничений без last-write-wins. reference.rs:460

  • Versioned IR contract отделяет modern semantics от legacy replay. model.rs:12

Security и lifecycle boundaries

  • Fetch boundary применяет prefix allowlist поверх actual-address SSRF policy. client.rs:229

  • Failed jobs и dependency sources завершаются под одной database transaction. import_job.rs:82

  • Apply блокирует missing или изменённые artifacts до Draft mutation. import_job.rs:301

Конфигурация и доказательства

  • Builder сохраняет одинаковую policy независимо от порядка настройки. service.rs:285

  • Generated contract фиксирует default-off и единые graph/fetch limits. schema.rs:81

  • End-to-end chain доказывает два fetch, два snapshots и Apply без refetch. external_references.rs:11

  • Resolver regressions покрывают relative paths, fragments и canonical authorities. reference_resolution.rs:522

  • Selection regression доказывает локальные blockers и атомарный full failure. openapi_import.rs:560