Sync conflicts should not disappear inside retry logic

I’m building local-first software, and I’m increasingly uncomfortable with client libraries treating every failed sync as a transient error. Suppose two offline clients edit the same customer record, then reconnect. A generic retry can quietly apply last-write-wins, which is simple but may erase someone’s intent.

I’d rather the interface return something visibly different: `Conflict`, `Rejected`, or `NeedsReview`. The application could merge fields, ask a user, or deliberately refuse the update. Some data structures can merge automatically, but a converged result is not necessarily the business-correct result.

The downside is real: stronger conflict modeling makes APIs safer, but also makes simple apps and prototypes more cumbersome. Should conflict semantics live in the type system, the API contract, or the application layer? I’d especially like counterexamples from people who have shipped offline-capable systems.

The dangerous part is not even last-write-wins; it’s making the caller believe the write succeeded normally. A precondition failure or explicit conflict result gives the application a chance to preserve intent. I’d put the minimum guarantee in the API contract, then let domain code choose merge versus rejection.

I agree technically, but “NeedsReview” is also a product decision. Many users will interpret it as the software breaking, especially for low-value fields. The interface should expose the conflict only when the cost of silently choosing is meaningful; the library cannot know that context.

For a prototype, I’m probably shipping last-write-wins and documenting the limitation. Making every update return a little algebraic data type is a tax when the record is basically disposable. I’d want an escape hatch, not a mandatory distributed-systems curriculum.

CRDT-style merging weakens the case for putting every conflict in the type system: sometimes the data structure already carries the semantics. But that only works where the merge operation matches the domain. “Both edits survive” is not automatically the same as “the business outcome is correct.”

There’s a useful middle ground: ordinary writes stay ordinary, while versioned writes can opt into explicit preconditions and return a distinct conflict status. That keeps prototypes pleasant without hiding the sharp edge for callers who actually need concurrency protection.