refactor(pkg/finality-grandpa): make closing globalIn the voter's shutdown signal

[timwu20]

Changes

The voter's lifecycle was split across two owners with overlapping duties: Stop both signalled shutdown and tore the voter down, while the caller separately owned globalIn. Stop left the forwarder reading a channel it did not own; closing globalIn released nothing the voter owned. Start separately opened a window between constructing a voter and running one, in which a shutdown could race a startup.

The voter is now three things:

NewVoter(...) *Voter             // constructs, runs, and owns its own teardown
(*Voter) Done() <-chan error     // why it stopped, once it has finished
(*Voter) VoterState() VoterState[ID]

Close globalIn to shut it down:

select {
case err := <-voter.Done():   // nil == you closed globalIn; otherwise it failed
case cmd := <-commands:
}

• Closing globalIn is the only shutdown signal. The poll loop has no early exit, so it leaves only by observing the close — which means first draining whatever the forwarder is holding on the unbuffered out. A retired voter's forwarder can no longer outlive it: across 10 rotations with traffic in flight, 10 leaked before, 0 now.
• NewVoter runs the voter, so there is no half-live state and nothing to schedule.
• The voter tears itself down before publishing on Done, so a receive there means it has released its finalization channel and every round timer. Callers have no teardown obligation.
• The error goes to a single receiver and the channel closes behind it. A voter has one owner; if others need the outcome, that owner fans it out.

globalIn belongs to the caller, who must be its only writer by the time it closes, or must serialise its writers against the close.

A running voter no longer accumulates goroutines

Separately from shutdown, the voter leaked four goroutines per round, released only when the process ended. Over 8 rounds the forwarder count grew by 32.

Three of the four were timers. A timer wrapped an unbuffered channel in a wakerChan purely to deliver a wake, but nothing anywhere reads a timer's out — consumers use SetWaker and Elapsed, and Elapsed reads an atomic. So every timer that fired stranded its forwarder on a send with no receiver that would ever exist, and Close could not reach it, because closing an input never releases a goroutine blocked on a send. The wakerChan is gone: the timer holds its waker directly and wakes it from the goroutine already watching the deadline, and Close ends that goroutine when a round finishes before its timer fires. Setting expired before waking also fixes a race where a poller could observe the timer as pending and go back to sleep.

The fourth was roundData.Incoming, which belongs to the environment. Its forwarder ends only when that channel closes, so a round input left open outlives its round. Environment.RoundData now documents that implementations close it once the round concludes and release any still open at shutdown; the test environment does so from Concluded. RoundData is reachable more than once for a round number, so each call's channel is tracked rather than one per round.

TestVoter_RoundsDoNotAccumulateForwarders pins this: +0 over 8 rounds, against +32 without the fixes.

Closed channels at the other wakerChan consumers

An unchecked <-ch on a closed channel stays permanently ready and hands out zero values, so the default arm that would break the loop is unreachable. Three sites:

site	before
pruneBackgroundRounds	spins while holding v.inner, which also blocks VoterState
votingRound.processIncoming	dereferences a nil Message interface — panic
finishPrevoting	reads a closed channel as "no best chain", parking the round in prevoting forever

past_rounds.go already handled this and is unchanged: a background round's commit channel closes when the round concludes, which the live poll loop is expected to see, so breaking out is right there.

Incidental

• Fixes a race in waker.wake, which read w.wakeCh inside the spawned goroutine after releasing the lock, racing register's write.
• wakerChan.start wakes its consumer on exit, so a shutdown reaches the poll loop rather than waiting on an unrelated source.
• The test network gains per-node teardown. route snapshotted senders under the lock but delivered outside it, so closing one node's channel could race a send.
• Tests build globalIn before NewVoter and pass it in, rather than overwriting voter.globalIn afterwards.

Known gaps outside the package

The gossamer callers under internal/client/consensus/grandpa are not brought up to the new contract here. Listed for the record rather than as pending work:

• voterWork never closes globalIn, so a retired voter's forwarder is not released, and the err == nil guard in poll would read an orderly shutdown as ErrSafety once it does.
• environment.RoundData does not close round inputs, so it does not meet the obligation now documented on the interface.
• communication.go's combinedIncoming forwarder continues past its own break check, so the break is dead code and the goroutine spins once its input closes.
• Test_networkBridge races on development today, unrelated to this change.