feat: pace startup housekeeper runs

src/ccma/services/housekeeper.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 import copy
 import json
+import math
 import os
+import time
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from datetime import date, datetime
@@ -54,8 +56,14 @@ class Housekeeper:
         self.state_path = repository.root / "housekeeper.json"
         self.lock_path = repository.root / ".housekeeper.lock"
 
-    def run(self, today: date | None = None) -> list[HousekeeperFinding]:
+    def run(
+        self,
+        today: date | None = None,
+        *,
+        member_delay: float = 0.0,
+    ) -> list[HousekeeperFinding]:
         current_date = today or date.today()
+        delay = _non_negative_delay(member_delay)
         with _exclusive_lock(self.lock_path):
             original = self._load_state()
             working = copy.deepcopy(original)
@@ -69,7 +77,9 @@ class Housekeeper:
 
             rules = load_rules(self.repository.root)
             repository_config = self.repository.get_configuration()
-            for member_id in sorted(member_ids):
+            for index, member_id in enumerate(sorted(member_ids)):
+                if index and delay:
+                    time.sleep(delay)
                 try:
                     member, contributions = self.repository.preflight_member_record(member_id)
                 except RepositoryError as exc:
@@ -405,6 +415,14 @@ def _remove_orphaned_member_items(items: dict[str, dict[str, Any]], member_ids:
         del items[key]
 
 
+def _non_negative_delay(value: float) -> float:
+    try:
+        delay = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    return max(0.0, delay) if math.isfinite(delay) else 0.0
+
+
 @contextmanager
 def _exclusive_lock(path: Path):
     path.parent.mkdir(parents=True, exist_ok=True)