Synchronization: Implementation and reliability
Offline edits carry stable operation identity; the server remains authoritative for conflicts, tombstones propagate deletes, and clients surface merge outcomes instead of silently dropping divergent local changes.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Clients queue offline mutations with stable operation ids and base revision pointers. On reconnect, the server validates each operation against current authoritative state. Conflicts produce explicit outcomes—server wins, client merge required, or forked draft—rather than last-writer-wins silence. Deletes propagate as tombstones visible to offline clients so resurrected rows do not reappear. The server is authoritative for merge decisions; clients display results and retain audit copies of rejected local ops when profile requires.
Scope
- Operation id assignment, idempotent replay, and base revision binding.
- Server validation, conflict classification, and response payloads.
- Tombstone retention and delete propagation to offline caches.
- Client UX states for in-sync, conflict-needs-attention, and rejected-local-op.
- Metrics on conflict rate, replay duplicates prevented, and tombstone resurrection blocked.
Outside this block
- Full text CRDT implementation.
- Binary large object delta sync.
- Push notification payload design.
Contract
- Each offline mutation includes operation_id and base_revision; duplicates replay original server outcome.
- Server rejects or conflicts operations whose base_revision lags authoritative head according to typed rules.
- Tombstones suppress deleted entities in client caches until purge interval elapses; resurrect without authority is blocked.
- Conflict responses name fields in disagreement and required client action; silent discard of local ops is forbidden in strict profile.
- Server authority wins for safety-critical fields defined in profile unless user merge UI completes.
- Batch sync commits are partial-order safe; accepted ops persist before conflict notifications return.
- Clock skew does not determine winner; revision vectors or server sequence govern.
Implementation guidance
- Persist operation outbox on client with exponential backoff replay.
- Return structured conflict bodies suitable for field-level UI merge.
- JSON Patch may encode field changes and HTTP conditional requests may carry preconditions, but neither defines this product's conflict policy;
sync-states.yaml, revision evidence, and server authority remain the governing contract. - Garbage-collect tombstones only after all known offline clients exceed sync horizon or explicit purge policy.
Failure handling and safeguards
- If sync interrupted mid-batch, retry operation ids must not double-apply side effects.
- Do not drop queued ops on logout without explicit user discard or secure wipe policy.
- Large conflict backlogs trigger user notification rather than unbounded background retry.
Verification and operations
- Monitor conflict rate by entity type, duplicate ops suppressed, tombstone resurrection attempts blocked.
- Test airgap offline edits crossing delete-on-server scenario.
- Execute acceptance scenarios in the target repository; packaged scenarios are not executed evidence.
Adoption assumptions
- Retention intervals and field authority lists in fixtures are profile choices.
- Teams map entity models and UI merge flows locally.