fix(core): reject local note creates over existing unindexed files

A DB-first create whose target file already existed on disk but was not yet
indexed (manual write, DB reset, or watcher lag) committed new entity,
note_content, and search rows, then materialization recorded
external_change_detected without overwriting the file or rolling back. The
caller saw "Created" while the markdown kept old content and DB/search
described new content, and the next watcher pass would overwrite the DB with
the stale file, silently losing the write.

Local runtimes (filesystem is the source of truth) now keep the storage
existence check on creates via a new verify_storage_absent_on_create
dependency flag, rejecting with 409 instead of diverging. The previously
uncaught EntityAlreadyExistsError is mapped to a typed conflict rejection.
Cloud keeps DB-first acceptance (flag defaults to False) and reconciles object
storage during materialization.

Addresses the #1002 review comment on accepted_note_mutation_runner create.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/deps/services.py

@@ -706,6 +706,10 @@ async def get_note_content_mutation_service(
                 disable_permalinks=app_config.disable_permalinks,
                 update_permalinks_on_move=app_config.update_permalinks_on_move,
             ),
+            # Local filesystem is the source of truth: reject a create when the
+            # target file already exists on disk but is not yet indexed (#1002
+            # review), rather than diverging DB/search from the file.
+            verify_storage_absent_on_create=True,
         ),
         content_freshener=LocalCurrentNoteContentFreshener(
             entity_repository=entity_repository,

src/basic_memory/indexing/accepted_note_mutation_runner.py

@@ -29,6 +29,7 @@
 )
 from basic_memory.models import Entity, NoteContent, Project
 from basic_memory.repository import NoteContentRepository
+from basic_memory.services.exceptions import EntityAlreadyExistsError
 from basic_memory.repository.accepted_note_search_repository import AcceptedNoteSearchRepository
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.runtime import (
@@ -290,6 +291,14 @@ class AcceptedNoteMutationDependencies:
     write_repositories: AcceptedNoteWriteRepositories
     clock: AcceptedNoteMutationClock
     move_policy: AcceptedNoteMutationMovePolicy
+    # Trigger: local runtimes where the filesystem is the source of truth.
+    # Why: a DB-first create over a file that exists on disk but is not yet
+    #   indexed would commit new DB/search rows while the file keeps old content;
+    #   the next watcher pass then overwrites the DB with the stale file content,
+    #   silently losing the write. Cloud reconciles object storage during
+    #   materialization, so it keeps DB-first acceptance.
+    # Outcome: local creates reject the conflict up front (409) instead.
+    verify_storage_absent_on_create: bool = False
 
 
 def accepted_note_integrity_rejection(error: IntegrityError) -> AcceptedNoteMutationRejection:
@@ -451,9 +460,14 @@ async def _run_accepted_note_create(
         prepared_write = await prepare_accepted_note_create(
             preparer,
             request.data,
-            check_storage_exists=False,
+            check_storage_exists=dependencies.verify_storage_absent_on_create,
             session=session,
         )
+    except EntityAlreadyExistsError as error:
+        # An unindexed file already occupies this path (local source-of-truth
+        # runtimes only). Reject instead of committing DB state that the next
+        # watcher pass would overwrite with the stale file content.
+        reject_accepted_note_mutation(AcceptedNoteMutationRejectKind.conflict, str(error))
     except (ParseError, ValueError) as error:
         reject_accepted_note_mutation(AcceptedNoteMutationRejectKind.bad_request, str(error))
 

tests/api/v2/test_knowledge_router.py

@@ -386,6 +386,39 @@ async def test_create_entity_conflict_returns_409(client: AsyncClient, v2_projec
     assert response.json()["detail"] == expected_detail
 
 
+@pytest.mark.asyncio
+async def test_create_entity_rejects_existing_unindexed_file(
+    client: AsyncClient, v2_project_url, project_config
+):
+    """A create over a file that exists on disk but is not indexed returns 409.
+
+    Regression for the #1002 review: local creates must not commit DB/search
+    rows that diverge from on-disk content, which the next watcher pass would
+    restore (silently losing the write). The local runtime keeps the storage
+    existence check enabled, so the create is rejected up front.
+    """
+    file_path = project_config.home / "conflict" / "UnindexedNote.md"
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    original = "---\ntitle: UnindexedNote\ntype: note\n---\n\nPre-existing on-disk content\n"
+    file_path.write_text(original, encoding="utf-8")
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/entities",
+        json={
+            "title": "UnindexedNote",
+            "directory": "conflict",
+            "note_type": "note",
+            "content_type": "text/markdown",
+            "content": "New content from the create request",
+        },
+        params={"fast": False},
+    )
+
+    assert response.status_code == 409
+    # The on-disk file must be untouched: no divergence, no silent overwrite.
+    assert file_path.read_text(encoding="utf-8") == original
+
+
 @pytest.mark.asyncio
 async def test_create_entity_returns_content(client: AsyncClient, file_service, v2_project_url):
     """Test creating an entity always returns file content with frontmatter."""