docs(spec): correct Raises docstrings to typed SpecRejectionError (leanEthereum#879)

The typed-rejection migration replaced prose-matched assertions with
SpecRejectionError carrying a RejectionReason, but several Raises
sections still documented the old AssertionError / ValueError types.

Update the affected docstrings to name SpecRejectionError and the
concrete rejection reason, and drop the banned backticks from the
participation docstrings:

- containers/participation.py: from_indices, to_validator_indices
- state_transition.py: process_slots, process_block_header,
  process_block, state_transition
- fork_choice.py: create_store, validate_attestation,
  on_gossip_attestation, on_gossip_aggregated_attestation, on_block

The on_gossip_aggregated_attestation signature path genuinely raises a
raw AssertionError, so that one entry is kept and only made precise.
The duplicate-attestation check documented on process_block actually
lives in on_block; the docstrings now reflect where each rejection is
raised.

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

Author: tcoratger

src/lean_spec/spec/forks/lstar/containers/participation.py

@@ -23,8 +23,8 @@ def from_indices(cls, indices: Iterable[ValidatorIndex]) -> "AggregationBits":
             Aggregation bits with exactly the given indices set to True.
 
         Raises:
-            AssertionError: If no indices are provided.
-            AssertionError: If any index is outside the supported LIMIT.
+            SpecRejectionError: EMPTY_AGGREGATION_BITS if no indices are provided.
+            SpecRejectionError: VALIDATOR_INDEX_OUT_OF_RANGE if an index exceeds the limit.
         """
         # Convert to native ints once for bounds checking and membership tests.
         #
@@ -55,10 +55,10 @@ def to_validator_indices(self) -> ValidatorIndices:
         Extract all validator indices encoded in these aggregation bits.
 
         Returns:
-            `ValidatorIndices` containing the indices, sorted in ascending order.
+            ValidatorIndices containing the indices, sorted in ascending order.
 
         Raises:
-            `AssertionError`: If no bits are set.
+            SpecRejectionError: EMPTY_AGGREGATION_BITS if no bits are set.
         """
         # Extract indices where bit is set; fail if none found.
         indices = [ValidatorIndex(i) for i, bit in enumerate(self.data) if bit]

src/lean_spec/spec/forks/lstar/fork_choice.py

@@ -77,9 +77,8 @@ def create_store(
         Both are treated as justified and finalized.
 
         Raises:
-            AssertionError:
-                If the anchor block's state root does not match the hash
-                of the state.
+            SpecRejectionError: ANCHOR_STATE_ROOT_MISMATCH if the anchor block's
+                state root does not match the hash of the state.
         """
         assert isinstance(state, State)
         assert isinstance(anchor_block, Block)
@@ -180,7 +179,7 @@ def validate_attestation(self, store: LstarStore, attestation_data: AttestationD
             6. The vote's slot must have started locally (a small disparity margin is allowed).
 
         Raises:
-            AssertionError: If attestation fails validation.
+            SpecRejectionError: If the attestation fails any of the validation checks above.
         """
         source_checkpoint = attestation_data.source
         target_checkpoint = attestation_data.target
@@ -297,8 +296,8 @@ def on_gossip_attestation(
             aggregator mode, otherwise the input store unchanged.
 
         Raises:
-            ValueError: If validator not found in state.
-            AssertionError: If signature verification fails.
+            SpecRejectionError: VALIDATOR_NOT_IN_STATE if the validator is not in the state.
+            SpecRejectionError: INVALID_SIGNATURE if signature verification fails.
         """
         with observe_on_attestation():
             validator_index = signed_attestation.validator_index
@@ -361,8 +360,8 @@ def on_gossip_aggregated_attestation(
         2. Stores the aggregation in aggregation_payloads map
 
         Raises:
-            ValueError: If validator not found in state.
-            AssertionError: If signature verification fails.
+            SpecRejectionError: VALIDATOR_NOT_IN_STATE if a participant is not in the state.
+            AssertionError: If aggregate signature verification fails.
         """
         attestation_data = signed_attestation.data
         aggregated_proof = signed_attestation.proof
@@ -432,7 +431,9 @@ def on_block(
         4. Updating the forkchoice head
 
         Raises:
-            AssertionError: If parent block/state not found in store.
+            SpecRejectionError: UNKNOWN_PARENT_BLOCK if the parent state is not in the store.
+            SpecRejectionError: DUPLICATE_ATTESTATION_DATA if the block repeats an AttestationData.
+            SpecRejectionError: TOO_MANY_ATTESTATION_DATA if the block exceeds the data cap.
         """
         with observe_on_block():
             block = signed_block.block

src/lean_spec/spec/forks/lstar/state_transition.py

@@ -132,7 +132,7 @@ def process_slots(self, state: State, target_slot: Slot) -> State:
         The function returns a new state with slot == target_slot.
 
         Raises:
-            AssertionError: If target_slot is not in the future.
+            SpecRejectionError: BLOCK_SLOT_NOT_IN_FUTURE if target_slot is not in the future.
         """
         # The target must be strictly greater than the current slot.
         if state.slot >= target_slot:
@@ -182,7 +182,8 @@ def process_block_header(self, state: State, block: Block) -> State:
           - Set latest_block_header for the new block with an empty state_root.
 
         Raises:
-            AssertionError: If any header check fails.
+            SpecRejectionError: If any header check fails (slot mismatch, block older
+                than the latest header, wrong proposer, or parent root mismatch).
         """
         # Validation
         #
@@ -311,8 +312,7 @@ def process_block(self, state: State, block: Block) -> State:
         Apply full block processing including header and body.
 
         Raises:
-            AssertionError: If block contains duplicate aggregated attestations
-                with no unique participant.
+            SpecRejectionError: If header validation fails.
         """
         # First process the block header.
         state = self.process_block_header(state, block)
@@ -573,7 +573,8 @@ def state_transition(
         Signatures are verified outside this function, before it is called.
 
         Raises:
-            AssertionError: If the computed state root is invalid.
+            SpecRejectionError: If slot or header validation fails, or STATE_ROOT_MISMATCH
+                if the block's state root does not match the computed post-state root.
         """
         with observe_state_transition():
             # First, process any intermediate slots.