Make background tasks idempotent - prevent duplicate bans on retry

CRITICAL FIX: Background tasks (especially blocklist_import) crashed mid-execution,
leaving partial state. On retry, the same bans were applied again, causing duplicates.

Solution: Content-hash based operation tracking for blocklist imports:
- Added import_runs table (migration 6) to track operations by source + content hash
- Before banning, check if this exact content has already been imported
- If completed: skip banning (already done), optionally re-warm cache
- If new or failed: proceed with ban and mark as completed or failed

Changes:
- Database: Migration 6 adds import_runs table with operation state tracking
- Model: Added ImportRunEntry for import run records
- Repository: New import_run_repo module with CRUD operations
- Workflow: Updated blocklist_import_workflow to check operation history before banning
- Dependencies: Registered import_run_repo for dependency injection
- Tests: Added test_import_source_idempotent_on_retry and test_import_source_different_content_not_reused
- Documentation: Added Task Idempotency section to Backend-Development.md

Verification:
- All 7 import tests pass (5 existing + 2 new idempotency tests)
- Type checking: mypy --strict ✅
- Linting: ruff ✅
- No API changes, backwards compatible via automatic migration

Fixes: Background tasks not idempotent #CRITICAL

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/app/tasks/geo_re_resolve.py

@@ -21,8 +21,8 @@ from typing import TYPE_CHECKING
 
 import structlog
 
-from app.services.geo_cache import GeoCache
 from app.tasks.db import task_db
+from app.tasks.timeout_utils import run_with_timeout
 from app.utils.runtime_state import get_effective_settings
 
 if TYPE_CHECKING:
@@ -30,6 +30,7 @@ if TYPE_CHECKING:
     from fastapi import FastAPI
 
     from app.config import Settings
+    from app.services.geo_cache import GeoCache
 
 log: structlog.stdlib.BoundLogger = structlog.get_logger()
 
@@ -39,6 +40,9 @@ GEO_RE_RESOLVE_INTERVAL: int = 600
 #: Stable APScheduler job ID — ensures re-registration replaces, not duplicates.
 JOB_ID: str = "geo_re_resolve"
 
+#: Maximum seconds to allow for geo re-resolve to complete.
+TASK_TIMEOUT_SECONDS: int = 120
+
 
 async def _run_re_resolve_with_resources(
     geo_cache: GeoCache, settings: Settings, http_session: ClientSession
@@ -50,31 +54,35 @@ async def _run_re_resolve_with_resources(
         settings: The resolved application settings used for database access.
         http_session: The shared aiohttp session used for external lookups.
     """
-    async with task_db(settings) as db:
-        # Fetch all IPs with NULL country_code from the persistent cache.
-        unresolved_ips = await geo_cache.get_unresolved_ips(db)
 
-        if not unresolved_ips:
-            log.debug("geo_re_resolve_skip", reason="no_unresolved_ips")
-            return
+    async def _do_re_resolve() -> None:
+        async with task_db(settings) as db:
+            # Fetch all IPs with NULL country_code from the persistent cache.
+            unresolved_ips = await geo_cache.get_unresolved_ips(db)
 
-        log.info("geo_re_resolve_start", unresolved=len(unresolved_ips))
+            if not unresolved_ips:
+                log.debug("geo_re_resolve_skip", reason="no_unresolved_ips")
+                return
 
-        # Clear the negative cache so these IPs are eligible for fresh API calls.
-        await geo_cache.clear_neg_cache()
+            log.info("geo_re_resolve_start", unresolved=len(unresolved_ips))
 
-        # lookup_batch handles throttling, retries, and persistence when db is
-        # passed.  This is a background task so DB writes are allowed.
-        results = await geo_cache.lookup_batch(unresolved_ips, http_session, db=db)
+            # Clear the negative cache so these IPs are eligible for fresh API calls.
+            await geo_cache.clear_neg_cache()
 
-    resolved_count: int = sum(
-        1 for info in results.values() if info.country_code is not None
-    )
-    log.info(
-        "geo_re_resolve_complete",
-        retried=len(unresolved_ips),
-        resolved=resolved_count,
-    )
+            # lookup_batch handles throttling, retries, and persistence when db is
+            # passed.  This is a background task so DB writes are allowed.
+            results = await geo_cache.lookup_batch(unresolved_ips, http_session, db=db)
+
+        resolved_count: int = sum(
+            1 for info in results.values() if info.country_code is not None
+        )
+        log.info(
+            "geo_re_resolve_complete",
+            retried=len(unresolved_ips),
+            resolved=resolved_count,
+        )
+
+    await run_with_timeout("geo_re_resolve", _do_re_resolve(), TASK_TIMEOUT_SECONDS)
 
 
 async def _run_re_resolve(app: FastAPI) -> None: