Files
clean-architecture-backend-…/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

5.0 KiB

ADR-MONGO-ADV-001 — Advanced capability promotion

  • Status: Accepted
  • Date: 2026-08-13
  • Design source: design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15
  • Amended 2026-09-25: the ca-skeleton.persistence-mongo.advanced.*.enabled binding (MongoAdvancedConfiguration/MongoAdvancedSettings) was imported by nothing, so no deployment property ever reached the flags; it was removed together with propertyFor. The flags are now built in code by the adapter that constructs an entry point. MongoAdvancedPromotionGate, MongoAdvancedPromotionEvidence, MongoVectorSearchBenchmarkGate and the search, vector, time series and GridFS packages (interfaces with no implementation) were removed. The evidence categories below remain a review obligation; no class checks them.

Context

Sharding, time series, CSFLE, Queryable Encryption, search, vector search and multi-tenancy each work in a demo within an afternoon. What they do not do is behave the same way in production, and the differences are not discovered by functional tests:

  • Sharding changes which queries are efficient. A query that misses the shard key becomes scatter-gather, which passes every test on a one-shard cluster.
  • Encryption's failure modes are KMS failure modes — wrong key, revoked permission, mid-rotation — none of which occur against a local key provider.
  • Search and vector search can be functionally correct and useless: the index returns results, and the results are not relevant. Recall is not visible in a pass/fail assertion.
  • Database-per-tenant works until the tenant count crosses what the connection and file-handle budget supports, which is an operational property, not a code property.

The failure mode this ADR prevents is a capability marked "done" on the strength of a green test that never touched the environment where it will run.

Decision

Every Advanced and Experimental capability is an opt-in module behind its own flag, and promotion requires evidence, not confidence.

Enablement

MongoAdvancedCapabilityFlags gates construction of every Advanced entry point. A disabled capability does not produce a runtime warning — the type refuses to be constructed, naming the property that enables it (MongoAdvancedCapabilityFlags.propertyFor(capability)). Being on the classpath is not being enabled, and stableNeverDependsOnAdvanced (ArchUnit) keeps the Stable surface free of them.

Promotion evidence

MongoAdvancedPromotionGate.verify(evidence) requires every category:

Category Means
stable-platform The Stable release gate passed on the same revision.
actual-topology The capability ran on the real topology — a real sharded cluster, the real KMS, the actual target deployment. Atlas Local is a pull-request convenience and explicitly not release evidence (MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL).
security Privileges reviewed; the capability's admin role is separate from the application role.
migration A documented path in and, where the capability is irreversible, an explicit statement that there is no path back.
failure Negative cases fail closed: wrong key, missing permission, rotation, non-ready index, unrouted query.
runbook A runbook exists for the capability's characteristic incident.

Additional per-capability requirements

  • Search / vector search: relevance and performance evidence, not functional success alone. MongoVectorSearchBenchmarkGate requires recall alongside latency and index size; a gate that measures only latency certifies a fast wrong answer.
  • Database-per-tenant and reshard orchestration remain Experimental until operational scale evidence exists. Both are correct in the small and unbounded in the large.
  • Reshard requires an explicit ReshardApproval — a named approver and a stated window. It rewrites the collection.

Promotion does not change the dependency boundary

A capability promoted to Stable remains an opt-in module unless a later starter ADR changes the dependency boundary. Promotion is a statement about evidence, not an invitation to add a transitive dependency to every service.

Consequences

Positive. No capability reaches production on the strength of a container-only test. The evidence list is the same for every capability, so promotion is reviewable rather than negotiated.

Negative. Promotion requires access to real infrastructure — a sharded cluster, a real KMS, the target deployment. That is the cost of the guarantee: the alternative is finding out in production, where encryption and sharding are both expensive to reverse.

Verification

scripts/verify-mongodb-advanced.sh enforced this ADR until it was removed on 2026-08-15. The promotion evidence categories this ADR requires are therefore no longer checked by any automated gate; they are a review obligation until one is rebuilt. See docs/mongodb/repository-adaptation.md §5 for the Gradle lanes the script wrapped.