feat: add offline waterbody source crosswalk

rf4_research/waterbody_crosswalk.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import Iterable, Protocol
 
 from .media_assets import normalize_entity_label
 
@@ -21,6 +22,14 @@ class WaterbodyIdentity:
     name: str
 
 
+class WaterbodyCandidate(Protocol):
+    """Minimum shape shared by parsed secondary-source candidates."""
+
+    source_system: str
+    source_external_id: str
+    name: str
+
+
 @dataclass(frozen=True, slots=True)
 class CrosswalkSuggestion:
     source_system: str
@@ -30,6 +39,24 @@ class CrosswalkSuggestion:
     canonical_keys: tuple[str, ...]
 
 
+def identities_from_candidates(
+    candidates: Iterable[WaterbodyCandidate],
+) -> list[WaterbodyIdentity]:
+    """Convert parser rows without selecting a canonical key.
+
+    Metrics, URLs, and other source facts stay outside the crosswalk
+    decision and must not influence automatic canonical matching.
+    """
+    return [
+        WaterbodyIdentity(
+            source_system=row.source_system,
+            external_id=row.source_external_id,
+            name=row.name,
+        )
+        for row in candidates
+    ]
+
+
 def suggest_waterbody_crosswalk(
     canonical: list[CanonicalWaterbody], identities: list[WaterbodyIdentity],
 ) -> list[CrosswalkSuggestion]: