설계: 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>
92 lines
6.0 KiB
Markdown
92 lines
6.0 KiB
Markdown
# 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](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](../adr/ADR-MONGO-ADV-001-capability-promotion.md). |
|
|
|
|
Search, vector search, time series and GridFS compatibility were interfaces with no implementation
|
|
and were removed on 2026-09-25 (`docs/capability-status.md`).
|