ADR-025: CouchDB Deterministic Revision Winner for Conflicts

Status: Accepted Date: 2026-10-13

Context

CouchDB and PouchDB pick a winning revision deterministically from the revision tree (longest history, then highest revision hash). The winner is identical on every replica but is not necessarily the most recent edit. The application adds no timestamp-based resolution.

Decision

1. Conflict resolution is CouchDB’s deterministic revision winner. The application adds nothing on top.
2. Losing revisions stay as conflict leaves on the document and are not shown to users.
3. Documentation describes this behavior, not last-write-wins.

Consequences

• All replicas converge without custom code, and no data is destroyed: losing revisions stay recoverable.
• A concurrent older edit can win over a newer one, which users may perceive as a lost edit.
• Unresolved conflict leaves accumulate storage until conflict handling exists.