Fix race condition in UPSERT entity implementation

Improve IntegrityError handling to distinguish between file_path
and permalink conflicts, addressing a race condition vulnerability
where:

1. Initial check finds no entity with file_path
2. Another process creates/deletes entity with same file_path
3. Insert fails with IntegrityError
4. We incorrectly assume it's a permalink conflict

Changes:
- Check for file_path conflict after IntegrityError using second query
- Handle race condition by updating the existing entity
- Only generate unique permalink if it's truly a permalink conflict
- Add comprehensive test for race condition scenario

This ensures robust conflict resolution regardless of timing between
concurrent operations on the same file_path.

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

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/repository/entity_repository.py

@@ -172,9 +172,47 @@ async def upsert_entity(self, entity: Entity) -> Entity:
                 return found
 
             except IntegrityError:
-                # Permalink conflict with different file - generate unique permalink
+                # Could be either file_path or permalink conflict
                 await session.rollback()
-                return await self._handle_permalink_conflict(entity, session)
+                
+                # Check if it's a file_path conflict (race condition)
+                existing_by_path_check = await session.execute(
+                    select(Entity).where(
+                        Entity.file_path == entity.file_path,
+                        Entity.project_id == entity.project_id
+                    )
+                )
+                race_condition_entity = existing_by_path_check.scalar_one_or_none()
+                
+                if race_condition_entity:
+                    # Race condition: file_path conflict detected after our initial check
+                    # Update the existing entity instead
+                    for key, value in {
+                        'title': entity.title,
+                        'entity_type': entity.entity_type,
+                        'entity_metadata': entity.entity_metadata,
+                        'content_type': entity.content_type,
+                        'permalink': entity.permalink,
+                        'checksum': entity.checksum,
+                        'updated_at': entity.updated_at,
+                    }.items():
+                        setattr(race_condition_entity, key, value)
+                    
+                    await session.flush()
+                    # Return the updated entity with relationships loaded
+                    query = (
+                        select(Entity)
+                        .where(Entity.file_path == entity.file_path)
+                        .options(*self.get_load_options())
+                    )
+                    result = await session.execute(query)
+                    found = result.scalar_one_or_none()
+                    if not found:  # pragma: no cover
+                        raise RuntimeError(f"Failed to retrieve entity after race condition update: {entity.file_path}")
+                    return found
+                else:
+                    # Must be permalink conflict - generate unique permalink
+                    return await self._handle_permalink_conflict(entity, session)
 
     async def _handle_permalink_conflict(self, entity: Entity, session: AsyncSession) -> Entity:
         """Handle permalink conflicts by generating a unique permalink."""

tests/repository/test_entity_repository_upsert.py

@@ -146,6 +146,65 @@ async def test_upsert_entity_multiple_permalink_conflicts(entity_repository: Ent
     assert len(set(entity_ids)) == 3
 
 
+@pytest.mark.asyncio
+async def test_upsert_entity_race_condition_file_path(entity_repository: EntityRepository):
+    """Test that upsert handles race condition where file_path conflict occurs after initial check."""
+    from unittest.mock import patch
+    from sqlalchemy.exc import IntegrityError
+    
+    # Create an entity first
+    entity1 = Entity(
+        project_id=entity_repository.project_id,
+        title="Original Entity",
+        entity_type="note",
+        permalink="test/original",
+        file_path="test/race-file.md",
+        content_type="text/markdown",
+        created_at=datetime.now(timezone.utc),
+        updated_at=datetime.now(timezone.utc),
+    )
+    
+    result1 = await entity_repository.upsert_entity(entity1)
+    original_id = result1.id
+    
+    # Create another entity with different file_path and permalink
+    entity2 = Entity(
+        project_id=entity_repository.project_id,
+        title="Race Condition Test",
+        entity_type="note", 
+        permalink="test/race-entity",
+        file_path="test/different-file.md",  # Different initially
+        content_type="text/markdown",
+        created_at=datetime.now(timezone.utc),
+        updated_at=datetime.now(timezone.utc),
+    )
+    
+    # Now simulate race condition: change file_path to conflict after the initial check
+    original_add = entity_repository.session_maker().add
+    call_count = 0
+    
+    def mock_add(obj):
+        nonlocal call_count
+        if isinstance(obj, Entity) and call_count == 0:
+            call_count += 1
+            # Simulate race condition by changing file_path to conflict
+            obj.file_path = "test/race-file.md"  # Same as entity1
+            # This should trigger IntegrityError for file_path constraint
+            raise IntegrityError("UNIQUE constraint failed: entity.file_path", None, None)
+        return original_add(obj)
+    
+    # Mock session.add to simulate the race condition
+    with patch.object(entity_repository.session_maker().__class__, 'add', side_effect=mock_add):
+        # This should handle the race condition gracefully by updating the existing entity
+        result2 = await entity_repository.upsert_entity(entity2)
+        
+        # Should return the updated original entity (same ID)
+        assert result2.id == original_id
+        assert result2.title == "Race Condition Test"  # Updated title
+        assert result2.file_path == "test/race-file.md"  # Same file path
+        assert result2.permalink == "test/race-entity"  # Updated permalink
+
+
 @pytest.mark.asyncio
 async def test_upsert_entity_gap_in_suffixes(entity_repository: EntityRepository):
     """Test that upsert finds the next available suffix even with gaps."""