설계: 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>
138 lines
10 KiB
Markdown
138 lines
10 KiB
Markdown
# MongoDB Document Persistence Platform — Repository Adaptation Contract
|
|
|
|
**Design source:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md`
|
|
**Stable plan:** `docs/superpowers/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md`
|
|
**Advanced plan:** `docs/superpowers/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md`
|
|
|
|
The design package declares its own module root (`modules/mongodb`) and root package
|
|
(`io.backend.skeleton.mongodb`) as *implementation assumptions*, not as contract. This file is the
|
|
single record of how that assumed layout was mapped onto this repository. Only paths, build DSL,
|
|
and composition-root ownership changed. Public contracts, policy order, and error semantics are
|
|
implemented exactly as specified.
|
|
|
|
## 1. Why the module layout differs
|
|
|
|
The design assumes 19 Stable Gradle projects under `modules/mongodb/` and 12 Advanced projects
|
|
under `modules/mongodb-advanced/`. This repository is a Clean Architecture template whose
|
|
**fail-closed registry** (`src/config/architecture/modules.json`, enforced by `src/settings.gradle`
|
|
and `verifyCleanArchitectureDependencies`) declares **exactly 19 leaf identities**. Creating 31 more
|
|
Gradle projects would violate HARD-STOP #5 in `AGENTS.md`.
|
|
|
|
Therefore the design's 31 modules become **package boundaries inside the registered leaf**
|
|
`:adapter:outbound:persistence-mongo`, following the precedent already set by
|
|
[docs/httpclient/repository-adaptation.md](../httpclient/repository-adaptation.md). The design's
|
|
module dependency table (§6.3) is enforced by `MongoModuleBoundaryTest` as a **closed edge matrix**:
|
|
every top-level package is declared with the packages it may import, the matrix is compared against
|
|
the tree for exact equality, and every observed edge must appear in it. A forbidden edge fails the
|
|
build the same way a missing Gradle dependency would, and so does a new package nobody registered.
|
|
|
|
This used to be a stronger claim than the test. The rules forbade a handful of reverse dependencies
|
|
and said nothing about the rest, so edges outside the design's DAG existed and passed, among them
|
|
`geo → imperative`. They are declared in the matrix now rather than removed — each is a real coupling the code relies on, and
|
|
the point of recording them is that the next one is a decision instead of an accident.
|
|
|
|
## 2. Package mapping
|
|
|
|
Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound.mongo`.
|
|
|
|
### 2.1 Stable modules
|
|
|
|
| Design module | Repository package |
|
|
|---|---|
|
|
| `mongodb-core-api` | `…outbound.mongo.api` (+ `.capability`, `.consistency`, `.error`, `.mapping`, `.observation`, `.profile`, `.schema`) |
|
|
| `mongodb-spring-data` | `…outbound.mongo.mapping` (+ `.type`), `…outbound.mongo.failure` |
|
|
| `mongodb-imperative` | `…outbound.mongo.imperative` (+ `.atomic`, `.bulk`, `.revision`) |
|
|
| `mongodb-query` | `…outbound.mongo.query` (+ `.budget`, `.pagination`) |
|
|
| `mongodb-aggregation` | `…outbound.mongo.aggregation` |
|
|
| `mongodb-transaction` | `…outbound.mongo.transaction` (+ `.retry`, `.session`) |
|
|
| `mongodb-index-schema` | `…outbound.mongo.schema` (+ `.index`, `.manifest`, `.model`, `.ttl`, `.validation`) |
|
|
| `mongodb-geospatial` | `…outbound.mongo.geo` |
|
|
| `mongodb-migration-core` | `…outbound.mongo.migration` |
|
|
| `mongodb-migration-flamingock` | `…outbound.mongo.migration.flamingock` |
|
|
| `mongodb-observability` | `…outbound.mongo.observation` |
|
|
| `mongodb-security` | `…outbound.mongo.security` (+ `.admin`), `…outbound.mongo.nativecap` |
|
|
| `mongodb-spring-boot-starter` | `…outbound.mongo.autoconfigure` |
|
|
| `mongodb-testkit-core` | `…outbound.mongo.testkit.mapping`, `.compat`, `.performance` (`testkit` source set) |
|
|
| `mongodb-testkit-replicaset` | `…outbound.mongo.testkit.rs` (`testkit` source set) |
|
|
| `mongodb-testkit-failover` | `…outbound.mongo.testkit.failover` (`testkit` source set) |
|
|
| `mongodb-testkit-migration` | `…outbound.mongo.testkit.migration` (`testkit` source set) |
|
|
|
|
`…outbound.mongo.architecture` has no design counterpart: it holds the `@MongoOperation` marker and
|
|
the reusable ArchUnit rule set a fork applies to its own document/repository code.
|
|
|
|
### 2.2 Advanced modules
|
|
|
|
| Design module | Repository package |
|
|
|---|---|
|
|
| `mongodb-sharding` | `…outbound.mongo.advanced.sharding` (+ `.admin` for the D4 shard plane) |
|
|
| `mongodb-csfle` | `…outbound.mongo.advanced.encryption.csfle` |
|
|
| `mongodb-queryable-encryption` | `…outbound.mongo.advanced.encryption.qe` |
|
|
| `mongodb-tenancy-shared` | `…outbound.mongo.advanced.tenancy.shared` |
|
|
| `mongodb-tenancy-database` | `…outbound.mongo.advanced.tenancy.database` |
|
|
| `mongodb-testkit-sharded` | `…outbound.mongo.testkit.sharded` (`testkit` source set) |
|
|
|
|
`mongodb-timeseries`, `mongodb-search`, `mongodb-vector-search`, `mongodb-gridfs-compat` and
|
|
`mongodb-testkit-atlas` have no package any more: each was an operations interface with no
|
|
implementation plus the descriptors that parametrised it, and was removed on 2026-09-25
|
|
(`docs/capability-status.md`).
|
|
|
|
The design's rule that a Stable module never depends on an Advanced one survives as an ArchUnit rule
|
|
(`stableNeverDependsOnAdvanced`). Every Advanced entry point takes a `MongoAdvancedCapabilityGuard`
|
|
and refuses construction unless its `MongoAdvancedCapabilityFlags` enable the matching capability.
|
|
There is no configuration property behind the flags: the Advanced types are library API, and the
|
|
adopter's adapter that constructs them builds the guard.
|
|
|
|
## 3. Other deliberate substitutions
|
|
|
|
| Design assumption | Repository reality | Adaptation |
|
|
|---|---|---|
|
|
| Gradle Kotlin DSL under `modules/mongodb*` | Groovy DSL, root `build.gradle` conventions, `LockMode.STRICT` locking | Dependencies declared in `src/adapter/outbound/persistence-mongo/build.gradle`; `gradle.lockfile` regenerated. |
|
|
| `mongodb-spring-boot-starter` is a separate module the app depends on | `modules.json` gives `adapter-outbound-persistence-mongo` an explicit project boundary; runtime membership is derived from resolved runtime classpaths rather than a per-leaf registry field | The `autoconfigure` package stays inside the leaf and registers through the leaf's own `META-INF/spring/…AutoConfiguration.imports`. This differs from the httpclient precedent; dependency and runtime-membership gates decide whether the leaf is actually composed. |
|
|
| Spring Boot 4.1 / Spring Data MongoDB 5.1 baseline | Repository baseline is Spring Boot 4.0.8 / Spring Data MongoDB 5.0.x | The platform targets the Spring Data MongoDB **API surface** common to both; no 5.1-only type is referenced. The support matrix records the actual pinned versions. |
|
|
| `MongoRetryScope` lives in `mongodb-transaction` | The `mongodb-spring-data` failure translator must classify retry scope, and it cannot depend on `mongodb-transaction` | `MongoRetryScope` lives in `…api.error` (core-api), which both packages already depend on. Same values, same meaning, one legal position in the DAG. |
|
|
| `mongodb-migration-flamingock` depends on Flamingock | Adding an unvetted external dependency is out of scope for this task, and the design itself requires the public contract not to depend on Flamingock types | The adapter is provider-neutral: it consumes a platform-owned `FlamingockChangeUnitView`. Wiring an actual Flamingock distribution is a one-file change behind that view. |
|
|
| Testkit as its own Gradle module | The design forbids production modules depending on the testkit | A dedicated `testkit` source set whose output is on the test compile/runtime classpaths only. ArchUnit rule `productionNeverDependsOnTestkit` enforces the direction. |
|
|
| Per-task `git commit` | `AGENTS.md`: commit policy is `human-only` | Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here. |
|
|
| `docs/mongodb/**`, `scripts/verify-mongodb-*.sh` | Repository already owns `docs/` and `scripts/` | Created at the same repository-relative paths. The two gate scripts were later removed (2026-08-15); see §5. |
|
|
|
|
## 4. What is unchanged from the design
|
|
|
|
- D1 / D2 / D3 / D4 exposure planes and the ordered D3 admission sequence (§5).
|
|
- Stable API V1 with `apiStrict=true` on the D1/D2 client generation; D3/D4 on separate generations.
|
|
- `MongoExecutionOutcome`, including both ambiguous outcomes (`WRITE_RESULT_UNKNOWN`,
|
|
`TRANSACTION_COMMIT_UNKNOWN`), and `MongoFailureContext`'s permitted-field list.
|
|
- The complete stable exception hierarchy and the label-before-code classification order.
|
|
- The BSON representation manifest (UUID `STANDARD`, `Decimal128`, UTC instants, alias type metadata)
|
|
and the document-size budget.
|
|
- Update-operator-first writes, and optimistic revision as the precondition for whole-document
|
|
replacement.
|
|
- Transaction body retry and commit retry as separate loops: a new session per body attempt, and
|
|
commit-only retry on unknown commit. The body is never replayed after a commit ambiguity.
|
|
- Registered operation names and manifests for query, aggregation and index; no free-form JSON query
|
|
and no unbounded pipeline.
|
|
- Keyset pagination with an authenticated cursor and a unique tie-breaker requirement.
|
|
- TTL as physical cleanup only, never the sole basis for access denial or business scheduling.
|
|
- Manifest-owned index/validator state with an apply policy that never drops what it does not own.
|
|
- Low-cardinality observation tags, command redaction, and the credential reference indirection.
|
|
- The Stable release gate's evidence categories. The Advanced promotion requirements
|
|
(actual-topology evidence) are a review obligation in ADR-MONGO-ADV-001; no class checks them.
|
|
|
|
## 5. Verification
|
|
|
|
The release-gate scripts `scripts/verify-mongodb-platform.sh` and
|
|
`scripts/verify-mongodb-advanced.sh` are present and wrap the named Gradle lanes with no-skip evidence
|
|
and promotion metadata. Use them when producing release/promotion evidence; the focused commands
|
|
below remain useful for local diagnosis.
|
|
|
|
From `src/`:
|
|
|
|
```bash
|
|
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
|
|
./gradlew verifyCleanArchitectureDependencies --console=plain
|
|
./gradlew :app-bootstrap:architectureTest --console=plain
|
|
```
|
|
|
|
The container-backed lanes the gate ran behind `MONGODB_DOCKER=1` — `mongoCompatibilityTest`,
|
|
`mongoMigrationTest`, `mongoSecurityIntegrationTest`, `mongoReplicaSetTest`, `mongoFailoverTest`,
|
|
`mongoPerformanceTest` — are now invoked by name or not at all.
|