설계: 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>
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).