Status: Accepted (documented from implementation)
Applies to: every deployment of the clarity binary (all topologies)
Related: High Availability
The clarity historian must survive single-node failure without an external orchestrator (it ships as a self-contained binary, not only on Kubernetes). It therefore implements its own failover rather than delegating to an external consensus system.
High availability is modelled as an explicit finite state machine over six roles, not a generic quorum/consensus protocol. The roles are defined in a single enum:
Leader, SecondaryHealthy, SecondaryStale, Recovering, Promoting, Fencedclarity:backend/src-tauri/src/ha/role.rs:10-23Only an explicit allow-list of transitions is legal, and every transition is validated:
Role::can_transition_to(target) — clarity:backend/src-tauri/src/ha/role.rs:75-103HaState::transition, which rejects illegal moves with Err("[HA] Illegal transition: …") — clarity:backend/src-tauri/src/ha/state.rs:177-187The cluster is active-passive: one Leader serves writes; Secondaries replicate and are gated out of leader-only services via SingletonGate (see ha.md).
Fenced terminal role separates "stale" from "fenced" (split-brain protection).clarity:backend/src-tauri/src/ha/role.rs:10-23, :75-103clarity:backend/src-tauri/src/ha/state.rs:177-187Last updated: 2026-06-02 from clarity@498c020