retry inviting rejected miner UIDs in competition enrollment due to low alpha stake (#190)

docs/competitions.md

@@ -112,6 +112,11 @@ competition_start_time
   < competition_end_time
 ```
 
+A miner below `minimum_alpha_stake` remains in the invitation queue and is
+retried at `contender_ping_interval` until enrollment ends. If its stake reaches
+the threshold in time, it can opt in and submit normally. The finalisation check
+still rejects any pinned submission that is below the threshold at the freeze.
+
 ### Execution resources and safety
 
 | Field | Meaning |

tests/competition/test_enrollment.py

@@ -271,17 +271,14 @@ class EnrollmentDispatcherTests(unittest.TestCase):
             len([call for call in forwarder.calls if call[0] == "invitation"]), 2
         )
 
-    def test_ineligible_alpha_stake_is_reported_and_persisted(self) -> None:
+    def test_below_minimum_alpha_stake_is_retried_until_miner_qualifies(self) -> None:
         self.competition.manifest_json = self.manifest.model_copy(
             update={"minimum_alpha_stake": 10}
         ).normalized_json()
         endpoints = [
             CompetitionMinerEndpoint(
-                1, "participating-hotkey", "coldkey-1", object(), alpha_stake=10
-            ),
-            CompetitionMinerEndpoint(
-                2, "declining-hotkey", "coldkey-2", object(), alpha_stake=9
-            ),
+                1, "participating-hotkey", "coldkey-1", object(), alpha_stake=9
+            )
         ]
         forwarder = FakeForwarder()
         dispatcher = CompetitionEnrollmentDispatcher(
@@ -294,27 +291,20 @@ class EnrollmentDispatcherTests(unittest.TestCase):
 
         asyncio.run(dispatcher.run_once(self.competition, endpoints))
 
-        self.assertCountEqual(
-            forwarder.calls[:2],
-            [
-                ("invitation", "participating-hotkey"),
-                ("invitation", "declining-hotkey"),
-            ],
-        )
-        self.assertEqual(
-            forwarder.calls[2], ("submission", "participating-hotkey")
-        )
-        rejected = self.repository.get_contender(
-            self.manifest.competition_id, "declining-hotkey"
+        self.assertEqual(forwarder.calls, [("invitation", "participating-hotkey")])
+        contender = self.repository.get_contender(
+            self.manifest.competition_id, "participating-hotkey"
         )
-        self.assertEqual(rejected.status, ContenderState.REJECTED.value)
-        self.assertEqual(rejected.reason_code, "ALPHA_STAKE_BELOW_MINIMUM")
-        self.assertIn("Observed alpha stake 9", rejected.reason_detail)
+        self.assertEqual(contender.status, ContenderState.INVITED.value)
+        self.assertEqual(contender.reason_code, "ALPHA_STAKE_BELOW_MINIMUM")
+        self.assertIn("Observed alpha stake 9", contender.reason_detail)
+        self.assertEqual(contender.invitation_attempts, 1)
+        first_invited_at = contender.last_invited_at
         rejection = next(
             response
             for response in forwarder.responses
             if isinstance(response, protocol.CompetitionInvitationProtocol)
-            and response.axon.hotkey == "declining-hotkey"
+            and response.axon.hotkey == "participating-hotkey"
         )
         self.assertEqual(
             rejection.eligibility_reason_code, "ALPHA_STAKE_BELOW_MINIMUM"
@@ -322,6 +312,43 @@ class EnrollmentDispatcherTests(unittest.TestCase):
         self.assertEqual(rejection.observed_alpha_stake, 9)
         self.assertEqual(rejection.minimum_alpha_stake, 10)
 
+        # Rows written by older validators were terminally rejected. They are
+        # requeued on the next metagraph snapshot during enrollment.
+        with self.repository.engine.begin() as connection:
+            connection.exec_driver_sql(
+                "UPDATE contender_metadata SET status='REJECTED' "
+                "WHERE competition_id=? AND hotkey=?",
+                (self.manifest.competition_id, "participating-hotkey"),
+            )
+
+        self.clock.now += self.manifest.contender_ping_interval
+        asyncio.run(dispatcher.run_once(self.competition, endpoints))
+
+        contender = self.repository.get_contender(
+            self.manifest.competition_id, "participating-hotkey"
+        )
+        self.assertEqual(contender.status, ContenderState.INVITED.value)
+        self.assertEqual(contender.reason_code, "ALPHA_STAKE_BELOW_MINIMUM")
+        self.assertEqual(contender.invitation_attempts, 2)
+        self.assertNotEqual(contender.last_invited_at, first_invited_at)
+
+        self.clock.now += self.manifest.contender_ping_interval
+        qualified_endpoints = [
+            CompetitionMinerEndpoint(
+                1, "participating-hotkey", "coldkey-1", object(), alpha_stake=10
+            )
+        ]
+        asyncio.run(dispatcher.run_once(self.competition, qualified_endpoints))
+
+        contender = self.repository.get_contender(
+            self.manifest.competition_id, "participating-hotkey"
+        )
+        self.assertEqual(contender.status, ContenderState.PARTICIPATING.value)
+        self.assertIsNone(contender.reason_code)
+        self.assertIsNone(contender.reason_detail)
+        self.assertEqual(contender.invitation_attempts, 3)
+        self.assertIn(("submission", "participating-hotkey"), forwarder.calls)
+
     def test_unavailable_alpha_stake_is_reported_and_persisted(self) -> None:
         self.competition.manifest_json = self.manifest.model_copy(
             update={"minimum_alpha_stake": 10}

vidaio_subnet_core/competition/enrollment.py

@@ -254,6 +254,13 @@ class CompetitionEnrollmentDispatcher:
                     "ENROLLMENT_WINDOW_CLOSED",
                     "invitation response arrived after contender finalisation",
                 )
+            if eligibility_reason_code == "ALPHA_STAKE_BELOW_MINIMUM":
+                # Match retryable transport failures such as CONTENDER_NOT_FOUND:
+                # record the reason without moving the row out of INVITED.
+                raise EnrollmentResponseError(
+                    eligibility_reason_code,
+                    eligibility_reason_detail or eligibility_reason_code,
+                )
             participating = invitation.participating and eligibility_reason_code is None
             await asyncio.to_thread(
                 self.repository.record_invitation_response,

vidaio_subnet_core/competition/repository.py

@@ -2776,6 +2776,17 @@ class CompetitionRepository:
                     row.uid_snapshot = uid_snapshot
                     row.coldkey_snapshot = coldkey_snapshot
                     row.updated_at = now_text
+                elif (
+                    row.status == ContenderState.REJECTED.value
+                    and row.reason_code == "ALPHA_STAKE_BELOW_MINIMUM"
+                    and row.pinned_commit_sha is None
+                ):
+                    # Requeue invitation-time rejections from older validators.
+                    # Pinned finalisation rejections must remain closed.
+                    row.status = ContenderState.INVITED.value
+                    row.uid_snapshot = uid_snapshot
+                    row.coldkey_snapshot = coldkey_snapshot
+                    row.updated_at = now_text
         return created
 
     def reject_ineligible_contenders(