> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택(보완) - 작성일: 2026-08-13 - 요약: MongoDB 고급 기능의 승격 기준을 정한 결정이다. 2026-09-25 보완이 있다. - 현재 정본: `docs/mongodb/support-matrix.md` # ADR-MONGO-ADV-001 — Advanced capability 승격 - **상태:** 채택 - **날짜:** 2026-08-13 - **설계 출처:** 설계 §2 (D-15), §3.2–§3.3. Advanced 확장 계획 Task 15 - **2026-09-25 보완:** `ca-skeleton.persistence-mongo.advanced.*.enabled` 바인딩(`MongoAdvancedConfiguration`/ `MongoAdvancedSettings`)은 아무것도 import하지 않아서 어떤 배포 속성도 flag에 닿지 않았다. `propertyFor`와 함께 지웠다. flag는 이제 entry point를 만드는 어댑터가 코드로 만든다. `MongoAdvancedPromotionGate`, `MongoAdvancedPromotionEvidence`, `MongoVectorSearchBenchmarkGate`, 그리고 search, vector, time series, GridFS 패키지(구현 없는 인터페이스)를 지웠다. 아래 증거 category는 리뷰 의무로 남는다. 그것을 검사하는 클래스는 없다. ## 배경 sharding, time series, CSFLE, Queryable Encryption, search, vector search, multi-tenancy는 하나같이 오후 한나절이면 demo에서 동작한다. 하지 않는 것은 운영에서 같은 방식으로 동작하는 것이고, 그 차이는 기능 시험으로 찾지 못한다: - sharding은 어떤 query가 효율적인지 바꾼다. shard key를 놓친 query는 scatter-gather가 되는데, shard 하나짜리 cluster에서는 모든 시험을 통과한다. - 암호화의 실패 방식은 KMS의 실패 방식이다 — 틀린 키, 거둬들인 권한, 교체 중 — 로컬 키 provider에 대고는 하나도 일어나지 않는다. - search와 vector search는 기능상 맞으면서 쓸모없을 수 있다: index는 결과를 돌려주는데 결과가 관련이 없다. recall은 통과·실패 단언에 보이지 않는다. - 테넌트마다 데이터베이스는 테넌트 수가 연결·파일 handle 예산이 받쳐 주는 수를 넘을 때까지 동작한다. 그것은 코드가 아니라 운영의 성질이다. 이 ADR이 막는 실패 방식은 그것이 돌 환경을 한 번도 건드리지 않은 초록 시험을 근거로 capability를 「끝남」으로 표시하는 것이다. ## 결정 모든 Advanced·Experimental capability는 **자기 flag 뒤의 골라 쓰는 모듈**이고, 승격에는 자신감이 아니라 증거가 필요하다. ### 켜기 `MongoAdvancedCapabilityFlags`가 모든 Advanced entry point의 생성을 막는다. 꺼진 capability는 런타임 경고를 내지 않는다 — 타입이 그것을 켜는 속성 이름을 대며 만들어지기를 거절한다(`MongoAdvancedCapabilityFlags.propertyFor(capability)`). classpath에 있다고 켜진 것이 아니고, `stableNeverDependsOnAdvanced`(ArchUnit)가 Stable surface에서 그것을 떼어 둔다. ### 승격 증거 `MongoAdvancedPromotionGate.verify(evidence)`는 모든 category를 요구한다: | category | 뜻 | |---|---| | `stable-platform` | 같은 revision에서 Stable 릴리스 gate가 통과했다. | | `actual-topology` | capability가 실제 topology에서 돌았다 — 실제 sharded cluster, 실제 KMS, 실제 대상 배포. Atlas Local은 pull request용 편의이고 릴리스 증거가 아님을 명시한다(`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). | | `security` | 권한을 리뷰했다. capability의 admin role은 애플리케이션 role과 따로다. | | `migration` | 들어가는 길을 적었고, capability가 되돌릴 수 없으면 돌아오는 길이 없다고 명시했다. | | `failure` | 부정 경우가 실패하면 닫힌다: 틀린 키, 빠진 권한, 교체, 준비되지 않은 index, 라우팅되지 않은 query. | | `runbook` | capability의 대표 사고를 위한 runbook이 있다. | ### capability별 추가 요구 - **search / vector search:** 기능 성공만이 아니라 관련성과 성능 증거. `MongoVectorSearchBenchmarkGate`는 지연 시간·index 크기와 함께 recall을 요구한다. 지연 시간만 재는 gate는 빠른 틀린 답을 인증한다. - **테넌트마다 데이터베이스와 reshard 조율은 운영 규모 증거가 생길 때까지 Experimental로 남는다.** 둘 다 작게는 맞고 크게는 한계가 없다. - **reshard에는 명시한 `ReshardApproval`이 필요하다** — 이름 있는 승인자와 밝힌 시간 창. reshard는 collection을 다시 쓴다. ### 승격은 의존 경계를 바꾸지 않는다 Stable로 승격한 capability도 나중의 starter ADR이 의존 경계를 바꾸지 않는 한 **골라 쓰는 모듈로 남는다**. 승격은 증거에 대한 진술이지, 모든 서비스에 전이 의존을 더하라는 초대가 아니다. ## 결과 **좋은 점.** container 전용 시험을 근거로 운영에 닿는 capability는 없다. 증거 목록이 모든 capability에 같으므로, 승격은 흥정이 아니라 리뷰할 수 있는 것이 된다. **나쁜 점.** 승격에는 실제 기반 시설 — sharded cluster, 실제 KMS, 대상 배포 — 에 대한 접근이 필요하다. 그것이 보장의 비용이다: 대안은 운영에서 알게 되는 것이고, 거기서는 암호화와 sharding 둘 다 되돌리기 비싸다. ## 검증 `scripts/verify-mongodb-advanced.sh`가 2026-08-15에 지워질 때까지 이 ADR을 강제했다. 그래서 이 ADR이 요구하는 승격 증거 category는 이제 어떤 자동 gate도 검사하지 않는다. 다시 만들 때까지 리뷰 의무다. 그 script가 감싸던 Gradle lane은 `docs/mongodb/repository-adaptation.md` §5를 본다.