refactor(sync): readability sweep on service.py

[tcoratger]

Summary

A spec-readability pass on subspecs/sync/service.py. The sync service
is the central coordinator of the node — a reader trying to understand
how blocks, attestations, and state transitions flow through the
system reaches this file early. The current version had layers of
wrappers and prose-heavy comments that made the file harder to follow
than it needed to be.

Net: -177 lines across 4 files, zero behavior change, all 1547
tests in sync/chain/networking/node pass.

Three kinds of change

1. Docstring rewrites (style + structure)

• Module header: drops the "Core Problem" preamble, the RST-style
  section headers, and the bold-markdown state list. Keeps a tight
  state-machine diagram and three one-line state descriptions.
• SyncService class: drops the marketing-tone "Design
  Philosophy" block ("Reactive / Simple / Resilient / Observable")
  and the bullet list of responsibilities that restated what methods
  do.
• Per-method: replaces narrative prose with educative line-by-line
  comments following the bitfields.py reference style — one
  sentence per line, no backticks, no marketing tone.

2. Removed abstractions (single-call-site wrappers)

Removed	Replaced with
Module-level _ancestor_set helper	Nested closure inside its only caller (_default_process_block), captures the block map
_check_sync_trigger method	Inlined into on_peer_status (single caller). Two redundant SYNCING-transition branches collapsed into one or-clause
_publish_agg_fn field + set_publish_agg_fn setter + publish_aggregated_attestation wrapper method	Single public Callable field
_state field + state @Property	Single public state field

Each follows the same architectural principle: a wrapper that adds
no behavior is pure indirection tax. The underscore-private +
public-accessor pattern carries weight only when the accessor enforces
something. When it does not, the consenting-adults Python idiom is
cleaner.

3. Worked examples added for non-trivial logic

• Reorg depth in _default_process_block: an ASCII chain diagram
  showing how ancestors(old_head) - ancestors(new_head) equals
  exactly the abandoned blocks. Common ancestor cancels both sides;
  the difference is the reorg depth.
• _persist_block: labeled rationale for each batch write, the
  finalize-then-prune invariant, why the finalized root is retained
  as the on-disk anchor, and why the slot > 0 guard exists.
• ancestors closure: a worked trace showing
  walk(B) -> {B, A, G} for a 3-block chain with genesis.
• State-root reverse index: a four-step checkpoint-sync example
  explaining why state-to-block lookup is needed (operator hands a
  trusted state root S, node downloads the state, looks up S in
  this index to find anchor block B, forkchoice resumes from B).
• _replay_pending_attestations: the swap-and-replay pattern
  documented with an A/B example. A succeeds because its target
  block just landed; B fails and re-appends; post-loop queue is
  exactly [B].

Files touched

• src/lean_spec/subspecs/sync/service.py — primary file. -324 lines.
• src/lean_spec/subspecs/node/node.py — one-line wiring change from
  sync_service.set_publish_agg_fn(...) to direct field assignment.
• tests/lean_spec/subspecs/sync/test_service.py — test updates to
  reflect new public surface (service.state = instead of
  service._state =, service.publish_aggregated_attestation =
  instead of service.set_publish_agg_fn(...)).
• tests/lean_spec/subspecs/networking/test_network_service.py —
  sync_service._state = ... → sync_service.state = ....

Test plan

• ruff check, ruff format --check, ty check all pass
• pytest tests/lean_spec/subspecs/sync tests/lean_spec/subspecs/chain tests/lean_spec/subspecs/networking tests/lean_spec/subspecs/node -> 1547 passed
• All four wiring/test call-sites verified (no remaining
  _publish_agg_fn, set_publish_agg_fn, or external ._state
  references)

🤖 Generated with Claude Code