docs(claude-md): collapse storage docs into a pointer to data_storage.md

CLAUDE.md had grown a near-duplicate of docs/data_storage.md once the
BlockRoots/table-count fixes landed on this branch. Collapse the three
storage sections under Common Gotchas into a short paragraph plus a few
must-not-forget bullets, following the pattern already used for the HTTP
Servers section.

Before deleting anything, verified each CLAUDE.md claim against source and
moved what data_storage.md was missing there instead: the BlockRoots table
(key encoding, per-table section, write-path and pruning-list entries), the
constant-at-runtime facts for Metadata["config"] and the genesis validator
registry, and a stronger statement of the StateDiff config/validators
invariant naming validate_history_append.

Also fixes two inaccuracies found during verification: BlockRoots backs
get_signed_blocks_by_slot_range (BlocksByRange serving), not the RPC
by-slot endpoint, which resolves through historical_block_hashes instead;
and ChainConfig has no validator_count field, only genesis_time.

Author: MegaRedHand

CLAUDE.md

@@ -350,60 +350,24 @@ incremental, and line-tables-only debuginfo, so rebuilds are much faster than
 - Signature spec tests use `on_block()` which always verifies
 - Crypto tests marked `#[ignore]` (slow leanVM operations)
 
-### Storage Architecture
-- Blocks are split into three tables: `BlockHeaders`, `BlockBodies`, `BlockSignatures`
-- Genesis/anchor blocks have empty bodies (detected via `EMPTY_BODY_ROOT`) — no entry in `BlockBodies`
-- Genesis block has no signatures — no entry in `BlockSignatures`
-- Non-genesis blocks have a `BlockSignatures` entry until finalized: once below the
-  finalized boundary, signatures are pruned (`prune_old_block_signatures`) while
-  headers and bodies are kept forever. `get_signed_block` returns `None` for a
-  pruned finalized block
-- States are stored as parent-linked diffs (`StateDiffs`, never pruned) plus
-  full-state snapshots (`States`) written only every `SNAPSHOT_ANCHOR_INTERVAL`
-  slots (and the bootstrap). Neither is ever pruned. `get_state` returns an anchor
-  snapshot or reconstructs by walking diffs back to the nearest anchor; results are
-  memoized in an in-memory LRU (`STATE_CACHE_CAPACITY`) so recent reads stay hot
-- `StateDiff` omits `config` and `validators` entirely and takes them from the
-  nearest ancestor snapshot: an STF that ever mutated either would silently corrupt
-  every reconstructed state. `historical_block_hashes` is likewise not stored but
-  regenerated from `base_root` plus the slot gap, guarded by `validate_history_append`
-- `LiveChain` table provides fast `(slot||root) → parent_root` index for fork choice
-- `BlockRoots` is the canonical `slot → root` index, rewritten on every head update:
-  `block_root_index_changes` walks both branches to their common ancestor, so a reorg
-  deletes the slots leaving the canonical chain and writes the ones joining it
-- Storage uses trait-based API: `StorageBackend` → `StorageReadView` (reads) + `StorageWriteBatch` (atomic writes)
-
-### Storage Tables (8)
-
-These are the variants of the `Table` enum (`crates/storage/src/api/tables.rs`).
-
-| Table | Key → Value | Purpose |
-|-------|-------------|---------|
-| `BlockHeaders` | H256 → BlockHeader | Block headers by root |
-| `BlockBodies` | H256 → BlockBody | Block bodies (empty for genesis) |
-| `BlockSignatures` | (slot\|\|root) → BlockSignatures | Type-2 proof blob; keyed slot\|\|root so pruning scans in slot order and stops early; absent for genesis, pruned below finalized |
-| `BlockRoots` | slot → H256 | Canonical block root per slot; rewritten on reorg, never pruned. Backs `get_block_by_slot` and BlocksByRange serving |
-| `States` | H256 → State | Full-state snapshots; bootstrap + `SNAPSHOT_ANCHOR_INTERVAL` anchors only; never pruned |
-| `StateDiffs` | H256 → StateDiff | Parent-linked state diff per non-genesis state; never pruned |
-| `Metadata` | string → various | Store state (time, config, head, safe target, checkpoints) |
-| `LiveChain` | (slot\|\|root) → parent\_root | Fast fork choice traversal index |
-
-Attestations and gossip signatures are **not** persisted tables; they live in
-in-memory `Store` buffers (`new_payloads`, `known_payloads`, `gossip_signatures`)
-and are consumed during the tick pipeline (promotion at intervals 0/4,
-aggregation at interval 2).
-
-### What Is Constant in the DB
-
-`Metadata["config"]` (a `ChainConfig`, currently just `genesis_time`) is written once
-at bootstrap and never rewritten: it has a getter but no setter. It doubles as the
-DB fingerprint, since `from_db_state` refuses to resume a DB whose persisted
-`genesis_time` disagrees with the config file.
-
-The genesis validator registry is constant too, but it lives inside each `States`
-snapshot rather than in its own table. Everything else moves: the remaining
-`Metadata` keys are mutated in place, `BlockRoots` is rewritten on reorg, and the
-block/state tables are write-once per entry with a growing key set.
+### Storage
+
+Blocks split across `BlockHeaders`/`BlockBodies`/`BlockSignatures`; states are
+snapshot (`States`) + diff (`StateDiffs`) pairs; `BlockRoots` and `LiveChain`
+index by slot for range serving and fork choice. Attestations and gossip
+signatures are not persisted; they live in in-memory `Store` buffers consumed
+during the tick pipeline. See [`docs/data_storage.md`](docs/data_storage.md)
+for the full reference: what each of the eight tables holds and how it's
+keyed, the snapshot/diff reconstruction algorithm, the block-import write
+sequence, pruning rules, what never changes at runtime, and startup/restore
+behavior.
+
+- `BlockSignatures` is the only pruned block table (below the finalized
+  boundary); `get_signed_block` returns `None` for a pruned finalized block.
+- A `StateDiff` omits `config` and `validators`, trusting they never mutate;
+  breaking that invariant would silently corrupt every reconstructed state.
+- `Metadata["config"]` is written once at bootstrap and never rewritten; it
+  doubles as the DB's genesis-time fingerprint on resume.
 
 ### State Root Computation
 - Always computed via `hash_tree_root()` after full state transition

docs/data_storage.md

@@ -2,7 +2,7 @@
 
 This doc explains how ethlambda saves data. Especially,
 the split between the fork choice `Store` and the `StorageBackend` trait,
-what each of the seven tables holds, and which data is in-memory only.
+what each of the eight tables holds, and which data is in-memory only.
 
 ## Overview
 
@@ -98,14 +98,14 @@ is built from it, and clones are handed to the BlockChain and P2P actors.
    │   │ BlockHeaders        │         │ new_payloads         │    │
    │   │ BlockBodies         │         │  (pending aggregated │    │
    │   │ BlockSignatures     │         │   attestations)      │    │
-   │   │ States              │         │ known_payloads       │    │
-   │   │ StateDiffs          │         │  (fork-choice-active │    │
-   │   │ Metadata            │         │   attestations)      │    │
-   │   │ LiveChain           │         │ gossip_signatures    │    │
-   │   └─────────────────────┘         │  (raw XMSS sigs      │    │
-   │                                   │   awaiting           │    │
-   │   Survives restarts.              │   aggregation)       │    │
-   │                                   │ state_cache (LRU)    │    │
+   │   │ BlockRoots          │         │ known_payloads       │    │
+   │   │ States              │         │  (fork-choice-active │    │
+   │   │ StateDiffs          │         │   attestations)      │    │
+   │   │ Metadata            │         │ gossip_signatures    │    │
+   │   │ LiveChain           │         │  (raw XMSS sigs      │    │
+   │   └─────────────────────┘         │   awaiting           │    │
+   │                                   │   aggregation)       │    │
+   │   Survives restarts.              │ state_cache (LRU)    │    │
    │                                   └──────────────────────┘    │
    │                                                               │
    │                                   Lost on restart.            │
@@ -114,21 +114,22 @@ is built from it, and clones are handed to the BlockChain and P2P actors.
 
 ## The Tables
 
-The seven variants of the `Table` enum (`crates/storage/src/api/tables.rs`):
+The eight variants of the `Table` enum (`crates/storage/src/api/tables.rs`):
 
 | Table             | Key         | Value                                     | Pruned?                          |
 | ----------------- | ----------- | ----------------------------------------- | -------------------------------- |
 | `BlockHeaders`    | root        | `BlockHeader`                             | never                            |
 | `BlockBodies`     | root        | `BlockBody`                               | never                            |
 | `BlockSignatures` | slot ‖ root | aggregate proof (`MultiMessageAggregate`) | yes: finalized older than ~1 day |
+| `BlockRoots`      | slot        | block root (`H256`)                       | never                            |
 | `States`          | root        | full `State` snapshot                     | never                            |
 | `StateDiffs`      | root        | `StateDiff`                               | never                            |
 | `Metadata`        | string      | SSZ scalars                               | never                            |
 | `LiveChain`       | slot ‖ root | `parent_root`                             | yes: below finalized             |
 
 ### Key encoding
 
-Two key layouts are used:
+Three key layouts are used:
 
 - **Root-keyed** tables use the 32-byte SSZ encoding of the block root
   (`root.to_ssz()`).
@@ -137,6 +138,10 @@ Two key layouts are used:
   32-byte root. Big-endian means lexicographic key order equals numeric slot
   order, so pruning can iterate from the start of the table and stop at the
   first key past its cutoff instead of scanning everything.
+- **Slot-only** (`BlockRoots`) uses `encode_block_root_key`: just the 8-byte
+  big-endian slot, since the value already holds the root. This table is
+  never pruned, so the ordering buys nothing here; it is kept only for
+  consistency with the other slot-prefixed keys.
 
 ### BlockHeaders
 
@@ -168,12 +173,35 @@ rather than a fabricated block.
 
 This is the one block table that **is** pruned; see [Pruning](#pruning).
 
+### BlockRoots
+
+`slot → H256`, the canonical block root at each slot. Rewritten on every head
+update inside `update_checkpoints`: `block_root_index_changes` walks the old
+and new head's branches back to their common ancestor, deleting the slots
+that leave the canonical chain and writing the ones that join it. A reorg
+therefore touches only the affected slot range, not the whole table. Never
+pruned.
+
+Backs `get_signed_blocks_by_slot_range`, which serves BlocksByRange requests
+over req/resp (`crates/net/p2p/src/req_resp/handlers.rs`). It does **not**
+back the RPC `GET /lean/v0/blocks/:slot` endpoint: that handler resolves a
+slot through the head state's `historical_block_hashes` instead
+(`resolve_slot` in `crates/net/rpc/src/blocks.rs`), so a block on a side fork
+is reachable there only by root, never by slot.
+
 ### States
 
 `root → State` (full SSZ snapshot). Holds full-state snapshots **only**: the
 bootstrap anchor written at initialization, plus one anchor whenever a block
-crosses a 1024-slot boundary. Never pruned — these anchors are the base every
-diff chain resolves against, so reconstruction always terminates.
+crosses a `SNAPSHOT_ANCHOR_INTERVAL`-slot boundary. Never pruned — these
+anchors are the base every diff chain resolves against, so reconstruction
+always terminates.
+
+The genesis validator registry is constant for the life of the chain
+(`validators` is fixed at genesis; the lean STF never mutates it), but it has
+no table of its own: it rides inside every `States` snapshot alongside
+`config`, which `StateDiff` reconstruction relies on (see
+[State Storage](#state-storage-snapshots--diffs)).
 
 ### StateDiffs
 
@@ -190,12 +218,20 @@ fields:
 | Key                | Type          | Meaning                                                |
 | ------------------ | ------------- | ------------------------------------------------------ |
 | `time`             | `u64`         | Intervals elapsed since genesis (the store clock)      |
-| `config`           | `ChainConfig` | Chain configuration (genesis time, validator count)    |
+| `config`           | `ChainConfig` | Chain configuration (currently just `genesis_time`)    |
 | `head`             | `H256`        | Current fork choice head                               |
 | `safe_target`      | `H256`        | Current safe target (see [lmd_ghost.md](lmd_ghost.md)) |
 | `latest_justified` | `Checkpoint`  | Latest justified checkpoint                            |
 | `latest_finalized` | `Checkpoint`  | Latest finalized checkpoint                            |
 
+`config` is the odd one out: `init_store` writes it once at bootstrap and
+nothing ever rewrites it afterward (it has a getter, `Store::config`, but no
+setter). That also makes it the DB's fingerprint: `from_db_state` refuses to
+resume a data directory whose persisted `genesis_time` disagrees with the
+node's own config file, treating the mismatch as an empty DB (see
+[Startup and Restore](#startup-and-restore)). Every other `Metadata` key is
+mutated in place as the chain progresses.
+
 ### LiveChain
 
 `slot ‖ root → parent_root`. A pure **index** for fork choice: it lets
@@ -219,9 +255,9 @@ or change predictably. Instead, `insert_state` writes:
 1. **Always** a `StateDiff` keyed by the block root, linked to its parent via
    `base_root` (the block's `parent_root`).
 2. **Only at anchors** a full snapshot into `States`. A block is an anchor
-   when it crosses a `SNAPSHOT_ANCHOR_INTERVAL = 1024` slot boundary relative
+   when it crosses a `SNAPSHOT_ANCHOR_INTERVAL` slot boundary relative
    to its parent (~68 minutes at 4-second slots). This bounds any
-   reconstruction walk to at most 1024 diff applications.
+   reconstruction walk to at most `SNAPSHOT_ANCHOR_INTERVAL` diff applications.
 
 A `StateDiff` stores only what cannot be recovered elsewhere: the target slot,
 justified/finalized checkpoints, and the justification fields
@@ -235,6 +271,16 @@ small under healthy finality). The rest is deliberately omitted:
 | `latest_block_header`     | The `BlockHeaders` table                                                                                                                                      |
 | `historical_block_hashes` | Regenerated from `base_root` + the slot gap (the state transition appends the parent root plus one zero per skipped slot, so the append is fully predictable) |
 
+Omitting `config` and `validators` is a bet, not a fallback: a diff carries no
+copy of either, so if a future state transition ever mutated one, every state
+reconstructed past that point would silently pick up the ancestor snapshot's
+stale value instead. The `historical_block_hashes` append is checked rather
+than trusted blindly: `validate_history_append`
+(`crates/storage/src/state_diff.rs`) rejects a diff whose appended hashes
+don't match the expected slot gap or aren't zero-filled for skipped slots,
+so a broken append surfaces at diff-creation time instead of corrupting a
+later reconstruction.
+
 Reads go through `get_state`, which tries three levels:
 
 1. An in-memory LRU cache (`STATE_CACHE_CAPACITY = 32` states, keyed by block
@@ -298,6 +344,7 @@ sequence of independent write batches:
    │
    └─ 4. update_head()                 Metadata: head
           (re-runs fork choice)        (+ justified/finalized if advanced,
+                                          + BlockRoots diff (canonical index),
                                           + pruning on finalization)
 ```
 
@@ -340,10 +387,10 @@ processed):
   not needed for fork choice, reorg safety, or re-aggregation once outside
   the window.
 
-**Never pruned:** `BlockHeaders`, `BlockBodies`, `States`, `StateDiffs`, and
-`Metadata`. Headers, bodies, and the snapshot+diff chain are the full
-historical record; only the proof blobs and the fork choice index are
-disposable.
+**Never pruned:** `BlockHeaders`, `BlockBodies`, `BlockRoots`, `States`,
+`StateDiffs`, and `Metadata`. Headers, bodies, the canonical slot index, and
+the snapshot+diff chain are the full historical record; only the proof blobs
+and the (non-finalized) fork choice index are disposable.
 
 ## In-Memory Only (Lost on Restart)
 
@@ -369,7 +416,7 @@ pools.
 
 After a restart these buffers start empty: pending attestations and
 un-aggregated gossip signatures are lost and must be re-collected from the
-network. Everything persisted in the seven tables survives.
+network. Everything persisted in the eight tables survives.
 
 ## Startup and Restore
 
@@ -385,8 +432,8 @@ A `Store` is created through one of three constructors in
 The first two funnel into `init_store`, which writes the anchor in **one
 atomic batch**: all six `Metadata` keys (time = 0, config, head = safe_target
 = anchor root, justified = finalized = anchor checkpoint), the anchor header,
-the body if non-empty, a full snapshot into `States` (the base of every future
-diff chain), and the anchor's `LiveChain` entry.
+its `BlockRoots` entry, the body if non-empty, a full snapshot into `States`
+(the base of every future diff chain), and the anchor's `LiveChain` entry.
 
 `from_db_state` is the restore path: it reads `config` and `latest_finalized`
 from `Metadata`, returning `None` for an empty DB or a `genesis_time`