Transitioning Couchbase Java SDK 3.x retry behavior to default idempotent mutations

Goal: guarantee that a transient network error does not cause a duplicate write when a Couchbase mutation is retried using the Java SDK 3.x. The SDK’s retry mechanism re‑sends the same operation, and safety currently depends on the application supplying idempotency through CAS tokens or the mutateIn upsert helper.

Uncertainty remains about whether the retry policy should automatically treat all mutations as idempotent by default, shifting the burden from developers to the SDK and potentially affecting existing code that relies on CAS for conflict detection.

Should the SDK enable idempotent mode by default for all retried mutations? What performance or behavioral side‑effects might arise from such a change? How can existing applications migrate to a default‑idempotent retry model without breaking CAS‑based logic?