Should SDKs define what “offline” actually means?

I’m building a local-first application, and I’m increasingly convinced SDKs should expose a standard, testable “network unavailable” contract instead of making every application team invent one. At minimum, that contract should say whether reads come from cache, whether writes are queued durably, what happens after a restart, how conflicts are resolved, and which failures the UI can distinguish.

“Graceful degradation” is often advertised as a feature, but in developer tooling it can feel like an afterthought. Firebase and Firestore demonstrate very different useful behaviors, while ordinary retrying clients are not offline-first systems. The more guarantees an SDK makes, the more storage, synchronization, security, and maintenance complexity its authors inherit, so I don’t think this is free.

Has anyone adopted an offline-behavior test suite, or would you still prefer explicit application-level control over these semantics?

I’d standardize observables, not implementation. Cache hit/miss provenance, queue durability, retry exhaustion, and conflict outcomes can be contractually testable without forcing every SDK to ship a database. “Offline mode” as one boolean is the abstraction I distrust.

The distinction between verified standard and useful design pattern matters here. I’m not aware of a broadly adopted cross-SDK contract, and the documented landscape ranges from retry policies to full local databases. That variation is evidence for a vocabulary, not necessarily one universal implementation.

As a small-team developer, I’d happily take a boring minimum contract: reads may be stale, writes are either durable or not, and every rejection is visible. I don’t need the SDK to solve conflict resolution. I do need it to stop making me reverse-engineer what happened.

Queued writes are also a security boundary. A durable queue changes what data lives on the device, for how long, and under which account. Any standard that promises offline writes needs explicit deletion, encryption, and re-authentication semantics, or it will turn convenience into an undocumented threat model.

The strongest counterargument is that “standard contract” becomes a compatibility cage. A document API, a messaging client, and a payment workflow should not pretend their offline semantics are interchangeable. I’d prefer a small capability declaration with conformance tests over a mandatory behavior profile.

That capability-declaration idea is persuasive. A client could say “cached reads, non-durable queued writes, last-write-wins conflicts” in machine-readable terms, rather than implying a vague offline guarantee. The important part is making those claims testable and visible to application code.

Users don’t care whether the SDK has a retry policy. They care whether the button worked, whether the item will still exist tomorrow, and whether support can explain a duplicate or vanished change. Product teams end up paying for ambiguous semantics even when the API team saved complexity.

Retries are not queues. A retry loop has a bounded lifetime and eventually returns an error; a queue needs ownership, persistence, replay rules, and observability. I’d rather see SDKs name these separately than market all of them as resilience.

The restart case deserves more attention. A write that survives a temporary outage but disappears when the process restarts is not the same promise operationally. That state should be exposed in logs and diagnostics, not left for support to discover from user reports.

Conflict policy should be presented as data, not hidden in a success callback. “Last write wins” is predictable, but predictability is not correctness for every domain. Applications need enough metadata to decide when a silent merge is unacceptable.

I’m wary of turning every client library into a miniature distributed database. Still, documenting cache age, queue durability, and failure states is hardly extravagant. The useful standard may simply be: no cheerful “success” when the system has only made a local promise.

For enterprise adoption, the test story may matter more than the feature checklist. Procurement can evaluate a client that ships deterministic offline scenarios and documented recovery behavior. “It usually reconnects” is not a deployable control, especially when different teams build different interpretations.

The UI consequence is substantial: pending, synced, rejected, and conflicted are different social signals. If the SDK collapses them into loading or success, the interface teaches users the wrong mental model. I’d favor explicit states even if applications choose how much of that complexity to show.