RefusalGate

Which guard refused an inbound frame — the gate of RaftTraceEvent.FrameRefused.

Every guard named here refuses by returning, so without this its only observable is the absence of a state change. An absence carries no attribution: as soon as two guards refuse the same frame, a test asserting "term unchanged, still a Follower" cannot say which one did it, and the upstream guard's coverage silently drops to zero. That is measured, not hypothetical — a mutation survey (#1980) found four of RaftEngine.onTimeoutNow's five guards deletable with the whole module green, and found that adding one state-effect test per guard reproduces the defect rather than fixing it, because each new test is shadowed exactly as the old ones were. This enum is the attribution those tests had no way to make (#1989).

Closed on purpose

wedgeGate is an exhaustive when with no else, so a value added here cannot compile without deciding whether the wedge metric hears about it — the mechanism RaftMessage.wireTerm and RaftMessage.isLeaderToPeer already use to keep a new frame type from slipping silently past a gate (#1973). What no compiler can force is adding the value in the first place; the FrameRefusedTest suite's reachability test is the other half, and it fails on an entry no emit site produces.

What no type can close, and the slice that is closed anyway

The guard above runs in one direction only, and the next reader must not assume otherwise. FrameRefusedTest.everyRefusalGateIsReachable proves declared→emitted: every value below has a live emit site. The converse — emitted→declared, that every refusal of an inbound frame names a gate — is not compile-time enforceable in general (#2033). "This return refuses a frame" is a property of control flow, not of a type; Kotlin has no effect system, so nothing stops a new if (…) return in a handler body from dropping a frame silently, and no test that inspects only declared values can see it. Funnelling every refusal through RaftEngine.refuseFrame does not change that either — a funnel catches only what someone chooses to route into it.

What is enforced is the slice where the whole gap actually lived. Every factored validator on the inbound path returns RefusalGate? — null admits, non-null names the gate that refused — (RaftEngine.batchRefusal, snapshotChunkRefusal, committedTermFloorRefusal, adoptLeaderForTerm), so a refusing clause added to one of them cannot compile without naming a gate: return false has stopped being expressible there. Keep it that way — when a handler grows a new frame refusal, factor it into a validator of that shape rather than writing a bare return in the handler body.

Two alternatives were weighed and rejected. A sealed Disposition return on the eleven handlers converts a silent skip into a lying Processed — visible in a diff, still unenforced, and a large blast radius for that. A lexical detekt/Gradle scanner in the shape of forbidRunCatchingCancellableUnderNonCancellable would key on the debug { } log text rather than on control flow, so rewording a message evades it: a smell detector, not a proof.

Order

Grouped by where the engine evaluates them, and in evaluation order within each group. The two implausible-term arms and the §5.2/§8 leader-authority gate run at the dispatch boundary in RaftEngine.onMessage, before any handler. The five TimeoutNow* guards run inside RaftEngine.onTimeoutNow. The AppendEntries* and InstallSnapshot* guards run inside their own handlers, ahead of every side-effect those handlers have. ForgedLeaderForTerm is last because it is shared: both of those two handlers reach it, and both reach it after their own frame-shape bounds.