refactor(node/storage): tighten docs and fix two pruning defects

[tcoratger]

Summary

Clarity/documentation pass over src/lean_spec/node/storage/, plus two real pruning correctness fixes surfaced during review. The storage module is otherwise well-built — the get/put boilerplate, checkpoint accessors, and connection model are left as-is (refactoring them would trade readability for indirection and the rollback tests pin the current transaction model).

Documentation

• Trim verbose docstrings and consensus-tutorial comments across all five files to the project rules. Kept the load-bearing rationale only: head is a raw root (not SSZ), genesis time is little-endian, the empty-keep-set branch, and blocks/states sharing columns.
• Fix three doc inaccuracies in the SQLite backend:
  • It referenced a commit() method that does not exist — durability is exclusively via the batch-write block, and a lone write outside it is rolled back on close. The docstring invited silent data loss.
  • It claimed thread-safety the shared-connection-with-buffered-writes design does not provide (it is single-writer / event-loop-only; the API server never touches the DB).
  • It listed "attestations indexed by validator" storage that does not exist.

Pruning correctness

• Prune the state-root index. prune_before_slot never cleaned state_root_index, leaking rows indefinitely and leaving get_block_root_by_state_root able to resolve to a block that was already pruned. Now drops index entries whose block is no longer present.
• Honor the keep set in the slot-index delete. Blocks and states preserved roots in the keep set, but the slot index was deleted unconditionally by slot — so a preserved finalized block below the prune slot kept its block row but lost its slot mapping. Now consistent across all three tables.
• Added two tests covering the orphan-removal and kept-root cases. Existing prune count assertions are unaffected.

Testing

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

🤖 Generated with Claude Code