DongHyeonkaandClaude Opus 5
d57d2f62a0
Implements the mongodb-superpowers-package design: Stable Tasks 1-50 and Advanced Tasks 1-15. The design assumes 19 Stable + 12 Advanced Gradle projects under modules/mongodb*. This repository's fail-closed registry declares exactly 19 leaf identities, so those modules become package boundaries inside the registered leaf :adapter:outbound:persistence-mongo, with the design's module dependency table enforced by ten ArchUnit rules. The mapping and every deviation are recorded in docs/mongodb/repository-adaptation.md. Contract highlights, all enforced by tests rather than convention: - Transaction body retry and commit retry are separate loops. A new session per body attempt; commit-only retry on an unknown commit. The body is never replayed after a commit ambiguity, so a failover cannot become a duplicate. - MongoExecutionOutcome keeps both ambiguous outcomes distinct from success and failure, and MongoFailureContext records only the design-permitted fields. - Failure classification reads server error labels before numeric codes. - BSON representations come from a pinned manifest, never a library default, and a golden type-signature gate fails on any drift. - Index and validator changes go through the manifest and the admin plane; metadata ownership gates every drop. - Every Advanced capability refuses construction unless its flag is enabled. Verified against real servers, not only unit tests. Running the lanes for the first time exposed four defects that a green `check` had hidden: - Four release lanes passed while executing zero tests; the gate now counts executed tests per lane and fails on zero. - The "single replica set" fixture was a standalone, because Testcontainers 2.x needs withReplicaSet(); its test only asserted a connection string. - The three-node fixture was three independent clusters, so no election could occur, and awaitNewPrimary() compared against the post-stop primary. - The migration lease checked modifiedCount, so a same-millisecond refresh read as a lost lease. scripts/verify-mongodb-platform.sh now reports: 9 lanes, 0 skipped, 0 failed, every evidence category produced. scripts/verify-mongodb-advanced.sh reports NOT PROMOTABLE: actual-topology evidence (real sharded cluster, real KMS, real target deployment) is unobtainable here, so it is named rather than assumed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.7 KiB
ADR-MONGO-004 — Index and schema changes belong to the admin plane
- Status: Accepted
- Date: 2026-08-13
- Design source: design §21–§25, decisions D-11, D-13
Context
Spring Data can create indexes automatically from annotations. On a laptop this is convenient. On a collection with a hundred million documents, an index build is a capacity event: it consumes CPU, IO and memory on the primary for minutes to hours, and it starts because a pod restarted.
Worse, it starts N times when N pods restart, and there is no approval step, no ordering relative to the code that needs the index, and no record afterwards of what was created.
Schema validators have the same shape with a sharper edge: tightening a validator on a collection with existing data rejects writes to documents that were legal when they were written.
TTL has a third shape. It looks like a scheduler and is not one: the TTL monitor runs about once a minute and deletes in batches, so an expired document routinely remains readable for minutes or hours.
Decision
Indexes and validators are declared in a manifest and applied by the admin plane (D4). Automatic index creation in production is disabled.
MongoManifestRegistryholds the declared indexes (MongoIndexManifest) and validator (MongoSchemaManifest) per collection. The manifest is the source of truth, reviewed in a pull request.MongoIndexDiffEnginecompares manifest against observed state and reports missing, extra and changed indexes. Changed ones are reported rather than re-issued: MongoDB will not silently rebuild an index whose definition moved.MongoIndexApplyPolicysets what an environment may do —APPLY(local),APPLY_WITH_DIFF(staging),DIFF_WITH_APPROVED_APPLY(production),REPORT_ONLY(audit).- Ownership gates every drop.
MongoMetadataOwnershipdistinguishesAPPLICATION_MANAGEDfromSEARCH_MANAGED,ENCRYPTION_MANAGEDandEXTERNAL. Only application-managed objects are droppable on drift. A diff engine without ownership eventually proposes droppingenxcol_.customers.esc, and "the drift tool cleaned it up" is a very bad incident summary. - Retirement is staged.
MongoIndexRetirementStatemoves an index declared → hidden → observed-unused → droppable, one deployment per transition. Hiding is instantly reversible; dropping is a rebuild. - Stable validation actions are
errorandwarnonly.errorAndLogis not part of the Stable contract on 7.0 or 8.0 and is refused. Tightening goeswarn+MODERATE→ confirm zero warnings →error+STRICT, in two deployments. - TTL is physical cleanup only (D-13).
MongoExpirationAccessPolicystates the rule: a document's presence is not authorization and its absence is not a deadline. Access control checks the expiry field; scheduling uses a scheduler. - Migrations are checksummed, locked, precondition-checked and resumable.
MongoMigrationRunnerfails hard when an applied id's checksum changed — two environments running different code under one id is worse than a failed deploy.
Consequences
Positive. Index builds are scheduled by people who know the capacity. Rollback is possible at every step. Drift is visible without being dangerous. Nothing drops what it does not own.
Negative. Adding an index is a manifest change plus an apply, not an annotation. Local development
uses APPLY so the friction is confined to environments where it is warranted.
Rejected alternative — "auto-create with a feature flag." The flag is either on in production, which is the problem, or off, in which case the manifest is the real mechanism and the annotation is a second, divergent source of truth.