kuilt-raft/us.tractat.kuilt.raft/RaftTraceEvent

RaftTraceEvent

One engine state transition, emitted on RaftNode.trace.

The event vocabulary follows the etcd TLA+ action names so traces can be replayed through the Vanlightly standard-raft TLA+ spec for TLC validation.

FrameRefused and FrameUndecodable are the two variants that are deliberately not state transitions — each reports a frame the engine dropped, i.e. a transition that did not happen, and neither has a TLA+ action to correspond to. Filter both out before a spec replay.

Inheritors

Types

AdvanceCommitIndex

data class AdvanceCommitIndex(val clock: Long, val node: NodeId, val oldCommitIndex: Long, val newCommitIndex: Long) : RaftTraceEvent

commitIndex advanced.

AppendEntries

data class AppendEntries(val clock: Long, val from: NodeId, val to: NodeId, val term: Long, val prevLogIndex: Long, val prevLogTerm: Long, val entryCount: Int, val leaderCommit: Long) : RaftTraceEvent

AppendEntries RPC sent (including heartbeats — entryCount=0).

AppendEntriesAccepted

data class AppendEntriesAccepted(val clock: Long, val from: NodeId, val to: NodeId, val matchIndex: Long) : RaftTraceEvent

AppendEntries accepted by follower.

AppendEntriesRejected

data class AppendEntriesRejected(val clock: Long, val from: NodeId, val to: NodeId, val conflictIndex: Long?, val conflictTerm: Long?) : RaftTraceEvent

AppendEntries rejected by follower.

BecomeFollower

data class BecomeFollower(val clock: Long, val node: NodeId, val term: Long, val reason: StepDownReason) : RaftTraceEvent

Node stepped down to follower.

BecomeLeader

data class BecomeLeader(val clock: Long, val node: NodeId, val term: Long) : RaftTraceEvent

Node became leader.

ClientRequest

data class ClientRequest(val clock: Long, val node: NodeId, val index: Long, val term: Long) : RaftTraceEvent

A client proposal was appended to the leader's log.

Compacted

data class Compacted(val clock: Long, val node: NodeId, val throughIndex: Long, val throughTerm: Long) : RaftTraceEvent

Log prefix discarded after a compaction.

ConfigChange

data class ConfigChange(val clock: Long, val node: NodeId, val index: Long, val old: ClusterConfig?, val new: ClusterConfig) : RaftTraceEvent

A config entry was appended to the log (adopted on append, per §6). Emitted by both the leader (on RaftNode.changeMembership) and followers (on receiving the AppendEntries carrying the config entry). This is the primary assertion point for membership-change tests — config and term are private engine state, so tests observe transitions through this event.

FrameRefused

data class FrameRefused(val clock: Long, val node: NodeId, val from: NodeId, val messageType: RaftMessageType, val gate: RefusalGate) : RaftTraceEvent

A frame from a peer was refused by gate — the one variant that reports something the engine did not do.

FrameUndecodable

data class FrameUndecodable(val clock: Long, val node: NodeId, val from: NodeId, val byteCount: Int) : RaftTraceEvent

A frame from a peer could not be decoded, and was dropped (#2051).

InstallSnapshot

data class InstallSnapshot(val clock: Long, val from: NodeId, val to: NodeId, val lastIncludedIndex: Long, val offset: Long, val done: Boolean) : RaftTraceEvent

§7 InstallSnapshot chunk sent to a follower whose needed prefix has been compacted away.

InstallSnapshotAccepted

data class InstallSnapshotAccepted(val clock: Long, val from: NodeId, val to: NodeId, val lastIncludedIndex: Long) : RaftTraceEvent

A follower finished reassembling and installed a snapshot.

LeadershipTransferAbandoned

data class LeadershipTransferAbandoned(val clock: Long, val leader: NodeId, val target: NodeId, val reason: LeadershipTransferAbandonReason) : RaftTraceEvent

A leadership transfer was abandoned — either because the auto-timeout expired before the target won an election, or because RaftNode.cancelTransfer was called explicitly. reason describes which path fired. Normal proposal acceptance is resumed.

LeadershipTransferStarted

data class LeadershipTransferStarted(val clock: Long, val leader: NodeId, val target: NodeId) : RaftTraceEvent

The leader started a leadership transfer to target. Proposals are blocked until the transfer completes or is abandoned.

PreVoteDenied

data class PreVoteDenied(val clock: Long, val node: NodeId, val to: NodeId, val proposedTerm: Long, val reasons: Set<DenyReason>) : RaftTraceEvent

Node denied a pre-vote to a candidate.

PreVoteGranted

data class PreVoteGranted(val clock: Long, val node: NodeId, val to: NodeId, val proposedTerm: Long) : RaftTraceEvent

Node granted a pre-vote to a candidate.

PreVoteStarted

data class PreVoteStarted(val clock: Long, val node: NodeId, val proposedTerm: Long) : RaftTraceEvent

Pre-vote phase started: candidate broadcasts hypothetical-term requests.

ReadIndexConfirmed

data class ReadIndexConfirmed(val clock: Long, val readIndex: Long, val term: Long) : RaftTraceEvent

The leader confirmed quorum freshness for a linearizable read at readIndex in term. No log entry is written for the read. Emitted once per pending read as it resolves.

RequestVote

data class RequestVote(val clock: Long, val from: NodeId, val to: NodeId, val term: Long, val lastLogIndex: Long, val lastLogTerm: Long) : RaftTraceEvent

RequestVote RPC sent.

Timeout

data class Timeout(val clock: Long, val node: NodeId, val newTerm: Long) : RaftTraceEvent

Election timeout fired; node becomes candidate.

VoteDenied

data class VoteDenied(val clock: Long, val from: NodeId, val to: NodeId, val term: Long, val reasons: Set<DenyReason>) : RaftTraceEvent

Vote denied to a candidate.

VoteGranted

data class VoteGranted(val clock: Long, val from: NodeId, val to: NodeId, val term: Long) : RaftTraceEvent

Vote granted to a candidate.

Properties

clock

abstract val clock: Long

Logical monotonic clock — incremented on every emitted event.