# ADR-MONGO-ADV-001 — Advanced capability promotion

- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15

## Context

Sharding, time series, CSFLE, Queryable Encryption, search, vector search and multi-tenancy each work
in a demo within an afternoon. What they do not do is behave the same way in production, and the
differences are not discovered by functional tests:

- Sharding changes which queries are efficient. A query that misses the shard key becomes
  scatter-gather, which passes every test on a one-shard cluster.
- Encryption's failure modes are KMS failure modes — wrong key, revoked permission, mid-rotation —
  none of which occur against a local key provider.
- Search and vector search can be functionally correct and useless: the index returns results, and
  the results are not relevant. Recall is not visible in a pass/fail assertion.
- Database-per-tenant works until the tenant count crosses what the connection and file-handle
  budget supports, which is an operational property, not a code property.

The failure mode this ADR prevents is a capability marked "done" on the strength of a green test that
never touched the environment where it will run.

## Decision

Every Advanced and Experimental capability is an **opt-in module behind its own flag**, and promotion
requires evidence, not confidence.

### Enablement

`MongoAdvancedCapabilityFlags` gates construction of every Advanced entry point. A disabled capability
does not produce a runtime warning — the type refuses to be constructed, naming the property that
enables it (`MongoAdvancedCapabilityFlags.propertyFor(capability)`). Being on the classpath is not
being enabled, and `stableNeverDependsOnAdvanced` (ArchUnit) keeps the Stable surface free of them.

### Promotion evidence

`MongoAdvancedPromotionGate.verify(evidence)` requires every category:

| Category | Means |
|---|---|
| `stable-platform` | The Stable release gate passed on the same revision. |
| `actual-topology` | The capability ran on the real topology — a real sharded cluster, the real KMS, the actual target deployment. Atlas Local is a pull-request convenience and explicitly not release evidence (`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). |
| `security` | Privileges reviewed; the capability's admin role is separate from the application role. |
| `migration` | A documented path in and, where the capability is irreversible, an explicit statement that there is no path back. |
| `failure` | Negative cases fail closed: wrong key, missing permission, rotation, non-ready index, unrouted query. |
| `runbook` | A runbook exists for the capability's characteristic incident. |

### Additional per-capability requirements

- **Search / vector search:** relevance and performance evidence, not functional success alone.
  `MongoVectorSearchBenchmarkGate` requires recall alongside latency and index size; a gate that
  measures only latency certifies a fast wrong answer.
- **Database-per-tenant and reshard orchestration remain Experimental** until operational scale
  evidence exists. Both are correct in the small and unbounded in the large.
- **Reshard requires an explicit `ReshardApproval`** — a named approver and a stated window. It
  rewrites the collection.

### Promotion does not change the dependency boundary

A capability promoted to Stable **remains an opt-in module** unless a later starter ADR changes the
dependency boundary. Promotion is a statement about evidence, not an invitation to add a transitive
dependency to every service.

## Consequences

**Positive.** No capability reaches production on the strength of a container-only test. The evidence
list is the same for every capability, so promotion is reviewable rather than negotiated.

**Negative.** Promotion requires access to real infrastructure — a sharded cluster, a real KMS, the
target deployment. That is the cost of the guarantee: the alternative is finding out in production,
where encryption and sharding are both expensive to reverse.

## Verification

`scripts/verify-mongodb-advanced.sh` enforced this ADR until it was removed on 2026-08-15. The
promotion evidence categories this ADR requires are therefore no longer checked by any automated
gate; they are a review obligation until one is rebuilt. See `docs/mongodb/repository-adaptation.md`
§5 for the Gradle lanes the script wrapped.