refactor(head-sync): flatten descendant processing into an iterative drain

[tcoratger]

Summary

Rework the gossip head follower so the cached-descendant cascade is a single iterative loop instead of mutual recursion through three methods. The behavior is preserved; the structure, return shape, and docs are simplified.

Changes

• Store | None return. on_gossip_block returns the updated store when a block is integrated, or None when it is cached pending an unknown parent. This deletes the single-bool HeadSyncResult wrapper and the repeated two-channel (result, store) returns.
• Iterative drain. The recursion (_process_block_with_descendants + _process_cached_descendants) becomes one deque[Bytes32] worklist. A long backfilled chain can no longer exhaust the stack. The gossiped block is processed explicitly, so its failure is a direct early return; the loop then drains only cached descendants (each already carries its root and slot).
• Reentrancy set removed. The processed path is now fully synchronous — no awaits — so a concurrent entry for the same root cannot interleave. The already-in-store check is the sufficient guard. This also makes the sync service's write-back comment describe a true invariant rather than a fragile one.
• Inlined the single-use cache-and-backfill helper into its only caller.
• Hash once. Reuse the gossiped block root and the cached child roots instead of recomputing hash_tree_root per method.
• Docs trimmed to the project's terseness bar (module, class, fields, inline comments), keeping the genuinely non-obvious rationale (finalized-slot floor, backfill routing dichotomy).

Net: head_sync.py drops from 379 to ~118 lines — one public method, no helpers, no result wrapper, no recursion, no reentrancy set.

Out of scope (flagged for a follow-up)

Review surfaced a liveness question: backfill caches a fetched parent but nothing re-drives the cascade unless that parent is later re-gossiped. Closing it is a behavioral change (backfill → head-sync notification) that needs confirmation of the intended sync state machine, so it is not bundled here.

Testing

• just check passes.
• tests/node/sync/test_head_sync.py and test_service.py pass. Assertions now check the store contract directly (is None / is not None); the reentrancy-guard test is removed with the set it exercised.

🤖 Generated with Claude Code