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.5 KiB
ADR-MONGO-003 — Transaction body retry and commit retry are separate loops
- Status: Accepted
- Date: 2026-08-13
- Design source: design §14–§16, decisions D-07 through D-10
Context
MongoDB reports two transaction failures that look similar and must be handled in opposite ways.
TransientTransactionError means the transaction definitively did not commit. The correct response is
to run the whole thing again.
UnknownTransactionCommitResult means the commit may already have applied — typically because the
primary changed while the commit was in flight. The correct response is to retry the commit, which
is a no-op if it already succeeded.
The common implementation wraps everything in one retry loop. That loop replays the body after an unknown commit, and if the commit did apply, the body applies twice. In a payment or notification path that is a duplicate charge or a duplicate message, produced by the error handler.
The related trap is session reuse: retrying on the same session after an abort carries the aborted transaction's state into the retry.
Decision
MongoTransactionRetryCoordinator implements two loops with different scopes.
for each body attempt within the budget:
open a NEW session
run the body
TransientTransactionError -> abort, continue to next body attempt
commitWithRetry(session):
UnknownTransactionCommitResult -> retry the COMMIT ONLY, same session
Rules that follow, all of them load-bearing:
- A new session per body attempt. No aborted state leaks into a retry.
- The body is never replayed after a commit ambiguity.
MongoRetryScope.COMMIT_ONLYis a distinct value fromBODYprecisely so this cannot be collapsed by accident. - One budget bounds both loops.
MongoRetryBudgetlimits attempts and elapsed time, with jittered backoff, so a struggling primary is not retried into the ground by every instance at once. - An exhausted commit retry surfaces
TRANSACTION_COMMIT_UNKNOWN, never a generic failure. An ambiguous outcome reported as a failure invites the caller to retry — the one thing that must not happen. See docs/mongodb/runbooks/unknown-commit.md. - Transaction bodies write a deterministic marker so
MongoCommitReconcilercan establish what actually happened. A transaction that cannot be reconciled has no recovery path. - Classification reads labels before codes. Server error labels are the authoritative statement about retryability; error codes vary by version.
Surrounding decisions that reduce how often this path is reached at all: single-document atomic
operations are preferred over transactions (D-09), partial changes use update operators rather than
save() (D-07), and whole-document replacement requires an optimistic revision (D-08).
Consequences
Positive. A commit ambiguity cannot become a duplicate effect. The ambiguity reaches the caller as an ambiguity. The retry budget is bounded in both attempts and time.
Negative. Callers must handle a third outcome beyond success and failure. Transaction bodies must write a marker they would not otherwise need. Both costs are small compared with reconciling duplicated financial effects after the fact.
Rejected alternative — "one retry loop, at-least-once everywhere." It requires every transaction body to be fully idempotent, which is a much stronger and much less checkable property than writing one marker, and it is silently violated the first time someone adds a non-idempotent step.