raptiye 0.1.0

package/src/core/engine.js

@@ -0,0 +1,907 @@
+/**
+ * Pure deterministic consensus state machine for Raptiye.
+ * Zero external side-effects: input event -> output effects.
+ */
+
+import { Role, MessageType, EntryType, EffectType, EventType } from '../types.js';
+
+export class ConsensusEngine {
+  constructor({
+    id,
+    peers = [],
+    storage,
+    maxBatchBytes = 64 * 1024,
+    maxBatchEntries = 256,
+    maxInflightBatches = 16,
+    maxInflightBytes = 4 * 1024 * 1024
+  }) {
+    this.id = Number(id);
+    this.peers = peers.map(Number).filter(p => p !== this.id);
+    this.storage = storage;
+
+    this.maxBatchBytes = maxBatchBytes;
+    this.maxBatchEntries = maxBatchEntries;
+    this.maxInflightBatches = maxInflightBatches;
+    this.maxInflightBytes = maxInflightBytes;
+
+    // Persistent state
+    const hardState = storage.getHardState();
+    this.currentTerm = hardState ? BigInt(hardState.currentTerm) : 0n;
+    this.votedFor = hardState && hardState.votedFor !== null ? Number(hardState.votedFor) : null;
+
+    // Volatile state
+    this.role = Role.FOLLOWER;
+    this.commitIndex = 0n;
+    this.lastApplied = 0n;
+    this.leaderId = null;
+
+    // Tracking for invariants
+    this._prevCheckedCommitIndex = 0n;
+
+    // Candidate election state
+    this.preVotes = new Set();
+    this.votes = new Set();
+
+    // Leader volatile state
+    this.nextIndex = new Map();
+    this.matchIndex = new Map();
+    this.inflightBatches = new Map();
+    this.inflightBytes = new Map();
+
+    // Leadership transfer
+    this.transferTarget = null;
+
+    this._initPeerProgress();
+  }
+
+  _initPeerProgress() {
+    const last = this.storage.lastIndex();
+    for (const peer of this.peers) {
+      this.nextIndex.set(peer, last + 1n);
+      this.matchIndex.set(peer, 0n);
+      this.inflightBatches.set(peer, 0);
+      this.inflightBytes.set(peer, 0);
+    }
+  }
+
+  quorumSize() {
+    return Math.floor((this.peers.length + 1) / 2) + 1;
+  }
+
+  /**
+   * Main state machine entry point.
+   * Pure function: takes an event, mutates internal FSM, and returns an array of effects.
+   * 
+   * @param {{ type: string, [key: string]: any }} event
+   * @returns {Array<{ type: string, [key: string]: any }>} effects
+   */
+  step(event) {
+    const effects = [];
+
+    switch (event.type) {
+      case EventType.ELECTION_TIMEOUT:
+      case EventType.TIMEOUT_NOW:
+        this._handleElectionTimeout(event, effects);
+        break;
+
+      case EventType.HEARTBEAT_TIMEOUT:
+        this._handleHeartbeatTimeout(effects);
+        break;
+
+      case EventType.SUBMIT:
+        this._handleSubmit(event, effects);
+        break;
+
+      case EventType.MESSAGE:
+        this._handleMessage(event.message, effects);
+        break;
+
+      case EventType.TRANSFER_LEADERSHIP:
+        this._handleTransferLeadership(event.targetPeer, effects);
+        break;
+    }
+
+    return effects;
+  }
+
+  _handleElectionTimeout(event, effects) {
+    if (this.role === Role.LEADER) {
+      return;
+    }
+
+    // Single-node cluster becomes leader immediately
+    if (this.peers.length === 0) {
+      this._becomeLeader(effects);
+      return;
+    }
+
+    const isTimeoutNow = event.type === EventType.TIMEOUT_NOW;
+
+    if (isTimeoutNow || this.role === Role.FOLLOWER || this.role === Role.PRE_CANDIDATE) {
+      // Step 1: Pre-Vote phase (prevents disruptive term increases from isolated nodes)
+      this.role = Role.PRE_CANDIDATE;
+      this.preVotes.clear();
+      this.preVotes.add(this.id);
+
+      const candidateTerm = this.currentTerm + 1n;
+      const lastIndex = this.storage.lastIndex();
+      const lastTerm = this.storage.lastTerm();
+
+      for (const peer of this.peers) {
+        effects.push({
+          type: EffectType.SEND,
+          to: peer,
+          message: {
+            type: MessageType.PRE_VOTE_REQUEST,
+            term: candidateTerm,
+            sourceNode: this.id,
+            destNode: peer,
+            candidateId: this.id,
+            lastLogIndex: lastIndex,
+            lastLogTerm: lastTerm
+          }
+        });
+      }
+
+      effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+    }
+  }
+
+  _handleHeartbeatTimeout(effects) {
+    if (this.role !== Role.LEADER) {
+      return;
+    }
+
+    // Send heartbeats / pipeline pending entries to all peers
+    for (const peer of this.peers) {
+      this._replicateToPeer(peer, effects, true);
+    }
+
+    effects.push({ type: EffectType.RESET_HEARTBEAT_TIMER });
+  }
+
+  _handleSubmit(event, effects) {
+    if (this.role !== Role.LEADER) {
+      effects.push({
+        type: 'ERROR',
+        error: 'NOT_LEADER',
+        leaderId: this.leaderId
+      });
+      return;
+    }
+
+    if (this.transferTarget !== null) {
+      effects.push({
+        type: 'ERROR',
+        error: 'LEADERSHIP_TRANSFERRING',
+        target: this.transferTarget
+      });
+      return;
+    }
+
+    const payload = event.payload || new Uint8Array(0);
+    const index = this.storage.lastIndex() + 1n;
+    const entry = {
+      term: this.currentTerm,
+      index,
+      type: event.entryType || EntryType.NORMAL,
+      payload
+    };
+
+    this.storage.append(entry);
+    effects.push({
+      type: EffectType.PERSIST_ENTRIES,
+      entries: [entry]
+    });
+
+    // Single-node cluster commit
+    if (this.peers.length === 0) {
+      this.commitIndex = index;
+      this._advanceApplied(effects);
+      effects.push({
+        type: EffectType.NOTIFY_COMMITTED,
+        index
+      });
+      return;
+    }
+
+    // Replicate to all peers
+    for (const peer of this.peers) {
+      this._replicateToPeer(peer, effects, false);
+    }
+  }
+
+  _handleTransferLeadership(targetPeer, effects) {
+    if (this.role !== Role.LEADER) return;
+    const peer = Number(targetPeer);
+    if (!this.peers.includes(peer)) return;
+
+    this.transferTarget = peer;
+    const targetMatch = this.matchIndex.get(peer) || 0n;
+    const lastIndex = this.storage.lastIndex();
+
+    if (targetMatch >= lastIndex) {
+      // Follower is fully caught up! Send TIMEOUT_NOW immediately
+      effects.push({
+        type: EffectType.SEND,
+        to: peer,
+        message: {
+          type: MessageType.TIMEOUT_NOW,
+          term: this.currentTerm,
+          sourceNode: this.id,
+          destNode: peer,
+          leaderId: this.id
+        }
+      });
+    } else {
+      // Replicate urgently to target
+      this._replicateToPeer(peer, effects, false);
+    }
+  }
+
+  _handleMessage(msg, effects) {
+    // If msg has higher term, revert to follower
+    if (msg.term > this.currentTerm) {
+      if (msg.type !== MessageType.PRE_VOTE_REQUEST && msg.type !== MessageType.PRE_VOTE_RESPONSE) {
+        this._becomeFollower(msg.term, null, effects);
+      }
+    }
+
+    switch (msg.type) {
+      case MessageType.PRE_VOTE_REQUEST:
+        this._handlePreVoteRequest(msg, effects);
+        break;
+
+      case MessageType.PRE_VOTE_RESPONSE:
+        this._handlePreVoteResponse(msg, effects);
+        break;
+
+      case MessageType.VOTE_REQUEST:
+        this._handleVoteRequest(msg, effects);
+        break;
+
+      case MessageType.VOTE_RESPONSE:
+        this._handleVoteResponse(msg, effects);
+        break;
+
+      case MessageType.APPEND_REQUEST:
+        this._handleAppendRequest(msg, effects);
+        break;
+
+      case MessageType.APPEND_RESPONSE:
+        this._handleAppendResponse(msg, effects);
+        break;
+
+      case MessageType.HEARTBEAT:
+        this._handleHeartbeat(msg, effects);
+        break;
+
+      case MessageType.TIMEOUT_NOW:
+        // Immediate election trigger
+        this._handleElectionTimeout({ type: EventType.TIMEOUT_NOW }, effects);
+        break;
+
+      case MessageType.SNAPSHOT_BEGIN:
+      case MessageType.SNAPSHOT_CHUNK:
+      case MessageType.SNAPSHOT_END:
+        this._handleSnapshotMessage(msg, effects);
+        break;
+
+      case MessageType.SNAPSHOT_RESPONSE:
+        this._handleSnapshotResponse(msg, effects);
+        break;
+    }
+  }
+
+  _handlePreVoteRequest(msg, effects) {
+    let voteGranted = false;
+    const candidateTerm = BigInt(msg.term);
+
+    // Pre-vote condition: candidate term must be greater than currentTerm,
+    // and candidate log must be at least as up-to-date as receiver log
+    if (candidateTerm > this.currentTerm) {
+      const myLastIndex = this.storage.lastIndex();
+      const myLastTerm = this.storage.lastTerm();
+      const candidateLastIndex = BigInt(msg.lastLogIndex);
+      const candidateLastTerm = BigInt(msg.lastLogTerm);
+
+      const logUpToDate = candidateLastTerm > myLastTerm ||
+        (candidateLastTerm === myLastTerm && candidateLastIndex >= myLastIndex);
+
+      if (logUpToDate) {
+        voteGranted = true;
+      }
+    }
+
+    effects.push({
+      type: EffectType.SEND,
+      to: msg.candidateId,
+      message: {
+        type: MessageType.PRE_VOTE_RESPONSE,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: msg.candidateId,
+        voteGranted
+      }
+    });
+  }
+
+  _handlePreVoteResponse(msg, effects) {
+    if (this.role !== Role.PRE_CANDIDATE) return;
+
+    if (msg.voteGranted) {
+      this.preVotes.add(msg.sourceNode);
+      if (this.preVotes.size >= this.quorumSize()) {
+        // Pre-vote quorum achieved -> Transition to Candidate & begin real election
+        this._startElection(effects);
+      }
+    }
+  }
+
+  _startElection(effects) {
+    this.role = Role.CANDIDATE;
+    this.currentTerm += 1n;
+    this.votedFor = this.id;
+    this.votes.clear();
+    this.votes.add(this.id);
+
+    this.storage.setHardState({
+      currentTerm: this.currentTerm,
+      votedFor: this.votedFor
+    });
+
+    effects.push({
+      type: EffectType.PERSIST_HARD_STATE,
+      currentTerm: this.currentTerm,
+      votedFor: this.votedFor
+    });
+
+    effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+
+    const lastIndex = this.storage.lastIndex();
+    const lastTerm = this.storage.lastTerm();
+
+    for (const peer of this.peers) {
+      effects.push({
+        type: EffectType.SEND,
+        to: peer,
+        message: {
+          type: MessageType.VOTE_REQUEST,
+          term: this.currentTerm,
+          sourceNode: this.id,
+          destNode: peer,
+          candidateId: this.id,
+          lastLogIndex: lastIndex,
+          lastLogTerm: lastTerm
+        }
+      });
+    }
+  }
+
+  _handleVoteRequest(msg, effects) {
+    let voteGranted = false;
+    const msgTerm = BigInt(msg.term);
+
+    if (msgTerm >= this.currentTerm) {
+      if (msgTerm > this.currentTerm) {
+        this._becomeFollower(msgTerm, null, effects);
+      }
+
+      const canVote = (this.votedFor === null || this.votedFor === msg.candidateId);
+      if (canVote) {
+        const myLastIndex = this.storage.lastIndex();
+        const myLastTerm = this.storage.lastTerm();
+        const candidateLastIndex = BigInt(msg.lastLogIndex);
+        const candidateLastTerm = BigInt(msg.lastLogTerm);
+
+        const logUpToDate = candidateLastTerm > myLastTerm ||
+          (candidateLastTerm === myLastTerm && candidateLastIndex >= myLastIndex);
+
+        if (logUpToDate) {
+          voteGranted = true;
+          this.votedFor = msg.candidateId;
+          this.storage.setHardState({
+            currentTerm: this.currentTerm,
+            votedFor: this.votedFor
+          });
+
+          effects.push({
+            type: EffectType.PERSIST_HARD_STATE,
+            currentTerm: this.currentTerm,
+            votedFor: this.votedFor
+          });
+
+          effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+        }
+      }
+    }
+
+    effects.push({
+      type: EffectType.SEND,
+      to: msg.candidateId,
+      message: {
+        type: MessageType.VOTE_RESPONSE,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: msg.candidateId,
+        voteGranted
+      }
+    });
+  }
+
+  _handleVoteResponse(msg, effects) {
+    if (this.role !== Role.CANDIDATE || BigInt(msg.term) !== this.currentTerm) {
+      return;
+    }
+
+    if (msg.voteGranted) {
+      this.votes.add(msg.sourceNode);
+      if (this.votes.size >= this.quorumSize()) {
+        this._becomeLeader(effects);
+      }
+    }
+  }
+
+  _becomeLeader(effects) {
+    this.role = Role.LEADER;
+    this.leaderId = this.id;
+    this.transferTarget = null;
+    this._initPeerProgress();
+
+    effects.push({ type: EffectType.BECOME_LEADER });
+    effects.push({ type: EffectType.RESET_HEARTBEAT_TIMER });
+
+    // Append a NOOP entry to establish leadership and commit entries from prior terms
+    const noopIndex = this.storage.lastIndex() + 1n;
+    const noopEntry = {
+      term: this.currentTerm,
+      index: noopIndex,
+      type: EntryType.NOOP,
+      payload: new Uint8Array(0)
+    };
+    this.storage.append(noopEntry);
+
+    effects.push({
+      type: EffectType.PERSIST_ENTRIES,
+      entries: [noopEntry]
+    });
+
+    if (this.peers.length === 0) {
+      this.commitIndex = noopIndex;
+      this._advanceApplied(effects);
+      effects.push({
+        type: EffectType.NOTIFY_COMMITTED,
+        index: noopIndex
+      });
+      return;
+    }
+
+    // Broadcast AppendEntries to all followers
+    for (const peer of this.peers) {
+      this._replicateToPeer(peer, effects, false);
+    }
+  }
+
+  _becomeFollower(term, leaderId, effects) {
+    const prevRole = this.role;
+    this.role = Role.FOLLOWER;
+    this.currentTerm = BigInt(term);
+    this.votedFor = null;
+    this.leaderId = leaderId;
+    this.transferTarget = null;
+
+    this.storage.setHardState({
+      currentTerm: this.currentTerm,
+      votedFor: null
+    });
+
+    effects.push({
+      type: EffectType.PERSIST_HARD_STATE,
+      currentTerm: this.currentTerm,
+      votedFor: null
+    });
+
+    effects.push({
+      type: EffectType.BECOME_FOLLOWER,
+      term: this.currentTerm,
+      leaderId
+    });
+
+    effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+  }
+
+  _handleHeartbeat(msg, effects) {
+    if (BigInt(msg.term) < this.currentTerm) {
+      return;
+    }
+
+    this.leaderId = msg.leaderId;
+    effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+
+    // Advance commit index if leaderCommit > commitIndex
+    const leaderCommit = BigInt(msg.leaderCommit);
+    if (leaderCommit > this.commitIndex) {
+      const lastIndex = this.storage.lastIndex();
+      this.commitIndex = leaderCommit < lastIndex ? leaderCommit : lastIndex;
+      this._advanceApplied(effects);
+    }
+  }
+
+  _handleAppendRequest(msg, effects) {
+    const msgTerm = BigInt(msg.term);
+
+    if (msgTerm < this.currentTerm) {
+      effects.push({
+        type: EffectType.SEND,
+        to: msg.leaderId,
+        message: {
+          type: MessageType.APPEND_RESPONSE,
+          term: this.currentTerm,
+          sourceNode: this.id,
+          destNode: msg.leaderId,
+          followerId: this.id,
+          success: false,
+          matchIndex: 0n,
+          lastLogIndex: this.storage.lastIndex()
+        }
+      });
+      return;
+    }
+
+    this.leaderId = msg.leaderId;
+    effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+
+    const prevLogIndex = BigInt(msg.prevLogIndex);
+    const prevLogTerm = BigInt(msg.prevLogTerm);
+
+    // Verify log matching property at prevLogIndex
+    if (prevLogIndex > 0n) {
+      if (prevLogIndex > this.storage.lastIndex()) {
+        // Missing entry
+        effects.push({
+          type: EffectType.SEND,
+          to: msg.leaderId,
+          message: {
+            type: MessageType.APPEND_RESPONSE,
+            term: this.currentTerm,
+            sourceNode: this.id,
+            destNode: msg.leaderId,
+            followerId: this.id,
+            success: false,
+            matchIndex: 0n,
+            lastLogIndex: this.storage.lastIndex()
+          }
+        });
+        return;
+      }
+
+      const termAtPrev = this.storage.term(prevLogIndex);
+      if (termAtPrev === null || termAtPrev !== prevLogTerm) {
+        // Conflict at prevLogIndex: truncate from here
+        if (prevLogIndex >= this.storage.firstIndex()) {
+          this.storage.truncateFrom(prevLogIndex);
+        }
+        effects.push({
+          type: EffectType.SEND,
+          to: msg.leaderId,
+          message: {
+            type: MessageType.APPEND_RESPONSE,
+            term: this.currentTerm,
+            sourceNode: this.id,
+            destNode: msg.leaderId,
+            followerId: this.id,
+            success: false,
+            matchIndex: 0n,
+            lastLogIndex: this.storage.lastIndex()
+          }
+        });
+        return;
+      }
+    }
+
+    // Append entries, handling any conflicts
+    const entries = msg.entries || [];
+    const entriesToPersist = [];
+
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      const entryIndex = BigInt(entry.index);
+      const entryTerm = BigInt(entry.term);
+
+      if (entryIndex <= this.storage.lastIndex()) {
+        const existingTerm = this.storage.term(entryIndex);
+        if (existingTerm !== entryTerm) {
+          // Truncate conflict
+          this.storage.truncateFrom(entryIndex);
+          this.storage.append(entry);
+          entriesToPersist.push(entry);
+        }
+      } else {
+        this.storage.append(entry);
+        entriesToPersist.push(entry);
+      }
+    }
+
+    if (entriesToPersist.length > 0) {
+      effects.push({
+        type: EffectType.PERSIST_ENTRIES,
+        entries: entriesToPersist
+      });
+    }
+
+    // Update commit index
+    const leaderCommit = BigInt(msg.leaderCommit);
+    if (leaderCommit > this.commitIndex) {
+      const lastIndex = this.storage.lastIndex();
+      this.commitIndex = leaderCommit < lastIndex ? leaderCommit : lastIndex;
+      this._advanceApplied(effects);
+    }
+
+    effects.push({
+      type: EffectType.SEND,
+      to: msg.leaderId,
+      message: {
+        type: MessageType.APPEND_RESPONSE,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: msg.leaderId,
+        followerId: this.id,
+        success: true,
+        matchIndex: this.storage.lastIndex(),
+        lastLogIndex: this.storage.lastIndex()
+      }
+    });
+  }
+
+  _handleAppendResponse(msg, effects) {
+    if (this.role !== Role.LEADER || BigInt(msg.term) !== this.currentTerm) {
+      return;
+    }
+
+    const peer = msg.followerId;
+    const curInflightBatches = this.inflightBatches.get(peer) || 0;
+    if (curInflightBatches > 0) {
+      this.inflightBatches.set(peer, curInflightBatches - 1);
+    }
+
+    if (msg.success) {
+      const match = BigInt(msg.matchIndex);
+      this.matchIndex.set(peer, match);
+      this.nextIndex.set(peer, match + 1n);
+
+      // Check if leadership transfer target has caught up
+      if (this.transferTarget === peer && match >= this.storage.lastIndex()) {
+        effects.push({
+          type: EffectType.SEND,
+          to: peer,
+          message: {
+            type: MessageType.TIMEOUT_NOW,
+            term: this.currentTerm,
+            sourceNode: this.id,
+            destNode: peer,
+            leaderId: this.id
+          }
+        });
+        this.transferTarget = null;
+      }
+
+      // Check if commitIndex can advance
+      this._maybeAdvanceCommitIndex(effects);
+
+      // Continue replication if follower is still behind
+      if (this.nextIndex.get(peer) <= this.storage.lastIndex()) {
+        this._replicateToPeer(peer, effects, false);
+      }
+    } else {
+      // Rejection: back up nextIndex
+      const curNext = this.nextIndex.get(peer) || (this.storage.lastIndex() + 1n);
+      const followerLast = BigInt(msg.lastLogIndex);
+
+      let newNext = curNext > 1n ? curNext - 1n : 1n;
+      if (followerLast < newNext) {
+        newNext = followerLast + 1n;
+      }
+      this.nextIndex.set(peer, newNext);
+
+      // Check if follower is behind compacted log -> snapshot required
+      if (newNext < this.storage.firstIndex()) {
+        this._sendSnapshotToPeer(peer, effects);
+      } else {
+        this._replicateToPeer(peer, effects, false);
+      }
+    }
+  }
+
+  _maybeAdvanceCommitIndex(effects) {
+    const matches = [this.storage.lastIndex()];
+    for (const peer of this.peers) {
+      matches.push(this.matchIndex.get(peer) || 0n);
+    }
+
+    // Sort descending
+    matches.sort((a, b) => (b > a ? 1 : b < a ? -1 : 0));
+
+    // Quorum match index is at index: quorumSize - 1
+    const N = matches[this.quorumSize() - 1];
+
+    if (N > this.commitIndex) {
+      // Raft safety rule: only commit entries from currentTerm by counting replicas
+      const termAtN = this.storage.term(N);
+      if (termAtN === this.currentTerm) {
+        const prevCommit = this.commitIndex;
+        this.commitIndex = N;
+        this._advanceApplied(effects);
+
+        for (let idx = prevCommit + 1n; idx <= N; idx++) {
+          effects.push({
+            type: EffectType.NOTIFY_COMMITTED,
+            index: idx
+          });
+        }
+      }
+    }
+  }
+
+  _advanceApplied(effects) {
+    while (this.lastApplied < this.commitIndex) {
+      this.lastApplied += 1n;
+      const entries = this.storage.entries(this.lastApplied, this.lastApplied);
+      if (entries.length > 0) {
+        effects.push({
+          type: EffectType.APPLY,
+          entry: entries[0]
+        });
+      }
+    }
+  }
+
+  _replicateToPeer(peer, effects, isHeartbeat = false) {
+    const next = this.nextIndex.get(peer) || (this.storage.lastIndex() + 1n);
+
+    // Check if behind snapshot
+    if (next < this.storage.firstIndex()) {
+      this._sendSnapshotToPeer(peer, effects);
+      return;
+    }
+
+    const inflight = this.inflightBatches.get(peer) || 0;
+    if (!isHeartbeat && inflight >= this.maxInflightBatches) {
+      // Inflight limit reached, wait for ACK
+      return;
+    }
+
+    const prevLogIndex = next - 1n;
+    const prevLogTerm = this.storage.term(prevLogIndex) || 0n;
+
+    const last = this.storage.lastIndex();
+    let entries = [];
+
+    if (next <= last) {
+      const maxTo = next + BigInt(this.maxBatchEntries) - 1n;
+      const to = maxTo < last ? maxTo : last;
+      entries = this.storage.entries(next, to, this.maxBatchBytes);
+    }
+
+    if (entries.length === 0 && !isHeartbeat) {
+      return; // Nothing new to replicate
+    }
+
+    this.inflightBatches.set(peer, inflight + 1);
+
+    effects.push({
+      type: EffectType.SEND,
+      to: peer,
+      message: {
+        type: MessageType.APPEND_REQUEST,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: peer,
+        leaderId: this.id,
+        prevLogIndex,
+        prevLogTerm,
+        leaderCommit: this.commitIndex,
+        entries
+      }
+    });
+  }
+
+  _sendSnapshotToPeer(peer, effects) {
+    const snap = this.storage.getSnapshot();
+    if (!snap) return;
+
+    effects.push({
+      type: EffectType.SEND,
+      to: peer,
+      message: {
+        type: MessageType.SNAPSHOT_BEGIN,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: peer,
+        leaderId: this.id,
+        snapshotIndex: snap.index,
+        snapshotTerm: snap.term,
+        totalBytes: BigInt(snap.data.byteLength)
+      }
+    });
+
+    effects.push({
+      type: EffectType.SEND,
+      to: peer,
+      message: {
+        type: MessageType.SNAPSHOT_CHUNK,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: peer,
+        snapshotIndex: snap.index,
+        offset: 0n,
+        chunkData: snap.data
+      }
+    });
+
+    effects.push({
+      type: EffectType.SEND,
+      to: peer,
+      message: {
+        type: MessageType.SNAPSHOT_END,
+        term: this.currentTerm,
+        sourceNode: this.id,
+        destNode: peer,
+        snapshotIndex: snap.index,
+        totalChecksum: 0
+      }
+    });
+  }
+
+  _handleSnapshotMessage(msg, effects) {
+    if (BigInt(msg.term) < this.currentTerm) {
+      return;
+    }
+
+    this.leaderId = msg.leaderId;
+    effects.push({ type: EffectType.RESET_ELECTION_TIMER });
+
+    if (msg.type === MessageType.SNAPSHOT_CHUNK) {
+      this._pendingSnapshot = {
+        index: BigInt(msg.snapshotIndex),
+        term: BigInt(msg.term),
+        data: msg.chunkData
+      };
+    } else if (msg.type === MessageType.SNAPSHOT_END) {
+      if (this._pendingSnapshot) {
+        this.storage.saveSnapshot(this._pendingSnapshot);
+        if (this._pendingSnapshot.index > this.commitIndex) {
+          this.commitIndex = this._pendingSnapshot.index;
+          this.lastApplied = this._pendingSnapshot.index;
+        }
+
+        effects.push({
+          type: EffectType.SEND,
+          to: msg.sourceNode,
+          message: {
+            type: MessageType.SNAPSHOT_RESPONSE,
+            term: this.currentTerm,
+            sourceNode: this.id,
+            destNode: msg.sourceNode,
+            followerId: this.id,
+            success: true,
+            lastIndex: this.storage.lastIndex()
+          }
+        });
+        this._pendingSnapshot = null;
+      }
+    }
+  }
+
+  _handleSnapshotResponse(msg, effects) {
+    if (this.role !== Role.LEADER || BigInt(msg.term) !== this.currentTerm) {
+      return;
+    }
+
+    if (msg.success) {
+      const match = BigInt(msg.lastIndex);
+      this.matchIndex.set(msg.followerId, match);
+      this.nextIndex.set(msg.followerId, match + 1n);
+      this._replicateToPeer(msg.followerId, effects, false);
+    }
+  }
+}