fix(testing): make equivocation head assertions scheme-independent

The equivocation tiebreak vectors hardcoded the winning fork of #1181's
largest-attestation-data-root rule. That root embeds validator XMSS pubkeys,
so the winner flips between test and prod schemes; the vectors passed PR CI
(test scheme) and failed prod-vectors on main (prod scheme). Same class as #916.

Add a scheme-independent canonical_equivocation_head_among check that reads
each fork's attestation root from the store and asserts the head is the
largest-root fork, mirroring lexicographic_head_among. Rewrite the 3 vectors
to use it, note the scheme-dependence on the spec tiebreak, add a CLAUDE.md
rule, and gate fork-choice vectors under --scheme=prod in PR CI.

Author: leolara

.github/workflows/ci.yml

@@ -159,6 +159,41 @@ jobs:
       - name: Fill test fixtures
         run: just fill-ci
 
+  # Scheme-fragility guard. A root-based fork-choice tiebreak embeds the validator XMSS public
+  # keys, so a vector that hardcodes the winning fork can pass under the default `test` scheme
+  # and fail under `prod`. This reruns the fork-choice vectors under the prod scheme to catch
+  # that pre-merge. See CLAUDE.md, "FORK-CHOICE HEAD ASSERTIONS MUST BE SCHEME-INDEPENDENT".
+  # Determinism is already gated by fill-tests; this job disables it to stay a fast smoke check.
+  fill-tests-prod-scheme:
+    name: Fill fork-choice fixtures under the prod scheme - Python 3.14
+    runs-on: macos-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout leanSpec
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
+      - name: Download prod scheme keys
+        run: uv run keys --download --scheme prod
+
+      - name: Fill fork-choice fixtures under the prod scheme
+        run: just fill-ci --scheme=prod --no-check-determinism tests/consensus/lstar/fork_choice
+
   interop-tests:
     name: Interop tests - Multi-node consensus
     runs-on: macos-latest

CLAUDE.md

@@ -128,3 +128,21 @@ subspecifications that the Lean Ethereum protocol relies on.
     one-to-one: if an assertion changes, the matching docstring line changes with it.
   - Do not weaken a docstring into vagueness to avoid updating it; describe the new behavior
     precisely, as the doc-writer rules require.
+- **CRITICAL - FORK-CHOICE HEAD ASSERTIONS MUST BE SCHEME-INDEPENDENT**: This is a STRICT
+  requirement. A fork-choice head assertion (`head_slot`, `head_root_label`, or any check that
+  pins which block is head) must NOT depend on the signature scheme. Block and attestation-data
+  roots embed the genesis state root, which embeds the validator XMSS public keys, so a
+  root-based tiebreak winner can flip between the `test` and `prod` schemes. A vector that
+  hardcodes the winning fork passes under one scheme and fails under the other; this has shipped
+  twice (PR #916, PR #1181).
+  - Never pin the winner of a weight tie or an equal-slot equivocation tie to a hardcoded fork
+    label or slot. Assert the scheme-independent facts instead.
+  - For a weight tie between equal-weight forks, use `lexicographic_head_among` (head = highest
+    block root, computed from the store).
+  - For an equal-slot equivocation tie, use `canonical_equivocation_head_among` (head = fork
+    whose attestation carries the largest attestation-data root, computed from the store).
+  - When a tie is incidental to the scenario, prefer asserting the genuine behavior at a later
+    step where a single child or unambiguous weight removes the tie, rather than asserting the
+    head at the tie step.
+  - The identity of the winning fork may legitimately differ across schemes; what must hold is
+    that all nodes with identical store contents pick the identical head.

packages/testing/src/consensus_testing/test_types/store_checks.py

@@ -214,6 +214,18 @@ class StoreChecks(SelectiveCheck):
     All listed forks must have equal attestation weight, and the head carries the highest root.
     """
 
+    canonical_equivocation_head_among: list[str] | None = None
+    """Fork labels in an equal-slot equivocation tie, head on the largest attestation-data root.
+
+    Each listed fork must be targeted by at least one attestation in the store's accepted
+    aggregated pool. The fork whose attestation carries the largest canonical hash_tree_root
+    absorbs each equivocator's single counted vote, so the head must sit at that fork.
+
+    The roots are read from the store, so the assertion holds under any signature scheme;
+    it never pins which fork wins. The winner is a pure function of store contents, exactly as
+    the fork-choice latest-vote extraction computes it.
+    """
+
     reorg_depth: int | None = None
     """Expected count of blocks from the old head back to its common ancestor with the new head."""
 
@@ -437,6 +449,18 @@ def _canonical_precedence(vote: AttestationData) -> tuple[Slot, Bytes32]:
                 self.lexicographic_head_among, store, block_registry, step_index
             )
 
+        # Equal-slot equivocation tiebreak: head sits on the largest attestation-data root.
+        if "canonical_equivocation_head_among" in fields:
+            if block_registry is None:
+                raise ValueError(
+                    f"Step {step_index}: canonical_equivocation_head_among specified "
+                    f"but block_registry not provided"
+                )
+            assert self.canonical_equivocation_head_among is not None
+            StoreChecks._validate_canonical_equivocation_head(
+                self.canonical_equivocation_head_among, store, block_registry, step_index
+            )
+
         # Reorg depth
         if "reorg_depth" in fields:
             if old_head is None:
@@ -577,3 +601,81 @@ def _validate_lexicographic_head(
                 f"When forks have equal weight, the fork with the lexicographically "
                 f"highest root should be selected as head."
             )
+
+    @staticmethod
+    def _validate_canonical_equivocation_head(
+        fork_labels: list[str],
+        store: Store,
+        block_registry: dict[str, Block],
+        step_index: int,
+    ) -> None:
+        """
+        Validate the equal-slot equivocation tiebreak.
+
+        Each listed fork must be targeted by at least one attestation in the store's accepted
+        aggregated pool. The fork whose attestation carries the largest canonical
+        ``hash_tree_root`` absorbs each equivocator's single counted vote, so the head must sit
+        at that fork. The comparison key is identical to the one the fork-choice latest-vote
+        extraction sorts on, so the winner derived here is the fork that wins in the spec.
+
+        The roots are read from the store rather than hardcoded, which keeps the assertion
+        independent of the signature scheme: a block root embeds the genesis state root, which
+        embeds the validator XMSS public keys, so the identity of the winning fork can flip
+        between schemes. What is invariant is that the head tracks the largest root present.
+        """
+        if len(fork_labels) < 2:
+            raise ValueError(
+                f"Step {step_index}: canonical_equivocation_head_among requires at least 2 forks "
+                f"to test the equivocation tiebreak, got {len(fork_labels)}: {fork_labels}"
+            )
+
+        # Resolve each fork label to its block root.
+        fork_roots: dict[str, Bytes32] = {}
+        for label in fork_labels:
+            if label not in block_registry:
+                raise ValueError(
+                    f"Step {step_index}: canonical_equivocation_head_among label '{label}' "
+                    f"not found in block registry. Available: {list(block_registry.keys())}"
+                )
+            fork_roots[label] = hash_tree_root(block_registry[label])
+
+        # For each fork, take the largest canonical attestation-data root among the attestations
+        # targeting it. This is the same key the latest-vote extraction sorts on, so the fork with
+        # the maximum value here is the one each equivocator's weight lands on.
+        attestation_root_by_label: dict[str, Bytes32] = {}
+        for label, fork_root in fork_roots.items():
+            targeting_data_roots = [
+                hash_tree_root(attestation_data)
+                for attestation_data in store.latest_known_aggregated_payloads
+                if attestation_data.target.root == fork_root
+            ]
+            if not targeting_data_roots:
+                raise AssertionError(
+                    f"Step {step_index}: canonical_equivocation_head_among fork '{label}' "
+                    f"(block_root=0x{fork_root.hex()}) has no attestation targeting it in the "
+                    f"accepted aggregated pool."
+                )
+            attestation_root_by_label[label] = max(targeting_data_roots)
+
+        winning_label = max(
+            attestation_root_by_label, key=lambda label: attestation_root_by_label[label]
+        )
+        expected_head_root = fork_roots[winning_label]
+
+        if store.head != expected_head_root:
+            actual_label = next(
+                (label for label, root in fork_roots.items() if root == store.head),
+                "unknown",
+            )
+            fork_info = "\n".join(
+                f"  {label}: block_root=0x{fork_roots[label].hex()} "
+                f"attestation_data_root=0x{attestation_root_by_label[label].hex()}"
+                for label in sorted(fork_roots)
+            )
+            raise AssertionError(
+                f"Step {step_index}: canonical equivocation tiebreak failed.\n"
+                f"The head must be the fork with the largest attestation-data root.\n"
+                f"Expected head: '{winning_label}' (0x{expected_head_root.hex()})\n"
+                f"Actual head:   '{actual_label}' (0x{store.head.hex()})\n"
+                f"Competing forks:\n{fork_info}\n"
+            )

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

@@ -682,6 +682,14 @@ def _extract_attestations_from_aggregated_payloads(
         An equal-slot tie breaks toward the larger canonical attestation-data root.
         The result is therefore independent of arrival or insertion order.
 
+        What is guaranteed is agreement: any two nodes with identical store contents map every
+        validator to the identical vote, and so select the identical head. The identity of the
+        winning fork is not stable across configurations: an attestation-data root embeds its
+        target block root, which embeds the genesis state root, which embeds the validator XMSS
+        public keys, so the larger root (and thus the equivocator's landing fork) can flip between
+        signature schemes. Tests must assert the head against the largest root present in the
+        store, never against a hardcoded fork label.
+
         A vote whose head sits at or below the finalized slot carries no fork-choice weight.
         Such stale votes are skipped here, so callers pass their pool without pre-filtering.
 

tests/consensus/lstar/fork_choice/test_equivocation.py

@@ -246,7 +246,7 @@ def test_same_slot_equivocating_attesters_count_once(
     fork_choice_test: ForkChoiceTestFiller,
 ) -> None:
     """
-    An equivocating validator is counted once, on the canonical-root fork.
+    An equivocating validator is counted once, on the canonical attestation-data root fork.
 
     Given
     -----
@@ -259,18 +259,18 @@ def test_same_slot_equivocating_attesters_count_once(
     - one vote at slot 3 targets fork_b from V0, V1, V3, V4.
     - V0 and V1 equivocate by voting on both forks at the same slot.
     - the two votes tie on slot, so the larger attestation-data root wins.
-    - the fork_b vote carries the larger root.
 
     When
     ----
     - both votes arrive by gossip and are accepted.
 
     Then
     ----
-    - V0 and V1 count once, toward fork_b.
-    - fork_b has effective weight 4 from V0, V1, V3, V4.
-    - fork_a has effective weight 1 from V2.
-    - head is fork_b.
+    - V0 and V1 each have one canonical vote at slot 3 (counted once), not pinned to a fork
+      because the winner depends on roots read from the store, not on a hardcoded outcome.
+    - V2 targets fork_a; V3 and V4 target fork_b (the exclusive, non-equivocating supporters).
+    - the head is the fork whose vote carries the larger attestation-data root, derived from the
+      store, so the vector holds under either signature scheme.
     - no slot is justified by the below-threshold votes.
     """
     fork_choice_test(
@@ -317,8 +317,7 @@ def test_same_slot_equivocating_attesters_count_once(
             TickStep(
                 time=16,
                 checks=StoreChecks(
-                    head_slot=Slot(3),
-                    head_root_label="fork_b",
+                    canonical_equivocation_head_among=["fork_a", "fork_b"],
                     latest_justified_slot=Slot(0),
                     latest_finalized_slot=Slot(0),
                     latest_known_aggregated_target_slots=[Slot(2), Slot(3)],
@@ -327,13 +326,11 @@ def test_same_slot_equivocating_attesters_count_once(
                             validator=ValidatorIndex(0),
                             location="known",
                             attestation_slot=Slot(3),
-                            target_slot=Slot(3),
                         ),
                         AttestationCheck(
                             validator=ValidatorIndex(1),
                             location="known",
                             attestation_slot=Slot(3),
-                            target_slot=Slot(3),
                         ),
                         AttestationCheck(
                             validator=ValidatorIndex(2),
@@ -364,7 +361,7 @@ def test_equivocation_head_independent_of_arrival_order_a_then_b(
     fork_choice_test: ForkChoiceTestFiller,
 ) -> None:
     """
-    Head ignores arrival order: fork_a arriving first still picks the canonical-root fork.
+    Head ignores arrival order: the canonical-root fork wins regardless of vote order.
 
     Given
     -----
@@ -377,20 +374,19 @@ def test_equivocation_head_independent_of_arrival_order_a_then_b(
     - one vote at slot 3 targets fork_b from V0, V2.
     - V0 equivocates by voting on both forks at the same slot.
     - V1 backs fork_a alone; V2 backs fork_b alone.
-    - without V0 the two forks tie one-to-one, so V0's vote decides the head.
+    - without V0 the two forks tie one-to-one, so V0's single counted vote decides the head.
     - the two votes tie on slot, so the larger attestation-data root wins.
-    - the fork_a vote carries the larger root.
 
     When
     ----
     - the fork_a vote arrives first, then the fork_b vote.
 
     Then
     ----
-    - V0 counts once, toward the larger-root fork.
-    - the larger-root fork has effective weight 2.
-    - the smaller-root fork has effective weight 1.
-    - head is fork_a.
+    - V0 counts once, toward whichever fork's vote carries the larger attestation-data root.
+    - that fork has effective weight 2; the other has weight 1.
+    - the head is that fork, derived from the store roots rather than pinned, so it matches the
+      opposite arrival order under either signature scheme.
     - no slot is justified by the below-threshold votes.
     """
     fork_choice_test(
@@ -428,16 +424,14 @@ def test_equivocation_head_independent_of_arrival_order_a_then_b(
             TickStep(
                 time=16,
                 checks=StoreChecks(
-                    head_slot=Slot(2),
-                    head_root_label="fork_a",
+                    canonical_equivocation_head_among=["fork_a", "fork_b"],
                     latest_justified_slot=Slot(0),
                     latest_finalized_slot=Slot(0),
                     attestation_checks=[
                         AttestationCheck(
                             validator=ValidatorIndex(0),
                             location="known",
                             attestation_slot=Slot(3),
-                            target_slot=Slot(2),
                         ),
                     ],
                 ),
@@ -450,7 +444,7 @@ def test_equivocation_head_independent_of_arrival_order_b_then_a(
     fork_choice_test: ForkChoiceTestFiller,
 ) -> None:
     """
-    Head ignores arrival order: fork_b arriving first still picks the canonical-root fork.
+    Head ignores arrival order: the canonical-root fork wins regardless of vote order.
 
     Given
     -----
@@ -463,20 +457,19 @@ def test_equivocation_head_independent_of_arrival_order_b_then_a(
     - one vote at slot 3 targets fork_b from V0, V2.
     - V0 equivocates by voting on both forks at the same slot.
     - V1 backs fork_a alone; V2 backs fork_b alone.
-    - without V0 the two forks tie one-to-one, so V0's vote decides the head.
+    - without V0 the two forks tie one-to-one, so V0's single counted vote decides the head.
     - the two votes tie on slot, so the larger attestation-data root wins.
-    - the fork_a vote carries the larger root.
 
     When
     ----
     - the fork_b vote arrives first, then the fork_a vote.
 
     Then
     ----
-    - V0 counts once, toward the larger-root fork.
-    - the larger-root fork has effective weight 2.
-    - the smaller-root fork has effective weight 1.
-    - head is fork_a, matching the opposite arrival order.
+    - V0 counts once, toward whichever fork's vote carries the larger attestation-data root.
+    - that fork has effective weight 2; the other has weight 1.
+    - the head is that fork, derived from the store roots rather than pinned, so it matches the
+      opposite arrival order under either signature scheme.
     - no slot is justified by the below-threshold votes.
     """
     fork_choice_test(
@@ -514,16 +507,14 @@ def test_equivocation_head_independent_of_arrival_order_b_then_a(
             TickStep(
                 time=16,
                 checks=StoreChecks(
-                    head_slot=Slot(2),
-                    head_root_label="fork_a",
+                    canonical_equivocation_head_among=["fork_a", "fork_b"],
                     latest_justified_slot=Slot(0),
                     latest_finalized_slot=Slot(0),
                     attestation_checks=[
                         AttestationCheck(
                             validator=ValidatorIndex(0),
                             location="known",
                             attestation_slot=Slot(3),
-                            target_slot=Slot(2),
                         ),
                     ],
                 ),