improve(core): add strict validation for edge_map source keys

Add proper validation to reject invalid source edge_ids in edge_map to
prevent user confusion and provide clear error messages.

Changes:
- Validate that all edge_map keys exist in the graph
- Raise ValueError with helpful message listing valid edge_ids
- Update tests to expect validation errors instead of silent ignoring
- Maintain support for arbitrary target values (strings, new IDs, etc.)

This improves user experience by catching configuration errors early
rather than silently ignoring invalid mappings.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: edeno

src/track_linearization/core.py

@@ -803,8 +803,13 @@ def get_linearized_position(
     # Convert segment indices to edge labels
     edge_ids = edge_id_by_index[seg_idx]
 
-    # Apply edge_map to labels
+    # Apply edge_map to labels and validate
     if edge_map is not None:
+        invalid_keys = [k for k in edge_map.keys() if k not in index_by_edge_id]
+        if invalid_keys:
+            raise ValueError(f"edge_map contains invalid source edge_ids: {invalid_keys}. "
+                           f"Valid edge_ids are: {list(index_by_edge_id.keys())}")
+
         # Apply mapping, keeping original dtype flexible for strings/mixed types
         mapped_edge_ids = np.array([edge_map.get(eid, eid) for eid in edge_ids])
         # Keep using original seg_idx for internal operations - only use mapped_edge_ids for output

src/track_linearization/tests/test_core.py

@@ -670,17 +670,15 @@ def test_edge_map_validation_invalid_keys(self, simple_rectangular_track):
         """Test edge_map validation with invalid keys."""
         position = np.array([[15, 0]])
 
-        # Map non-existent edge ID - should be ignored
+        # Map non-existent edge ID - should raise ValueError
         invalid_edge_map = {999: 1}  # 999 doesn't exist
 
-        pos_df = get_linearized_position(
-            position=position,
-            track_graph=simple_rectangular_track,
-            edge_map=invalid_edge_map
-        )
-
-        # Should still work (invalid keys ignored)
-        assert hasattr(pos_df, 'linear_position'), "Invalid edge_map keys should be ignored"
+        with pytest.raises(ValueError, match="edge_map contains invalid source edge_ids"):
+            get_linearized_position(
+                position=position,
+                track_graph=simple_rectangular_track,
+                edge_map=invalid_edge_map
+            )
 
     def test_edge_map_none_vs_no_parameter(self, simple_rectangular_track):
         """Test that edge_map=None is equivalent to not providing edge_map."""

src/track_linearization/tests/test_edge_map.py

@@ -30,10 +30,9 @@ def test_edge_map_merge_two_edges_to_one_label():
     df = core.get_linearized_position(pts, g, edge_map={10:99, 20:99}, use_HMM=False)
     assert set(df["track_segment_id"].unique()) == {99}
 
-def test_edge_map_invalid_source_ignored():
+def test_edge_map_invalid_source_raises():
     g = _mk_line_graph()
     pts = np.array([[0.2,0.0]])
-    # 999 is not a real edge_id in the graph; should be ignored
-    df = core.get_linearized_position(pts, g, edge_map={999:42, 10:50}, use_HMM=False)
-    # Should work and use the valid mapping (10->50) while ignoring invalid key (999)
-    assert df.track_segment_id.iloc[0] == 50
+    with pytest.raises(ValueError, match="edge_map contains invalid source edge_ids"):
+        # 999 is not a real edge_id in the graph; should raise ValueError
+        core.get_linearized_position(pts, g, edge_map={999:42, 10:50}, use_HMM=False)