fix(ssz): correct JustificationValidators LIMIT formula in rule doc (leanEthereum#728)

The SSZ-patterns rule doc showed `LIMIT = HISTORICAL_ROOTS_LIMIT *
HISTORICAL_ROOTS_LIMIT` for the JustificationValidators example, but
the type stores one bit per (tracked root, registered validator)
pair. The second factor must be the validator registry limit.

The numerical impact is large: the doc value is 64x the correct
value. Because BaseBitlist.LIMIT controls the merkleization depth,
a second-client implementer following the rule doc would compute a
different hash_tree_root for the same state field and fork off
silently the first time they tried to talk to a node built from
this code.

Changes:

- ssz-patterns.md: fix the formula in the example, add an inline
  rationale, and define VALIDATOR_REGISTRY_LIMIT alongside
  HISTORICAL_ROOTS_LIMIT so the math is self-contained.
- ssz-patterns.md: update the frontmatter path glob and the
  architecture diagram to reflect that containers moved to
  forks/<fork>/containers/ in the recent refactor.
- state/types.py: expand the one-line docstring on
  JustificationValidators to document the layout and the
  consensus-critical nature of the LIMIT product.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tcoratger

.claude/rules/ssz-patterns.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - "src/lean_spec/subspecs/containers/**/*.py"
+  - "src/lean_spec/forks/*/containers/**/*.py"
   - "src/lean_spec/types/**/*.py"
 ---
 
@@ -36,7 +36,7 @@ When creating SSZ types, follow these established patterns:
 Containers should be organized into modules with clear separation:
 
 ```
-src/lean_spec/subspecs/containers/
+src/lean_spec/forks/<fork>/containers/
 ├── state/
 │   ├── __init__.py      # Exports State and related types
 │   ├── state.py         # Main State container class
@@ -61,11 +61,15 @@ src/lean_spec/subspecs/containers/
 
 ```python
 # In state/types.py
-HISTORICAL_ROOTS_LIMIT = 262144
+HISTORICAL_ROOTS_LIMIT = 262144   # 2**18 tracked roots
+VALIDATOR_REGISTRY_LIMIT = 4096   # 2**12 registered validators
 
 class JustificationValidators(BaseBitlist):
-    """Bitlist for tracking validator justifications."""
-    LIMIT = HISTORICAL_ROOTS_LIMIT * HISTORICAL_ROOTS_LIMIT
+    """Per-root validator vote bitfields, concatenated into one flat bitlist."""
+    # Worst-case size: one bit per (tracked root, registered validator) pair.
+    # Any larger LIMIT inflates the bitlist's merkle depth and changes the
+    # state root for identical data, so this product is consensus-critical.
+    LIMIT = HISTORICAL_ROOTS_LIMIT * VALIDATOR_REGISTRY_LIMIT
 
 # In block/types.py
 class Attestations(SSZList):

src/lean_spec/forks/lstar/containers/state/types.py

@@ -162,6 +162,13 @@ def shift_window(self, delta: int) -> JustifiedSlots:
 
 
 class JustificationValidators(BaseBitlist):
-    """Bitlist for tracking validator justifications per historical root."""
+    """Per-root validator vote bitfields, concatenated into one flat bitlist.
+
+    Each tracked root contributes one bit per registered validator.
+    The cap is the maximum tracked roots times the validator registry limit.
+
+    Why this product: a larger cap inflates the bitlist's merkle tree depth.
+    That changes the state root for identical data, so this limit is consensus-critical.
+    """
 
     LIMIT = int(HISTORICAL_ROOTS_LIMIT) * int(VALIDATOR_REGISTRY_LIMIT)