Function: resolvesplitbrain in leader-election/leaderelection.py

Date: 2026-05-29

Time: 13:21

resolvesplit_brain — Split-Brain Resolution in Bully Leader Election

Purpose

This is a safety net on the BullyElectionCluster simulation harness that detects and resolves split-brain conditions — situations where two or more nodes simultaneously believe they are the leader. In a real distributed system, split-brain is one of the most dangerous failure modes because conflicting leaders can accept divergent writes. This method enforces the Bully Algorithm's core invariant: the highest-ID available node is always the rightful leader.

It exists because the message-passing simulation in tick() can leave the cluster in a transiently inconsistent state. Network partitions healing, simultaneous elections, or message delivery ordering can all produce multiple self-proclaimed leaders within a single tick. Rather than proving the message loop is always convergent in one pass, the code takes the pragmatic route of detecting and correcting the violation after each tick completes.

Contract

Parameters

| Parameter | Type | Description |

|-----------|------|-------------|

| currenttime | int | The simulation's logical clock value for the current tick. Passed through to startelection() so that election messages carry the correct timestamp. |

No validation is performed on current_time. The method assumes it's a monotonically increasing integer consistent with the rest of the simulation.

Return Value

None. This method operates entirely through side effects.

Algorithm

1. Detect: Scan all nodes and collect IDs of those that are both available (is_available() == True) and in "leader" state. Unavailable nodes are excluded — a crashed node's stale state doesn't count.

2. Guard: If zero or one leaders exist, there's no split-brain. Exit immediately.

3. Choose winner: highest = max(leaders) — the highest-ID leader survives. This node is left completely untouched; it keeps its "leader" state, term, and heartbeat schedule.

4. Force losers to step down: For each other leader (lid != highest):

5. Deliver one round of messages: The ELECTION messages are delivered to their receivers. Each receiver may respond (e.g., with ALIVE if it has a higher ID, or by starting its own election). Those responses are delivered too — but only one level deep. The delivery is not recursive; it processes exactly two hops (election → response → delivery of response).

Side Effects

Error Handling

None. The method silently handles missing receivers via self.nodes.get(msg.receiver_id) returning None and the if receiver guard skipping delivery. No exceptions are raised or caught. If a node ID in a message doesn't exist in self.nodes, the message is silently dropped.

Usage Patterns

Called exactly once per tick(), as the final step after all normal message delivery has completed:


def tick(self, current_time: int) -> None:
    # ... collect and deliver all messages ...
    self._resolve_split_brain(current_time)

This is a private method (_ prefix) — it's internal to BullyElectionCluster and not part of the public API. Callers of tick() don't need to know it exists; they just get the guarantee that split-brain won't persist across ticks.

Dependencies

Assumptions Not Enforced by Types

1. currenttime is consistent with self.current_time — nothing prevents passing a stale or future timestamp.

2. Two hops of delivery is sufficient — the code delivers election messages and their immediate responses, but if those responses trigger further cascading messages, they are dropped. This assumes one round is enough to begin convergence; the next tick() will finish the job.

3. max(leaders) is the correct winner — this hard-codes the Bully Algorithm's rule. If the election protocol were changed (e.g., to Raft's term-based leadership), this resolution logic would silently enforce the wrong invariant.

4. No concurrent modification — the method mutates node state while iterating, assuming single-threaded execution. In a concurrent environment, the leader list could change mid-iteration.

Topics to Explore

Beliefs