Registration Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 16 offline-first
1. Per-Aggregate Conflict Policy
| Aggregate / Resource | Conflict policy | Rationale |
|---|---|---|
PatientAggregate (demographics) | server_authoritative + optimistic lock | Identity is safety-critical; client must hold version and retry with updated values on conflict. Server wins on concurrent edits. |
PatientIdentifier | server_authoritative | Identifier uniqueness is enforced server-side; client cannot merge conflicting identifiers. |
PatientName | server_authoritative | Multi-script name display rules require server validation; client provides intent, server confirms. |
NextOfKinEntry | append_only (additions); server_authoritative (removals) | New NOK entries accumulate safely; removal requires explicit user action with audit. |
ConsentFlag | server_authoritative | Consent state is legal record; requires explicit user action; no client merge. |
EncounterAggregate | server_authoritative + optimistic lock | Status machine is enforced server-side; client cannot skip transitions. |
PatientPortrait | server_authoritative | Binary with consent/retention policy; always server-resolved. |
PatientExtensionInstance | server_authoritative | JSON Schema validation is server-side; conflicts resolved by server with optimistic lock on version. |
| MPI merge decisions | server_authoritative | Safety-critical; human-approved and server-executed; offline merge is prohibited. |
2. Offline-first Considerations
| Scenario | Handling |
|---|---|
| Create patient while offline | Idempotent create supported: client sends Idempotency-Key or clientMutationId; server deduplicates on reconnect |
| Update demographics offline | Allowed with version snapshot; on sync, if version stale → OPTIMISTIC_LOCK_CONFLICT returned; client prompts for re-review |
| Search patients offline | Clients may use local cache (read-only); writes queued for server reconciliation |
| Encounter status transition offline | planned→arrived permitted offline; server validates on sync; in-progress→finished requires online confirmation |
| Merge / unmerge offline | Prohibited — safety-critical operation requires real-time server execution |
| Vital status (deceased) offline | Prohibited — legal record; online-only |
3. Sync Sequencing
Offline writes are ordered by clientMutationId timestamp. On reconnect, the sync layer replays mutations in order. Server rejects duplicates via idempotency store (24h TTL).