sort queued items before dispatching in light mode for non-zero confirmation

[Chengxuan]

Summary

In light chain tracking mode with confirmationsRequired > 0, events dispatched from the confirmation manager weren't guaranteed to be in block order. This could occasionally lead to a later-arriving event being treated by the event stream as a re-detection of an earlier one, so it wasn't forwarded. This path isn't used when confirmationsRequired = 0 or during catch-up.

Root cause

checkAndDispatchConfirmationsUsingBlockHeight builds its list of newly-confirmable items from bcm.pending, a Go map. Map iteration order isn't guaranteed, so when a head block update confirmed several pending events at once, they were dispatched in map order rather than block order.

Full chain tracking mode already handles this correctly in processBlock via sort.Sort(notifications) before dispatch. Light mode was missing the equivalent sort.

Fix

Sort pending items by block number, transaction index, and log index (using the existing pendingItems sort type) before dispatching in checkAndDispatchConfirmationsUsingBlockHeight, bringing it in line with full mode.

Testing

• Added TestBlockConfirmationManagerHeadBlockNumberDispatchesInBlockOrder, which confirms a batch of light-mode events together via one head block update and asserts dispatch order. It reproduced the ordering issue consistently before the fix and passes consistently after.
• go build ./..., go vet ./..., and the internal/confirmations suite all pass.
• The full go test ./... run has two unrelated pre-existing failures in persistence/dbmigration and persistence/postgres (a golang-migrate panic in this environment), present on main before this change too.

🤖 Generated with Claude Code

[peterbroadhurst]

Cool the ordering is here:

transaction-manager/internal/confirmations/confirmations.go

Lines 213 to 225 in 5915cbc

	type pendingItems []*pendingItem
	func (pi pendingItems) Len() int { return len(pi) }
	func (pi pendingItems) Swap(i, j int) { pi[i], pi[j] = pi[j], pi[i] }
	func (pi pendingItems) Less(i, j int) bool {
	// At the point we emit the confirmations, we ensure to sort them by:
	// - Block number
	// - Transaction index within the block
	// - Log index within the transaction (only for events)
	return pi[i].blockNumber < pi[j].blockNumber ||
	(pi[i].blockNumber == pi[j].blockNumber && (pi[i].transactionIndex < pi[j].transactionIndex ||
	(pi[i].transactionIndex == pi[j].transactionIndex && pi[i].logIndex < pi[j].logIndex)))
	}