refactor(core): structure campaign — collapse seams, honest types, typed boundaries (#1054)

Closes #1053. Eight clusters over three integration waves: Protocol/Default/factory towers collapsed, object-typed protocol properties narrowed with coercion deleted, seven _session_scope copies consolidated into db.scoped_session, checkpoint state pairs collapsed into single fail-fast Pydantic models (persisted JSON pinned byte-identical), hand-rolled tagged unions replaced with real unions, dict route boundaries typed (response bytes snapshot-pinned), deps/services.py restored to a composition root. 78 contract changes recorded for the paired cloud adaptation (#1489).

Reviewed by a three-lens adversarial pass (17 findings fixed) plus cross-vendor Claude+Codex review (1 fixed, 1 dispositioned to cloud adaptation). Full unit suite green; ty at main baseline.

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

Author: phernandez

src/basic_memory/api/app.py

@@ -29,7 +29,7 @@
 import logfire
 from basic_memory.cloud.note_content_materialization import drain_pending_materializations
 from basic_memory.config import init_api_logging
-from basic_memory.deps.services import drain_background_tasks
+from basic_memory.index.local_schedulers import drain_background_tasks
 from basic_memory.services.exceptions import EntityAlreadyExistsError
 from basic_memory.services.initialization import initialize_app
 from basic_memory.workspace_context import (

src/basic_memory/api/v2/routers/knowledge_router.py

@@ -997,18 +997,19 @@ async def delete_directory(
         logger.info(f"API v2 request: delete_directory directory='{data.directory}'")
 
         try:
-            status_code, payload = await directory_delete_service.delete_directory(
+            result = await directory_delete_service.delete_directory(
                 project_external_id=project_external_id,
                 directory=data.directory,
             )
+            payload = result.to_response_payload()
             logger.info(
                 f"API v2 response: delete_directory "
-                f"total={payload.get('total_files')}, "
-                f"success={payload.get('successful_deletes')}, "
-                f"failed={payload.get('failed_deletes')}, "
-                f"file_delete_status={payload.get('file_delete_status')}"
+                f"total={payload['total_files']}, "
+                f"success={payload['successful_deletes']}, "
+                f"failed={payload['failed_deletes']}, "
+                f"file_delete_status={payload['file_delete_status']}"
             )
-            return runtime_json_response(status_code=status_code, payload=payload)
+            return runtime_json_response(status_code=result.http_status_code, payload=payload)
 
         except DirectoryDeleteServiceError as error:
             logger.error(f"Error deleting directory: {error.detail}")

src/basic_memory/api/v2/routers/project_router.py

@@ -24,10 +24,10 @@
     ProjectIndexCommandDep,
     ProjectIndexObserverDep,
     ProjectExternalIdPathDep,
-    ProjectIndexRouteRequest,
     SessionDep,
     SessionMakerDep,
 )
+from basic_memory.index.local_project import ProjectIndexRouteRequest
 from basic_memory.schemas import ProjectIndexStatusResponse
 from basic_memory.models import Project
 from basic_memory.repository.project_repository import ProjectRepository
@@ -38,7 +38,11 @@
     ProjectInfoResponse,
     ProjectStatusResponse,
 )
-from basic_memory.schemas.v2 import ProjectResolveRequest, ProjectResolveResponse
+from basic_memory.schemas.v2 import (
+    ProjectIndexResponse,
+    ProjectResolveRequest,
+    ProjectResolveResponse,
+)
 from basic_memory.utils import normalize_project_path, generate_permalink
 
 router = APIRouter(prefix="/projects", tags=["project_management-v2"])
@@ -231,14 +235,14 @@ async def synchronize_projects(
         raise HTTPException(status_code=400, detail=str(e))
 
 
-@router.post("/{project_id}/index")
+@router.post("/{project_id}/index", response_model=ProjectIndexResponse)
 async def index_project(
     project_index_command: ProjectIndexCommandDep,
     project_config: ProjectConfigV2ExternalDep,
     project_internal_id: ProjectExternalIdPathDep,
     force_full: bool = Query(False, description="Request a full project index run"),
     run_in_background: bool = Query(True, description="Run in background"),
-):
+) -> ProjectIndexResponse:
     """Run project-wide indexing through the event-index coordinator."""
     return await project_index_command.index_project(
         ProjectIndexRouteRequest(

src/basic_memory/cli/commands/command_utils.py

@@ -33,7 +33,7 @@ def run_with_cleanup(coro: Coroutine[Any, Any, T]) -> T:
     # at CLI import time — only when a command actually runs (#886).
     from basic_memory import db
     from basic_memory.cloud.note_content_materialization import drain_pending_materializations
-    from basic_memory.deps.services import drain_background_tasks
+    from basic_memory.index.local_schedulers import drain_background_tasks
 
     async def _with_cleanup() -> T:
         try:

src/basic_memory/cloud/directory_deletes.py

@@ -14,6 +14,7 @@
 from basic_memory import db
 from basic_memory.indexing.directory_delete_runner import (
     DirectoryDeleteAcceptanceRequest,
+    DirectoryDeleteAcceptedResult,
     DirectoryDeleteRejected,
     DirectoryDeleteRejection,
     DirectoryDeleteRuntime,
@@ -65,8 +66,12 @@ async def delete_directory(
         *,
         project_external_id: str,
         directory: str,
-    ) -> tuple[int, dict[str, object]]:
-        """Delete directory entities immediately and queue file cleanup in the background."""
+    ) -> DirectoryDeleteAcceptedResult:
+        """Delete directory entities immediately and queue file cleanup in the background.
+
+        The typed result carries the route status (``http_status_code``) and the
+        existing response contract (``to_response_payload``).
+        """
         request = DirectoryDeleteAcceptanceRequest(
             project_external_id=project_external_id,
             directory=directory,
@@ -102,8 +107,7 @@ async def delete_directory(
                 sorted(accepted.relation_cleanup_entity_ids)
             )
 
-        status_code = 500 if result.file_delete_status == "failed" else 200
-        return status_code, result.to_response_payload()
+        return result
 
     @staticmethod
     def normalize_directory_path(directory: str) -> str:

src/basic_memory/cloud/project_deletes.py

@@ -8,12 +8,10 @@
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
-from basic_memory.indexing.project_delete_acceptance import (
-    ProjectDeleteAcceptedProject,
-    ProjectDeleteAcceptedResult,
-)
+from basic_memory.indexing.project_delete_acceptance import ProjectDeleteAcceptedResult
 from basic_memory.models import Project
 from basic_memory.runtime.jobs import RuntimeJobId, RuntimeProjectDeleteJobRequest
+from basic_memory.schemas.project_info import ProjectItem
 
 
 class ProjectDeleteAcceptanceError(Exception):
@@ -106,7 +104,13 @@ async def delete_project(
                 project_path=project.path,
                 delete_notes=request.delete_notes,
             )
-            old_project = ProjectDeleteAcceptedProject.from_source(project)
+            old_project = ProjectItem(
+                id=project.id,
+                external_id=project.external_id,
+                name=project.name,
+                path=project.path,
+                is_default=project.is_default or False,
+            )
             project.is_active = False
             await session.commit()
 

src/basic_memory/db.py

@@ -139,31 +139,49 @@ def get_scoped_session_factory(
 @asynccontextmanager
 async def scoped_session(
     session_maker: async_sessionmaker[AsyncSession],
+    session: AsyncSession | None = None,
 ) -> AsyncGenerator[AsyncSession, None]:
     """
     Get a scoped session with proper lifecycle management.
 
+    This is the one shared session-scope seam for services and indexing code.
+    It covers both real usage variants:
+
+    - ``session`` provided: the caller-owned session is yielded unchanged and
+      the caller keeps commit/rollback ownership (composed multi-step writes).
+    - ``session`` omitted: a fresh task-scoped session is opened that commits
+      on success, rolls back on error, and always closes.
+
     Args:
         session_maker: Session maker to create scoped sessions from
+        session: Optional caller-owned session to reuse instead of opening one
     """
+    # Trigger: the caller already owns a transaction and passes its session in.
+    # Why: nested scopes must not commit or roll back mid-way through the
+    # caller's composed write; transaction ownership stays with the opener.
+    # Outcome: yield the session untouched and let the outermost scope finish it.
+    if session is not None:
+        yield session
+        return
+
     factory = get_scoped_session_factory(session_maker)
-    session = factory()
+    owned_session = factory()
     try:
         # Only enable foreign keys for SQLite (Postgres has them enabled by default)
         # Detect database type from session's bind (engine) dialect
-        engine = session.get_bind()
+        engine = owned_session.get_bind()
         dialect_name = engine.dialect.name
 
         if dialect_name == "sqlite":
-            await session.execute(text("PRAGMA foreign_keys=ON"))
+            await owned_session.execute(text("PRAGMA foreign_keys=ON"))
 
-        yield session
-        await session.commit()
+        yield owned_session
+        await owned_session.commit()
     except Exception:
-        await session.rollback()
+        await owned_session.rollback()
         raise
     finally:
-        await session.close()
+        await owned_session.close()
         await factory.remove()
 
 

src/basic_memory/deps/__init__.py

@@ -101,7 +101,6 @@
     ProjectIndexSchedulerDep,
     get_project_index_command,
     ProjectIndexCommandDep,
-    ProjectIndexRouteRequest,
     get_search_reindex_scheduler,
     SearchReindexSchedulerDep,
     get_search_service,
@@ -258,7 +257,6 @@
     "ProjectIndexSchedulerDep",
     "get_project_index_command",
     "ProjectIndexCommandDep",
-    "ProjectIndexRouteRequest",
     "get_search_reindex_scheduler",
     "SearchReindexSchedulerDep",
     "get_search_service",