fix: auto-migrate existing Windows graphs with backslash entity IDs

When loading graphs created on Windows (schema <2.2.0), normalize all
backslash entity IDs to forward slashes across entities, file_index,
edges, and hierarchy. Preserves all semantic features and lifted data.
Bumps schema version to 2.2.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: userFRM

crates/rpg-core/src/schema.rs

@@ -8,7 +8,7 @@ use crate::graph::RPGraph;
 use anyhow::{Context, Result};
 use semver::Version;
 
-const CURRENT_VERSION: &str = "2.1.0";
+const CURRENT_VERSION: &str = "2.2.0";
 
 /// Validate an RPGraph's schema version using semver compatibility.
 ///
@@ -40,14 +40,82 @@ pub fn migrate(graph: &mut RPGraph) -> Result<()> {
     let found = Version::parse(&graph.version)?;
 
     if found < current {
-        // Future migrations go here, e.g.:
-        // if found < Version::new(2, 1, 0) { ... }
+        // v2.2.0: normalize backslash entity IDs to forward slashes (Windows compat fix)
+        if found < Version::new(2, 2, 0) {
+            migrate_normalize_entity_ids(graph);
+        }
         graph.version = CURRENT_VERSION.to_string();
     }
 
     Ok(())
 }
 
+/// Migrate entity IDs from backslash paths to forward-slash paths.
+///
+/// On Windows, older graphs stored entity IDs with backslashes
+/// (e.g. `src\auth\login.py:validate`). This normalizes them to
+/// forward slashes so lookups from MCP tools match consistently.
+fn migrate_normalize_entity_ids(graph: &mut RPGraph) {
+    fn norm(id: &str) -> String {
+        id.replace('\\', "/")
+    }
+
+    fn fix_hierarchy(
+        node: &mut crate::graph::HierarchyNode,
+        remap: &std::collections::HashMap<String, String>,
+    ) {
+        for id in &mut node.entities {
+            if let Some(new_id) = remap.get(id.as_str()) {
+                *id = new_id.clone();
+            }
+        }
+        for child in node.children.values_mut() {
+            fix_hierarchy(child, remap);
+        }
+    }
+
+    // 1. Rebuild entities map with normalized keys + id fields
+    let old_entities = std::mem::take(&mut graph.entities);
+    let mut id_remap: std::collections::HashMap<String, String> = std::collections::HashMap::new();
+    for (old_key, mut entity) in old_entities {
+        let new_key = norm(&old_key);
+        entity.id = new_key.clone();
+        if old_key != new_key {
+            id_remap.insert(old_key, new_key.clone());
+        }
+        graph.entities.insert(new_key, entity);
+    }
+
+    // Nothing was remapped — graph already uses forward slashes
+    if id_remap.is_empty() {
+        return;
+    }
+
+    // 2. Update file_index value lists
+    for ids in graph.file_index.values_mut() {
+        for id in ids.iter_mut() {
+            if let Some(new_id) = id_remap.get(id.as_str()) {
+                *id = new_id.clone();
+            }
+        }
+    }
+
+    // 3. Update edge source/target
+    for edge in &mut graph.edges {
+        if let Some(new_id) = id_remap.get(&edge.source) {
+            edge.source = new_id.clone();
+        }
+        if let Some(new_id) = id_remap.get(&edge.target) {
+            edge.target = new_id.clone();
+        }
+    }
+
+    // 4. Update hierarchy entity lists (recursive)
+    for node in graph.hierarchy.values_mut() {
+        fix_hierarchy(node, &id_remap);
+    }
+}
+
 /// Serialize an RPGraph to a pretty-printed JSON string.
 ///
 /// Edges are sorted by (source, target, kind) for deterministic output,
@@ -139,4 +207,79 @@ mod tests {
         let graph = graph_with_version("not-a-version");
         assert!(validate_version(&graph).is_err());
     }
+
+    #[test]
+    fn test_migrate_normalizes_backslash_ids() {
+        use crate::graph::{
+            DependencyEdge, EdgeKind, Entity, EntityDeps, EntityKind, HierarchyNode,
+        };
+        use std::path::PathBuf;
+
+        let mut graph = graph_with_version("2.1.0");
+
+        // Insert entity with backslash ID (as Windows would produce)
+        let old_id = r"src\auth\login.py:validate".to_string();
+        graph.entities.insert(
+            old_id.clone(),
+            Entity {
+                id: old_id.clone(),
+                kind: EntityKind::Function,
+                name: "validate".to_string(),
+                file: PathBuf::from("src/auth/login.py"),
+                line_start: 1,
+                line_end: 10,
+                parent_class: None,
+                semantic_features: vec!["validates user credentials".to_string()],
+                feature_source: Some("llm".to_string()),
+                hierarchy_path: String::new(),
+                deps: EntityDeps::default(),
+                signature: None,
+            },
+        );
+
+        // file_index references the old ID
+        graph
+            .file_index
+            .insert(PathBuf::from("src/auth/login.py"), vec![old_id.clone()]);
+
+        // edge references the old ID
+        graph.edges.push(DependencyEdge {
+            source: old_id.clone(),
+            target: "other:target".to_string(),
+            kind: EdgeKind::Invokes,
+        });
+
+        // hierarchy references the old ID
+        let mut node = HierarchyNode::new("Auth");
+        node.entities.push(old_id.clone());
+        graph.hierarchy.insert("h:Auth".to_string(), node);
+
+        // Run migration
+        migrate(&mut graph).unwrap();
+
+        let new_id = "src/auth/login.py:validate";
+
+        // Entity moved to new key
+        assert!(graph.entities.contains_key(new_id));
+        assert!(!graph.entities.contains_key(&old_id));
+        assert_eq!(graph.entities[new_id].id, new_id);
+        // Semantic features preserved
+        assert_eq!(
+            graph.entities[new_id].semantic_features,
+            vec!["validates user credentials"]
+        );
+
+        // file_index updated
+        let file_ids = &graph.file_index[&PathBuf::from("src/auth/login.py")];
+        assert_eq!(file_ids, &[new_id]);
+
+        // edge updated
+        assert_eq!(graph.edges[0].source, new_id);
+
+        // hierarchy updated
+        assert_eq!(graph.hierarchy["h:Auth"].entities, vec![new_id]);
+
+        // version bumped
+        assert_eq!(graph.version, CURRENT_VERSION);
+    }
 }