superlocalmemory 4.0.3 → 4.0.5

package/src/superlocalmemory/server/routes/brain.py

@@ -52,6 +52,7 @@ from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from superlocalmemory import __version__
+from superlocalmemory.brain import BrainTruthService
 
 from superlocalmemory.core.security_primitives import (
     redact_secrets,
@@ -327,7 +328,12 @@ def _compute_agent_experience(profile_id: str) -> dict:
     Receipt rows record observation and verification evidence only; this read
     model never alters retrieval, ranking, or model routing.
     """
-    return get_profile_receipt_summary(_learning_db_path(), profile_id)
+    from superlocalmemory.storage.external_evidence import get_profile_external_evidence_summary
+    path = _learning_db_path()
+    return {
+        **get_profile_receipt_summary(path, profile_id),
+        "external_graph_evidence": get_profile_external_evidence_summary(path, profile_id),
+    }
 
 
 def _resolve_phase(signals: int, model_active: bool,
@@ -1125,11 +1131,16 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
     # "default" — the Brain must reflect whichever profile is active.
     profile_id = _authorized_profile(request, profile_id)
     lrn_db = LearningDatabase(_learning_db_path())
+    truth_service = BrainTruthService(
+        memory_db_path=_memory_dir() / "memory.db",
+        learning_db_path=_learning_db_path(),
+    )
 
     (
         preferences, learning, usage, bandit_snap, cache,
         cross_platform, outcomes_preview, evolution, active_clients,
         feedback_loop, source_quality, graph_summary, agent_experience,
+        brain_truth,
     ) = await asyncio.gather(
         asyncio.to_thread(_compute_preferences, profile_id),
         asyncio.to_thread(_compute_learning_status, profile_id, lrn_db),
@@ -1147,6 +1158,7 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
         asyncio.to_thread(_compute_source_quality, profile_id),
         asyncio.to_thread(_compute_graph_summary, profile_id),
         asyncio.to_thread(_compute_agent_experience, profile_id),
+        asyncio.to_thread(truth_service.snapshot, profile_id),
         return_exceptions=True,
     )
 
@@ -1208,6 +1220,14 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
             "source_quality": source_quality,
             "graph": graph_summary,
             "agent_experience": agent_experience,
+            # Additive v4.0.5 contract.  Keep the preceding legacy keys for
+            # existing dashboard/API clients; new clients should render this
+            # one shared, unavailable-aware snapshot.
+            "brain_truth": _ok(brain_truth, {
+                "availability": "unavailable",
+                "source": "BrainTruth service unavailable",
+                "control_plane": "observation_only",
+            }),
             "source": "local durable stores + ephemeral session registry",
         },
         "evolution_preview": _ok(evolution, {

package/src/superlocalmemory/server/routes/memories.py

@@ -1182,9 +1182,9 @@ async def merge_memory(request: Request, fact_id: str):
         raise _canonical_mutation_error(exc, "Merge error")
 
 
-@router.patch("/api/memories/{fact_id}")
+@router.patch("/api/memories/{fact_id}", status_code=202)
 async def edit_memory(request: Request, fact_id: str):
-    """Edit the content of a specific memory (atomic fact)."""
+    """Propose an immutable, review-required correction for one memory."""
     try:
         body = await request.json()
         new_content = (body.get("content") or "").strip()
@@ -1210,13 +1210,139 @@ async def edit_memory(request: Request, fact_id: str):
         )
         if not result.get("ok"):
             raise HTTPException(status_code=404, detail="Memory not found")
-        return {"success": True, "fact_id": fact_id, "content": new_content}
+        if result.get("unchanged"):
+            return {"success": True, "fact_id": fact_id, "content": new_content, "unchanged": True}
+        correction = result["correction_case"]
+        return {
+            "success": True,
+            "fact_id": fact_id,
+            "predecessor_fact_id": result["predecessor_fact_id"],
+            "successor_fact_id": result["successor_fact_id"],
+            "correction_case": correction,
+            "review_required": True,
+            "status": "proposed",
+        }
     except HTTPException:
         raise
     except Exception as exc:
         raise _canonical_mutation_error(exc, "Edit error")
 
 
+@router.post("/api/corrections/{case_id}/{action}")
+async def review_correction(request: Request, case_id: str, action: str):
+    """Apply, reject, or roll back an active-profile correction case.
+
+    The caller authenticates through the daemon boundary.  It cannot select a
+    profile, fact scope, or trust tier; the canonical writer rechecks all of
+    those fields in its one SQLite transaction.
+    """
+    try:
+        body = await request.json()
+        if action not in {"apply", "reject", "rollback"}:
+            raise HTTPException(422, detail="action must be apply, reject, or rollback")
+        expected_version = body.get("expected_version") if isinstance(body, dict) else None
+        if not isinstance(expected_version, int) or isinstance(expected_version, bool):
+            raise HTTPException(422, detail="expected_version must be a non-negative integer")
+        if expected_version < 0:
+            raise HTTPException(422, detail="expected_version must be a non-negative integer")
+        event_valid_until = body.get("event_valid_until") if isinstance(body, dict) else None
+        if event_valid_until is not None and not isinstance(event_valid_until, str):
+            raise HTTPException(422, detail="event_valid_until must be an RFC3339 timestamp")
+        if event_valid_until is not None and action != "apply":
+            raise HTTPException(422, detail="event_valid_until is permitted only for apply")
+        engine, active_profile, hook_context = _authorize_memory_mutation(
+            request, "update", case_id, run_pre_hook=False
+        )
+        result = _canonical_mutation_runtime(request).transition_correction(
+            active_profile,
+            case_id,
+            action=action,
+            expected_version=expected_version,
+            actor_id=hook_context["agent_id"],
+            event_valid_until=event_valid_until,
+            idempotency_key=_mutation_idempotency_key(request),
+        )
+        if not result.get("ok"):
+            raise HTTPException(404, detail="Correction case not found")
+        if action in {"apply", "rollback"}:
+            from superlocalmemory.core.mutations import purge_profile_context_cache
+
+            purge_profile_context_cache(engine, active_profile)
+        engine._hooks.run_post("update", hook_context)
+        return {"success": True, "correction_case": result}
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Correction review error")
+
+
+def _correction_case_response(case) -> dict[str, object]:
+    """Return review metadata only; correction ledgers never contain fact text."""
+    return {
+        "case_id": case.case_id,
+        "profile_id": case.profile_id,
+        "scope": case.scope,
+        "predecessor_fact_id": case.predecessor_fact_id,
+        "successor_fact_id": case.successor_fact_id,
+        "reason_code": case.reason_code,
+        "status": case.status,
+        "version": case.version,
+        "created_at": case.created_at,
+        "updated_at": case.updated_at,
+        "reviewed_at": case.reviewed_at,
+        "applied_at": case.applied_at,
+        "system_effective_at": case.system_effective_at,
+        "event_valid_from": case.event_valid_from,
+        "event_valid_until": case.event_valid_until,
+    }
+
+
+def _correction_store_for(engine, active_profile: str):
+    from superlocalmemory.storage.correction_cases import CorrectionCaseStore
+
+    return CorrectionCaseStore(
+        engine._db.db_path,
+        is_profile_active=lambda candidate: candidate == active_profile,
+        # Read operations never invoke this callback; writes use the daemon's
+        # canonical runtime, which derives the authenticated actor separately.
+        is_actor_trusted=lambda _actor: False,
+    )
+
+
+@router.get("/api/corrections")
+async def list_corrections(request: Request, limit: int = 100):
+    """List bounded review metadata for the active owning profile."""
+    try:
+        engine, active_profile, _context = _authorize_memory_mutation(
+            request, "update", "correction-list", run_pre_hook=False
+        )
+        cases = _correction_store_for(engine, active_profile).list_cases(active_profile, limit=limit)
+        return {"success": True, "corrections": [_correction_case_response(case) for case in cases]}
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Correction list error")
+
+
+@router.get("/api/corrections/{case_id}")
+async def get_correction(request: Request, case_id: str):
+    """Get one active-profile correction case without exposing raw memory text."""
+    try:
+        engine, active_profile, _context = _authorize_memory_mutation(
+            request, "update", case_id, run_pre_hook=False
+        )
+        case = _correction_store_for(engine, active_profile).get_case(case_id)
+        return {"success": True, "correction": _correction_case_response(case)}
+    except HTTPException:
+        raise
+    except Exception as exc:
+        from superlocalmemory.storage.correction_cases import CorrectionNotFoundError
+
+        if isinstance(exc, CorrectionNotFoundError):
+            raise HTTPException(404, detail="Correction case not found") from exc
+        raise _canonical_mutation_error(exc, "Correction lookup error")
+
+
 _VALID_SCOPES = ("personal", "shared", "global")
 
 

package/src/superlocalmemory/storage/_migration_internals.py

@@ -147,6 +147,12 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M040_agent_experience_receipts as _M040,
 )
+from superlocalmemory.storage.migrations import (
+    M041_external_evidence_receipts as _M041,
+)
+from superlocalmemory.storage.migrations import (
+    M042_correction_case_ledger as _M042,
+)
 
 # Emit under the runner's logger name so operational log filters that key on
 # "superlocalmemory.storage.migration_runner" keep matching after this split.
@@ -195,6 +201,8 @@ _MODULES = {
     _M038.NAME: _M038,
     _M039.NAME: _M039,
     _M040.NAME: _M040,
+    _M041.NAME: _M041,
+    _M042.NAME: _M042,
 }
 
 # Exact historical DDL fingerprints whose resulting schema is intentionally

package/src/superlocalmemory/storage/_schema_version.py

@@ -21,9 +21,9 @@ import sqlite3
 from pathlib import Path
 
 #: Highest schema_version this runner can write.  Matches the trailing serial
-#: of the latest migration (M040).  Increment when adding new migrations or
+#: of the latest migration (M042).  Increment when adding new migrations or
 #: table-level breaking changes.
-SUPPORTED_SCHEMA_VERSION: int = 40
+SUPPORTED_SCHEMA_VERSION: int = 42
 
 
 class SchemaVersionError(RuntimeError):

package/src/superlocalmemory/storage/agent_experience.py

@@ -245,17 +245,29 @@ class AgentExperienceStore:
             turn_count = conn.execute(
                 "DELETE FROM cognitive_turn_receipts WHERE profile_id=?", (profile_id,)
             ).rowcount
+            external_count = 0
+            has_external = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' "
+                "AND name='external_evidence_receipts'"
+            ).fetchone() is not None
+            if has_external:
+                external_count = conn.execute(
+                    "DELETE FROM external_evidence_receipts WHERE profile_id=?", (profile_id,)
+                ).rowcount
+            receipt_tables = ["agent_experiences", "cognitive_turn_receipts"]
+            if has_external:
+                receipt_tables.append("external_evidence_receipts")
             residue = sum(
                 int(
                     conn.execute(
                         f"SELECT COUNT(*) FROM {table} WHERE profile_id=?", (profile_id,)
                     ).fetchone()[0]
                 )
-                for table in ("agent_experiences", "cognitive_turn_receipts")
+                for table in receipt_tables
             )
             if residue:
                 raise RuntimeError("learning receipt erasure left profile residue")
-            return experience_count + turn_count
+            return experience_count + turn_count + external_count
 
         return self._write(erase)
 
@@ -422,7 +434,7 @@ def purge_profile_receipts(
             for row in conn.execute(
                 "SELECT name FROM sqlite_master WHERE type='table' "
                 "AND name IN ('agent_experiences', 'cognitive_turn_receipts', "
-                "'agent_receipt_profile_closures')"
+                "'agent_receipt_profile_closures', 'external_evidence_receipts')"
             )
         }
     if not tables:
@@ -431,6 +443,16 @@ def purge_profile_receipts(
         "agent_experiences", "cognitive_turn_receipts", "agent_receipt_profile_closures"
     }
     if tables != expected:
+        if tables == expected | {"external_evidence_receipts"}:
+            from superlocalmemory.storage.migrations import M041_external_evidence_receipts as m041
+
+            with sqlite3.connect(path) as conn:
+                # Erasure needs a valid table, not its optional performance indexes.
+                # A damaged index must never strand profile-scoped evidence.
+                if m041._table_is_valid(conn):
+                    return AgentExperienceStore(
+                        path, is_profile_active=lambda _: True
+                    ).erase_profile(profile_id, close_profile=close_profile)
         raise sqlite3.OperationalError("incomplete Agent Experience receipt schema")
     return AgentExperienceStore(
         path, is_profile_active=lambda _: True
@@ -459,7 +481,7 @@ def get_profile_receipt_summary(
     if not path.exists():
         return unavailable
     try:
-        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=0.5)
+        conn = sqlite3.connect(f"{path.resolve().as_uri()}?mode=ro", uri=True, timeout=0.5)
         try:
             experience = conn.execute(
                 "SELECT COUNT(*) FROM agent_experiences WHERE profile_id=?", (profile_id,)