설계: 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.2 KiB
Consistency and Transaction Guide
Design §12–§16, decisions D-07 through D-10. This is the part of the platform where the wrong default is most expensive and the least visible in testing, because every failure mode here needs a primary change to reproduce.
1. Prefer a single-document atomic operation
D-09: a transaction is for a multi-document invariant, nothing else. A single document is already atomic in MongoDB, so wrapping a one-document update in a transaction buys nothing and costs a session, a two-phase commit and a new ambiguous outcome.
D-07: partial change uses update operators, not save(). MongoAtomicOperations /
MongoAtomicOperationsTemplate expose the operator set through MongoUpdateOperator
($set, $inc, $push, $pull, $addToSet, $min, $max, $currentDate, …) with an
AtomicFilter precondition and a ReturnDocumentMode. Read-modify-write through save() replaces
the whole document and silently discards any field another writer changed in between — a lost update
with no error.
2. Whole-document replacement needs a revision
D-08. VersionedMongoUpdater requires a MongoRevision: either a Spring Data @Version field or an
explicit expected-revision predicate in VersionedUpdateCommand. A replacement whose filter matched
zero documents is not "nothing to do" — MongoOptimisticConflictTranslator distinguishes:
- filter matched nothing and the id does not exist →
MongoDocumentNotFoundException - filter matched nothing and the id exists →
MongoOptimisticConflictException
Collapsing these two into one is how a concurrent overwrite becomes a 404.
3. Consistency profiles
MongoConsistencyProfile names the read/write concern pair; MongoConsistencyRegistry binds a
profile to an operation or collection, and MongoConsistencyBinder applies it at execution.
| Profile | Meaning | Use for |
|---|---|---|
PRIMARY_LOCAL |
primary read, local concern | Throughput-sensitive reads that tolerate a rollback window. |
PRIMARY_MAJORITY |
primary read, majority write | The default for anything a user will see again immediately. |
CAUSAL_MAJORITY |
majority inside a causal session | Read-your-writes across separate operations. |
STALE_READ_ALLOWED |
secondary reads permitted | Reporting and analytics that state their staleness. |
SNAPSHOT_TRANSACTION |
snapshot isolation | Multi-document reads inside a transaction. |
A profile is a declaration, not a hint: the registry is consulted per operation and an operation without a registered profile is rejected rather than defaulting.
4. Causal sessions
MongoCausalSessionContext plus SpringMongoCausalSessionExecutor carry the cluster time and
operation time between operations, so
"write then read" returns the write even when the read lands on a different node. Without a causal
session, PRIMARY_MAJORITY gives you durability but not read-your-writes across two calls.
5. Transactions
MongoTransactionExecutor opens a session through the session
factory, run the body, and commit. MongoTransactionProfile carries the consistency profile, the
maxCommitTime and the retry budget. Topology matters: a transaction requires a replica set, and
MongoStartupValidator refuses a transaction-declaring profile on STANDALONE at startup rather
than at the first call.
6. Retry: body and commit are different loops
D-10, and the single most consequential rule in the design.
for each body attempt:
open a NEW session
run the body
TransientTransactionError -> abort, next body attempt
commit
UnknownTransactionCommitResult -> retry COMMIT ONLY, same session
MongoTransactionRetryCoordinator implements exactly this:
- A new session per body attempt. Reusing the session after an abort carries the aborted transaction's state into the retry.
- The body is never replayed after a commit ambiguity. An unknown commit means the commit may already have applied. Re-running the body would apply it a second time. Only the commit is retried, and a commit retry on an already-committed transaction is a no-op by design.
- A budget bounds both loops.
MongoRetryBudgetlimits attempts and elapsed time, with jittered backoff (delayBefore(attempt, random)), so a struggling primary is not retried into the ground.
MongoRetryDecision and MongoRetryScope (in …api.error) say what may be retried:
MongoRetryScope.BODY, COMMIT_ONLY, or NONE.
7. Ambiguous outcomes
MongoExecutionOutcome has six values, two of which are ambiguous and must not be collapsed:
| Outcome | Did the write happen? |
|---|---|
NOT_SENT |
No. Safe to retry. |
NO_WRITE_PERFORMED |
No — the server answered and did nothing. |
WRITE_CONFIRMED |
Yes. |
PARTIAL_BULK_WRITE |
Some of it. See MongoBulkResult. |
WRITE_RESULT_UNKNOWN |
Unknown. |
TRANSACTION_COMMIT_UNKNOWN |
Unknown. |
An unknown outcome is not a failure and must not be reported to a caller as one. The caller either
reconciles (MongoCommitReconciler re-reads a deterministic marker the body wrote) or surfaces the
ambiguity. See runbooks/unknown-commit.md.
MongoFailureContext records only the design-permitted fields — outcome, category, operation name,
collection profile, retry scope, attempt — never the query, the document, or the values.
8. Failure translation
DefaultMongoFailureClassifier classifies labels before codes. The server's error labels
(TransientTransactionError, UnknownTransactionCommitResult, RetryableWriteError) are the
authoritative statement about retryability; an error code is a secondary signal whose meaning varies
by server version. DefaultMongoFailureTranslator maps a classification onto the stable exception
hierarchy, and anything unmatched becomes MongoUnclassifiedFailureException rather than leaking a
driver type.
9. Bulk writes
MongoBulkExecutor returns a MongoBulkResult with per-item MongoBulkItemFailure entries. An
unordered bulk write that partially fails is PARTIAL_BULK_WRITE, not a failure: some documents were
written. The result's per-item outcomes say which indexes succeeded and which failed, so a caller can
resume rather than replay.