Use the cached snapshot's version token as the optimistic-concurrency contract for writes
Context
After the DynamoDB cache cut Cash Clearance search latency from 3–5 minutes to under 5 seconds, a second problem surfaced: two users could sit on the same treaty's open transactions and both start marking cleared. Without coordination, duplicate clearances would go through — finance lead angry, audit problem, real customer money out the door twice. The conservative answer was a database-level lock or strict serialization on Aurora; both legible, both safe, both wrong for the latency profile we'd just bought.
Decision
Let the version token on the cached search snapshot do double duty as an optimistic-concurrency check on every write. If the underlying transaction set has shifted since the snapshot, the write fails fast, the user re-runs the search, and the system never lets two users operate on stale data. Name the move explicitly: the DDB cache is no longer a performance optimization, it's the place we read the truth from for this workflow. Walked the decision through with the data team and the finance owner line by line before committing.
Consequences
- Zero duplicate clearances in production since cutover, under concurrent load on 100K+ row result sets.
- The DDB cache is now the workflow's source of truth — if the snapshot semantics are ever wrong, the cache is where they get fixed, not Aurora.
- The interactive latency profile held — no database-level lock contention on writes.
- The harder lesson got written down: the dangerous call isn't moving the contract, it's moving it without explicitly saying you moved it. Name the new contract or you don't have one.