Config Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 16 offline-first-and-sync
1. Offline Posture
The config-service is a server-authoritative service. No config state is written from offline clients. Clients consume resolution results (read-only) which may be cached locally with TTL.
2. Per-Aggregate Conflict Policy
| Aggregate | Conflict Policy | Rationale |
|---|---|---|
ConfigNode | server_authoritative | DAG structure must be validated server-side for cycle detection; no offline mutations permitted |
FeatureDefinition | server_authoritative | Admin-only mutation; no offline write path |
RoleDefinition | server_authoritative | Admin-only; system roles require SUPER_ADMIN validation |
RoleInheritance | server_authoritative | BFS depth validation requires full graph; not safe to merge offline |
RoleFeatureGrant | server_authoritative | Permissions must be centrally authoritative |
UserNodeOverride | server_authoritative | Clinical safety: ExplicitDeny must not be overridable by stale offline state |
UIDefinition | server_authoritative | Platform admin tooling only |
UIVisibilityRule | server_authoritative | Admin-only |
DesignToken | server_authoritative | Tenant branding admin only |
EvaluationResult (read cache) | lww (client-side TTL) | Clients may cache resolved results for 60 s; stale reads are acceptable; hard-expiry on cache bust event |
3. Client-Side Caching Rules
| Cache item | Client TTL | Invalidation |
|---|---|---|
EvaluationResult (full resolution) | 60 s | On config.config.cache_busted.v1 received via SSE/WebSocket |
UIElementConfig[] | 120 s | On config.ui_definition.updated.v1 |
DesignTokens map | 300 s | On config.design_token.updated.v1 |
Clients MUST NOT use cached results beyond their TTL without re-validation.
4. Server-Side Redis Cache Contract
| Key pattern | TTL | Eviction trigger |
|---|---|---|
cfg:{tenantId}:{userId}:{nodeId}:{moduleKey}:{featureKey} | 60 s | Any config.feature., config.role., config.user_override.* |
cfg:ui:{tenantId}:{userId}:{featureKey} | 120 s | config.ui_definition.* |
cfg:tokens:{tenantId}:{userId}:{moduleKey}:{locale}:{nodeId} | 300 s | config.design_token.updated.v1 |
cfg:roles:{tenantId}:{roleKey}:expanded | 300 s | config.role., config.role_grant. |
5. Sync Not Applicable
Config mutations do not use CRDT or LWW merge. All writes go through the server and emit events. There is no sync protocol for bidirectional reconciliation. The sync framework (@ghasi/sync-protocol) is not used by this service.