Medication Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 16 Offline & Sync
1. Sync Scope
The medication-service has two offline surfaces:
- Clinical prescribing (EHR clinical shell) — read-mostly on mobile/tablet field devices; occasional draft.
- Pharmacy portal — full dispensing queue + label printing + GRN stock receive in offline mode for 4h+.
2. Per-Aggregate Conflict Policy
| Aggregate | Policy | Rationale |
|---|---|---|
| Prescription (draft) | lww+diff | Field-level last-writer-wins on non-signed drafts; merge independent fields (dose vs instructions) |
| Prescription (signed/active) | server_authoritative | Signed Rx is clinically immutable; server state always wins on sync |
| DispensingEvent | append_only | Immutable event log; idempotency key prevents dup; conflicts rejected with reconcile action |
| StockItem | server_authoritative | Inventory authoritative server-side; offline dispenses enqueue deltas applied atomically on sync |
| MedicationAdministration | append_only | MAR events are immutable; corrections are new entries linked to prior |
| ReconciliationSession | server_authoritative | Conflict surfaced to user when session status diverges; user resolves |
| AlertOverrideRecord | append_only | Immutable override log |
| Medication (reference) | server_authoritative | Read-only formulary catalog; server wins |
3. Offline Behavior
| Capability | Offline mode |
|---|---|
| Read prescriptions | ✅ (cached subset by patient context) |
| Draft prescription | ✅ queued, synced on reconnect |
| Sign prescription | ❌ requires online KB check (policy: safety-critical) |
| Record dispense | ✅ queued with idempotency key; stock decrement tentative until sync confirms |
| Record MAR event | ✅ append queue |
| Receive stock (GRN) | ✅ queued |
| Inventory adjustments | ❌ requires online (supervisor gate) |
| Alert override | ❌ requires online KB snapshot version |
4. Conflict Surfacing
- Tentative offline dispenses that fail stock reservation on sync: flag to pharmacist, requeue, user decides to switch lot, partial-dispense, or cancel.
- Home-med reconciliation conflict (two devices opened session): server resolves as
entered-in-erroron both; user re-starts a single session.
5. Encryption at rest on device
- Device-bound keys from identity-service encrypt local pharmacy data.
- Device revocation invalidates local cache within 5 minutes when online.