refactor(node/sync): tidy block cache and fix internal-node eviction

[tcoratger]

Summary

Clarity, modern-Python, and one correctness fix in BlockCache (src/lean_spec/node/sync/block_cache.py). All sync tests pass.

Documentation

• Trim the banner-essay module docstring ("Why Cache Blocks? / How It Works / Memory Safety"), the PendingBlock class + five multi-line field docstrings, and the verbose method Args/Returns blocks to the project rules. Keep the genuine rationale (why >= in the capacity check, why empty parent-sets are deleted, the slot-order example, FIFO attack-resistance).

Structure

• Inline _evict_oldest into add (single caller) and drop unmark_orphan (no external callers; its only caller was remove, so its one-line discard is now inline). Deleted its two now-redundant direct tests (the behavior stays covered by the remove-clears-orphan test).
• Keep mark_orphan: it has callers in head_sync and backfill_sync plus internal use, and guards the orphan set against phantom entries — inlining would duplicate the guard and break the cache's encapsulation.
• PendingBlock is now frozen=True — nothing mutates it, matching the frozen-by-default convention.
• On stdlib: no itertools.batched fit here (no chunking), and OrderedDict stays (FIFO eviction needs popitem(last=False)).

Eviction correctness fix

Evicting an internal node (a cached block that is itself a parent of other cached blocks) left its children stranded: they stayed cached, were no longer linked to a present parent, and were never re-marked as orphans — so backfill never refetched the parent and orphan_count under-reported. Since service.py gates sync-completion on orphan_count, the node could flip to synced with stuck blocks. Eviction now re-marks the evicted block's still-cached children as orphans (keeping the parent-index link so they reconnect if the parent returns), with a regression test (test_eviction_remarks_orphaned_children).

Deferred (noted): the dedup-keeps-deeper-backfill_depth nit, and gating sync-completion on more than orphan_count — both lower-severity, separate concerns.

Testing

• just check passes (ruff, format, ty, codespell, mdformat).
• uv run pytest tests/node/sync — 141 pass.

🤖 Generated with Claude Code