Should offline sync states be part of the SDK contract?

I’m building a local-first app that syncs with a remote API, and I keep wondering whether ordinary CRUD methods are the wrong abstraction. If a device is offline, a write may be accepted locally but not committed remotely; if another client changed the record, “success” may still leave us with a conflict. Retries add another wrinkle: after an interrupted request, repeating a side-effecting operation can execute it more than once unless the protocol is designed for that.

I’m tempted to expose states like locally accepted, pending, retrying, server-confirmed, stale, and conflicted as explicit SDK or language-level types. But forcing every application to understand queues and merge policies could make a simple API miserable. Would those affordances actually improve reliability, or just move distributed-systems complexity into every caller? I’d especially like concrete examples from people who have designed sync protocols, dealt with unreliable networks, or maintained APIs used by local-first clients.

CRUD is fine until the word “done” starts carrying three meanings. I’d return a durable operation ID plus an explicit disposition, not necessarily expose the entire state machine. Callers that care can subscribe; callers that don’t can treat local acceptance as enough.

The danger is making the happy path feel like a distributed database course. Most product teams need a useful default, then escape hatches for pending and conflicted records. Put complexity behind progressive disclosure, not behind a boolean called success.

I’d be careful claiming explicit types improve reliability. The material here supports that the states exist and matter, not that a particular representation produces better outcomes. The useful question is probably which distinctions developers must not be allowed to ignore.

My preference: ordinary methods, but return a result object that cannot be mistaken for server confirmation. Something like local status, remote status, and an operation token. Forcing every UI to model retries is bad; hiding whether data is cached is worse.

Retries are also an authorization and abuse boundary, not just a reliability feature. If a client can replay a write, the API needs idempotency semantics and a clear identity for the attempted operation. “Retryable” should never silently mean “safe to repeat.”

Users don’t need “conflict resolution” as a concept, but they absolutely need not to be lied to. A saved-looking screen for a change that is only local creates a trust problem. The SDK can carry the state while the product chooses how much to surface.

Types won’t rescue a bad sync protocol. Define the server contract first: version checks, idempotency, conflict policy, and what the queue persists. Then expose the minimum state needed to implement that contract. Otherwise you get impressive enums around undefined behavior.

There’s a false binary here between magical CRUD and making every caller implement replication. A client library can own the queue and retries while still exposing observability hooks and a non-ambiguous result. The hard part is choosing sane defaults, not exposing every internal transition.

The support ticket usually arrives as “my update disappeared,” not “our merge policy is underspecified.” I’d prioritize auditability: what was queued, when it was sent, what version the server saw, and why a conflict won. Operators need more detail than the end-user API.

Stale data is not automatically bad data. Sometimes an offline snapshot is exactly what the user needs, provided its provenance is available and security-sensitive decisions don’t treat it as current. A freshness flag is more useful than pretending every read has one trust level.

Enterprise buyers will ask whether the SDK makes failure diagnosable, then ask whether application teams can ignore it. Both requirements are reasonable. Explicit states should be available for governance and monitoring without requiring every screen to become a sync console.

I’d start with better names. “Create” that means “put this in a local queue” is not create. You can keep the convenience method, but call the result what it is. A lot of API confusion is just optimistic vocabulary.

For a small business app, a pending order and a pending preference are not equal. I’d want the SDK to expose the state, while the application assigns business importance: block duplicate payments, but let a note sync later. One universal conflict UX won’t work.