AI Gateway Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 16 offline-first-and-sync
AI Gateway is a synchronous online-only service. Assist calls require provider reachability and policy evaluation; offline clients cannot produce AI drafts autonomously.
1. Aggregate conflict policy
| Aggregate | Policy | Notes |
|---|---|---|
AIDecision | server_authoritative | All state transitions server-side; client may submit a review only when online. Optimistic lock on version. |
AIProvenance | append_only | Immutable; never conflicts. |
DecisionReviewEvent | append_only | One row per reviewer action. |
ProviderAttempt | append_only | — |
ModerationFinding | append_only | — |
PromptTemplate | server_authoritative | Admin path only; reads cached client-side for 5 min. |
ProviderRoutingRule | server_authoritative | — |
TenantQuota/QuotaWindow | server_authoritative | Redis-backed; strict. |
2. Offline behaviour
| Client | Behaviour when offline |
|---|---|
| Clinical mobile app | AI features are gracefully hidden (no local model fallback for clinical use); the action is queued for online re-submission where safe (e.g. note draft). |
| Patient portal | AI triage disabled with a "Feature requires network" notice. |
| Reviewer dashboard | Read of cached pending-review list shown read-only; actions queued; a confirmation dialog warns that review must happen online. |
3. Queued actions
Client SDK may queue POST /api/v1/ai/assist with Idempotency-Key. On reconnection the SDK retries with the same key. Server treats the first successful outcome as canonical and returns the stored decision on retries.
4. Replay protection
Idempotency-Key (ULID) stored for 24h; repeated assists with the same key return the same decisionId and provenance.