Module control_plane 

Control-plane consensus seam (issue #996, parent #987, ADR 0052).

The Cluster Supervisor coordinates membership, leader election, and shard/range ownership through a Raft-equivalent control-plane consensus layer — and only the control plane. ADR 0052 fixes the boundary; this module is the small internal abstraction that boundary lives behind, so the follow-up implementation slices (the replicated log, its durable store, its snapshot/compaction) target a named seam instead of picking a consensus library or inventing protocol semantics.

What goes through this layer — and what never does

The control-plane log carries exactly two kinds of entry:

• a membership change — admission, removal, or role change of a cluster member; and
• an ownership-catalog transition — a fenced, versioned move / split / merge / promote of a shard/range (ADR 0037).

ControlPlaneEntry is closed over exactly these two: there is, by construction, no user-data variant. User-data writes are never recorded in, ordered by, or gated on the control-plane log — they flow through the data plane (WAL → logical stream → replicas, ADR 0030/0044) under per-range ownership and commit policy. The control plane decides who may write a range and where it lives; it does not carry what is written. The two logs are physically separate and a user write touches exactly one of them. This is the central line ADR 0030 drew (“the term/epoch and vote-safety ideas without running data payloads through a Raft log”) made concrete and type-enforced.

Relationship to the election core

The election half of this protocol already exists: term-based, quorum-gated election with a durable last-vote in super::election (issue #834), and the vote-only super::witness profile (issue #836). This seam names the log half — append + commit of control-plane entries — and ties it to the same role/term so the whole forms one Raft-equivalent layer. The concrete engine behind ControlPlaneConsensus (an embedded Raft crate, the election core extended with a replicated log, or another quorum protocol) is an implementation detail; swapping it must not change the boundary above.

Durable state requirement

An implementation must persist, fsync-ordered, before acknowledging a vote grant or reporting an entry committed: the current term, voted_for for that term (the existing super::election::LastVoteStore), and the accepted control-plane log entries plus the highest committed index. Election safety (one leader per term) and log safety (a committed entry is never lost) both depend on it (ADR 0052, safety properties 1–3).

Structs

ControlPlanePayload

Opaque, already-encoded body of a control-plane entry.

Enums

ControlPlaneEntry

A single entry in the control-plane log.

ControlPlaneEntryKind

The kind of a ControlPlaneEntry, without its payload.

ControlPlaneRole

This node’s role in the control-plane consensus layer.

ProposeRefusal

Why a ControlPlaneConsensus::propose was refused.

Traits

ControlPlaneConsensus

The Cluster Supervisor’s control-plane consensus seam.

Type Aliases

ControlPlaneLogIndex

Position of an entry in the control-plane log. Monotonic per term-history; an entry is durable once its index is at or below the committed index of a quorum.

MemberId

Stable identity of a cluster member, matching the election membership id (super::election::Member::id) and the replica/ack id namespace.