Files
clean-architecture-backend-…/docs/mongodb/support-matrix.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

6.0 KiB

MongoDB Platform — Support Matrix

Design §4. This file records what the platform is certified on, not what it happens to run on. A configuration absent from this table is unsupported until someone runs the gate against it and adds a row.

1. Runtime baseline

Component Version Policy
Java 21 Repository runtime baseline.
Spring Boot 4.0.0 BOM-managed. Individual driver overrides are forbidden.
Spring Data MongoDB 5.0.0 Repository and MongoTemplate integration. Version comes from the Boot BOM.
MongoDB Java Driver 5.6.1 BOM-managed. Never pinned directly in the module.
Micrometer 1.16.0 Driver-native observability.
Testcontainers 2.0.2 Replica-set, failover, migration and compatibility lanes.

The design's baseline is Spring Boot 4.1.x / Spring Data MongoDB 5.1.x. This repository is on 4.0.0 / 5.0.0, so the platform targets only the API surface common to both. See repository-adaptation.md §3.

2. Server versions

Lane Version Pinned image Gradle task
Primary certification MongoDB 8.0 mongo:8.0.16 mongoReplicaSetTest, mongoFailoverTest
Compatibility MongoDB 7.0 mongo:7.0.28 mongoCompatibilityTest
Network fault injection — ghcr.io/shopify/toxiproxy:2.12.0 mongoFailoverTest

Images are pinned, never latest: a mutable tag means the certification result describes whatever was pulled that morning, not the version in the row. Override with -PmongoPrimaryImage=… / -PmongoCompatibilityImage=… when testing a new patch level, and update the row once the gate passes.

MongoVersionMatrix.standard() is the machine-readable form of this table; a version outside it fails certifies().

3. Topologies

Topology Status What is certified What is not
Standalone Smoke only Basic CRUD and mapping. Not a production profile and never counts as Stable release evidence (D-03). A production profile, or platform.transactions=true, on a Standalone server is refused at startup by MongoStartupValidator.
Single-node replica set Local default (D-02) Transactions, retryable writes, change streams — the same semantics as production. Elections. A single-node set never holds one, so failover behaviour is untested here.
3-node replica set Stable production gate Everything above plus primary failover and unknown-commit handling. Shard routing.
Sharded cluster Advanced gate Shard-key routing classification, scatter-gather refusal, admin plane operations. Not included in the Stable gate.
Atlas / provider-managed Not certified Encryption against the actual target deployment is the adopter's evidence to produce. Search and vector search have no implementation in this leaf; a native $search command can only go through PolicyAwareMongoNativeGateway as a registered D3 operation.

4. Stable API and client generations

Plane Stable API Purpose
D1 Standard document persistence V1, apiStrict=true Repositories, typed queries, atomic updates, optimistic revision.
D2 Advanced document operations V1, apiStrict=true MongoTemplate, transactions, bulk, aggregation, keyset cursors.
D3 Explicit Mongo capability Not strict Native BSON, CSFLE/QE, shard-aware operations — each behind a registered capability.
D4 Admin plane Not strict Collection, validator, index, migration, shard and repair commands. Separate credential, separate client.

D3 is not a raw-client escape. Every call passes capability registration → database profile → collection allowlist → operation name → timeout → consistency profile → result limit → trace → redaction → command category → D4 refusal, in that order.

5. Validation actions

Stable validation actions are error and warn. errorAndLog is not part of the Stable contract on 7.0 or 8.0 and MongoValidatorDescriptor refuses it.

6. Explicitly unsupported

Per design §3.4, none of the following is provided, and adding one is a design change rather than a feature request:

  • A generic CommonMongoRepository<T, ID>.
  • Arbitrary runtime runCommand.
  • Automatic index creation in production.
  • A Standalone production contract.
  • TTL as an exact business scheduler or as the only access control.
  • Publishing raw change events as external business integration events.
  • GridFS as the source of truth for new files.
  • Java fully-qualified class names as a long-lived BSON schema.
  • Unbounded skip pagination, unbounded aggregation pipelines, unbounded regex, unbounded results.

7. Capability tiers

Tier Capabilities Enablement
Stable, auto-configured Mapping and BSON converters, imperative execution, atomic update, bulk partial results, consistency profiles, retry/translation, operation budgets, observability, typed client profiles, startup validation, health Beans registered when ca-skeleton.persistence-mongo.enabled=true.
Stable, library API Transactions, causal sessions, optimistic revision, query builder and keyset pagination, aggregation executor, schema/index/validator manifests and diffs, TTL contract, GeoJSON, migration runner, admin plane, native capability gateway The adopter's adapter leaf takes this leaf as implementation and constructs the type.
Advanced, library API Sharding-aware query and shard admin, CSFLE, Queryable Encryption (equality/range), shared-collection tenancy policies Same, plus a MongoAdvancedCapabilityGuard whose flags enable the capability. No configuration property.
Experimental, library API Database-per-tenant client registry and migration coordinator, reshard approval Same as Advanced; promotion additionally requires the evidence in ADR-MONGO-ADV-001.

Search, vector search, time series and GridFS compatibility were interfaces with no implementation and were removed on 2026-09-25 (docs/capability-status.md).