superlocalmemory 3.8.3 → 3.8.6

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

@@ -7,17 +7,23 @@ Uses V3 MemoryEngine for store/recall. Falls back to direct DB for list/graph.
 """
 import json
 import logging
+import re
+import uuid
 from typing import Optional
 
 from fastapi import APIRouter, HTTPException, Query, Request
 
 from .helpers import (
-    get_db_connection, dict_factory, get_active_profile, get_engine_lazy,
-    SearchRequest, DB_PATH, MEMORY_DIR,
+    SearchRequest,
+    dict_factory,
+    get_active_profile,
+    get_db_connection,
+    get_engine_lazy,
 )
 
 logger = logging.getLogger("superlocalmemory.routes.memories")
 router = APIRouter()
+_IDEMPOTENCY_KEY = re.compile(r"^[A-Za-z0-9._:-]{1,256}$")
 
 # v3.8.3: GENEROUS latency budget for recall. SLM's value is quality recall
 # under heavy multi-agent load, so semantic recall is given ample time to
@@ -56,6 +62,58 @@ def _get_engine(request: Request):
     return get_engine_lazy(request.app.state)
 
 
+def _canonical_mutation_runtime(request: Request):
+    """Return the daemon-owned mutation boundary or fail before queueing work."""
+    runtime = getattr(request.app.state, "canonical_remember_runtime", None)
+    if runtime is None or not runtime.ready:
+        raise HTTPException(503, detail="canonical mutation writer is not ready; retry shortly")
+    return runtime
+
+
+def _mutation_idempotency_key(request: Request) -> str:
+    """Accept a client retry key without making one mandatory for the dashboard."""
+    key = request.headers.get("X-Idempotency-Key", "").strip() or str(uuid.uuid4())
+    if not _IDEMPOTENCY_KEY.fullmatch(key):
+        raise HTTPException(
+            422,
+            detail="X-Idempotency-Key must contain 1-256 safe characters",
+        )
+    return key
+
+
+def _canonical_mutation_error(exc: Exception, detail: str) -> HTTPException:
+    """Map typed mutation failures without leaking SQLite or filesystem detail."""
+    from superlocalmemory.core.remember_runtime import (
+        CanonicalMutationConflict,
+        CanonicalRememberUnavailable,
+    )
+
+    if isinstance(exc, CanonicalMutationConflict):
+        return HTTPException(409, detail=str(exc))
+    if isinstance(exc, CanonicalRememberUnavailable):
+        return HTTPException(
+            503,
+            detail="canonical mutation writer is temporarily unavailable",
+        )
+    return _internal_error(detail)
+
+
+def _mutation_runtime_or_missing_fact(
+    request: Request, engine, profile_id: str, fact_id: str,
+):
+    """Retain the public 404 for a missing fact without creating a local writer."""
+    runtime = getattr(request.app.state, "canonical_remember_runtime", None)
+    if runtime is not None and runtime.ready:
+        return runtime
+    rows = engine._db.execute(
+        "SELECT 1 FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
+        (fact_id, profile_id),
+    )
+    if not rows:
+        raise HTTPException(status_code=404, detail="Memory not found")
+    raise HTTPException(503, detail="canonical mutation writer is not ready; retry shortly")
+
+
 def _authorize_memory_mutation(
     request: Request,
     operation: str,
@@ -725,13 +783,21 @@ async def get_clusters(request: Request):
                 unclustered = 0
 
         conn.close()
-        return {"clusters": clusters, "total_clusters": len(clusters), "unclustered_count": unclustered}
+        return {
+            "clusters": clusters,
+            "total_clusters": len(clusters),
+            "unclustered_count": unclustered,
+        }
     except Exception:
         raise _internal_error("Cluster error")
 
 
 @router.get("/api/clusters/{cluster_id}")
-async def get_cluster_detail(request: Request, cluster_id: str, limit: int = Query(50, ge=1, le=200)):
+async def get_cluster_detail(
+    request: Request,
+    cluster_id: str,
+    limit: int = Query(50, ge=1, le=200),
+):
     """Get detailed view of a specific cluster (scene)."""
     try:
         conn = get_db_connection()
@@ -973,14 +1039,18 @@ async def delete_memory(request: Request, fact_id: str):
             fact_id,
             trusted_actor_id=hook_context["agent_id"],
             source_agent_id="dashboard",
+            canonical_runtime=_mutation_runtime_or_missing_fact(
+                request, engine, _active_profile, fact_id,
+            ),
+            idempotency_key=_mutation_idempotency_key(request),
         )
         if not result.get("ok"):
             raise HTTPException(status_code=404, detail="Memory not found")
         return {"success": True, "deleted": fact_id}
     except HTTPException:
         raise
-    except Exception:
-        raise _internal_error("Delete error")
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Delete error")
 
 
 @router.post("/api/memories/{fact_id}/forget")
@@ -992,56 +1062,25 @@ async def forget_memory(request: Request, fact_id: str):
     The fact's payload is ALSO copied into ``memory_archive`` so a
     future ``slm restore`` can bring it back.
     """
-    import json as _json
     engine, active_profile, hook_context = _authorize_memory_mutation(
         request, "delete", fact_id,
+        run_pre_hook=False,
     )
     try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        cursor.execute(
-            "SELECT fact_id, content, importance, confidence, "
-            "       canonical_entities_json, embedding, created_at "
-            "FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
-            (fact_id, active_profile),
+        engine._hooks.run_pre("delete", hook_context)
+        result = _canonical_mutation_runtime(request).archive_fact(
+            active_profile,
+            fact_id,
+            idempotency_key=_mutation_idempotency_key(request),
         )
-        row = cursor.fetchone()
-        if not row:
-            conn.close()
+        if not result.get("ok"):
             raise HTTPException(status_code=404, detail="Memory not found")
-        # Archive copy — payload_json small enough for the canonical row.
-        payload = {
-            "fact_id": row["fact_id"],
-            "content": row["content"],
-            "canonical_entities_json": row.get("canonical_entities_json"),
-            "importance": row.get("importance"),
-            "confidence": row.get("confidence"),
-            "created_at": row.get("created_at"),
-        }
-        from datetime import datetime, timezone
-        archived_at = datetime.now(timezone.utc).isoformat()
-        import uuid as _uuid
-        cursor.execute(
-            "INSERT INTO memory_archive "
-            "(archive_id, fact_id, profile_id, payload_json, archived_at, reason) "
-            "VALUES (?, ?, ?, ?, ?, ?)",
-            (str(_uuid.uuid4()), fact_id, active_profile,
-             _json.dumps(payload), archived_at, "user_forget_dashboard"),
-        )
-        cursor.execute(
-            "UPDATE atomic_facts SET archive_status = 'archived' "
-            "WHERE fact_id = ?",
-            (fact_id,),
-        )
-        conn.commit()
-        conn.close()
         engine._hooks.run_post("delete", hook_context)
-        return {"success": True, "fact_id": fact_id, "archived_at": archived_at}
+        return {"success": True, "fact_id": fact_id, "archived_at": result["archived_at"]}
     except HTTPException:
         raise
-    except Exception:
-        raise _internal_error("Forget error")
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Forget error")
 
 
 @router.post("/api/memories/{fact_id}/merge")
@@ -1056,6 +1095,7 @@ async def merge_memory(request: Request, fact_id: str):
     """
     engine, active_profile, hook_context = _authorize_memory_mutation(
         request, "delete", fact_id,
+        run_pre_hook=False,
     )
     try:
         body = await request.json()
@@ -1067,50 +1107,26 @@ async def merge_memory(request: Request, fact_id: str):
             raise HTTPException(400, "'into' exceeds 200-char limit")
         if kept == fact_id:
             raise HTTPException(400, "Cannot merge a fact into itself")
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        # Both must belong to the active profile.
-        cursor.execute(
-            "SELECT fact_id FROM atomic_facts "
-            "WHERE fact_id IN (?, ?) AND profile_id = ?",
-            (fact_id, kept, active_profile),
-        )
-        found = {r["fact_id"] for r in cursor.fetchall()}
-        if fact_id not in found or kept not in found:
-            conn.close()
-            raise HTTPException(
-                404,
-                "Both fact_ids must exist in the active profile",
-            )
-        from datetime import datetime, timezone
-        merged_at = datetime.now(timezone.utc).isoformat()
-        cursor.execute(
-            "INSERT INTO memory_merge_log "
-            "(kept_fact_id, merged_fact_id, profile_id, reason, merged_at) "
-            "VALUES (?, ?, ?, ?, ?)",
-            (kept, fact_id, active_profile,
-             "user_merge_dashboard", merged_at),
-        )
-        cursor.execute(
-            "UPDATE atomic_facts "
-            "SET merged_into = ?, archive_status = 'archived' "
-            "WHERE fact_id = ?",
-            (kept, fact_id),
+        engine._hooks.run_pre("delete", hook_context)
+        result = _canonical_mutation_runtime(request).merge_fact(
+            active_profile,
+            fact_id,
+            kept,
+            idempotency_key=_mutation_idempotency_key(request),
         )
-        conn.commit()
-        conn.close()
+        if not result.get("ok"):
+            raise HTTPException(404, "Both fact_ids must exist in the active profile")
         engine._hooks.run_post("delete", hook_context)
         return {
             "success": True,
             "merged": fact_id,
             "into": kept,
-            "merged_at": merged_at,
+            "merged_at": result["merged_at"],
         }
     except HTTPException:
         raise
-    except Exception:
-        raise _internal_error("Merge error")
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Merge error")
 
 
 @router.patch("/api/memories/{fact_id}")
@@ -1136,14 +1152,16 @@ async def edit_memory(request: Request, fact_id: str):
             new_content,
             trusted_actor_id=hook_context["agent_id"],
             source_agent_id="dashboard",
+            canonical_runtime=_canonical_mutation_runtime(request),
+            idempotency_key=_mutation_idempotency_key(request),
         )
         if not result.get("ok"):
             raise HTTPException(status_code=404, detail="Memory not found")
         return {"success": True, "fact_id": fact_id, "content": new_content}
     except HTTPException:
         raise
-    except Exception:
-        raise _internal_error("Edit error")
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Edit error")
 
 
 _VALID_SCOPES = ("personal", "shared", "global")
@@ -1159,7 +1177,6 @@ async def set_memory_scope(request: Request, fact_id: str):
     belong to the active profile (a caller cannot re-scope another profile's
     fact). This is the write side of multi-scope sharing from the dashboard.
     """
-    import json as _json
     try:
         body = await request.json()
         scope = (body.get("scope") or "").strip().lower()
@@ -1180,26 +1197,30 @@ async def set_memory_scope(request: Request, fact_id: str):
         if scope != "shared":
             shared_list = []
 
-        engine, active_profile, _ctx = _authorize_memory_mutation(
+        engine, active_profile, hook_context = _authorize_memory_mutation(
             request, "update", fact_id, run_pre_hook=False,
         )
-        # Ownership check: the fact must belong to the active profile.
-        rows = engine._db.execute(
-            "SELECT 1 FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
-            (fact_id, active_profile),
+        if scope in {"shared", "global"}:
+            from superlocalmemory.access.rbac import Permission
+            from superlocalmemory.server.rbac_enforce import require_permission
+
+            require_permission(request, Permission.SHARE, profile=active_profile)
+        engine._hooks.run_pre("update", hook_context)
+        result = _canonical_mutation_runtime(request).set_fact_scope(
+            active_profile,
+            fact_id,
+            scope,
+            shared_list,
+            idempotency_key=_mutation_idempotency_key(request),
         )
-        if not rows:
+        if not result.get("ok"):
             raise HTTPException(404, detail="Memory not found in this profile")
-
-        engine._db.update_fact(fact_id, {
-            "scope": scope,
-            "shared_with": _json.dumps(shared_list),
-        }, profile_id=active_profile)
+        engine._hooks.run_post("update", hook_context)
         return {
             "success": True, "fact_id": fact_id, "scope": scope,
             "shared_with": shared_list, "active_profile": active_profile,
         }
     except HTTPException:
         raise
-    except Exception:
-        raise _internal_error("Scope update error")
+    except Exception as exc:
+        raise _canonical_mutation_error(exc, "Scope update error")

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

@@ -90,7 +90,9 @@ def _get_broker(request: Request):
     secret = getattr(broker, "_shared_secret", None)
     if secret:
         client_host = request.client.host if request.client else ""
-        if client_host not in ("127.0.0.1", "::1", "localhost"):
+        from superlocalmemory.server.loopback import is_loopback as _is_loopback_host
+
+        if not _is_loopback_host(client_host):
             import hmac
 
             from superlocalmemory.core.security_primitives import verify_install_token
@@ -261,7 +263,10 @@ def _mesh_read_model(records: list[dict]) -> tuple[list[dict], list[dict]]:
             "stale_at": stale_at.isoformat(),
             "expires_at": expires_at.isoformat(),
         }
-        if str(record.get("host") or "").lower() in _LOOPBACK_HOSTS:
+        # display-only — not an auth decision; is_loopback() handles IPv4-mapped forms
+        # such as "::ffff:127.0.0.1" that _LOOPBACK_HOSTS misses.
+        from superlocalmemory.server.loopback import is_loopback as _is_loopback
+        if _is_loopback(str(record.get("host") or "").lower()):
             local.append(normalized)
         else:
             remote.append(normalized)

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

@@ -25,6 +25,7 @@ from .helpers import (
     delete_profile_from_db,
     _load_profiles_json, _save_profiles_json,
 )
+from superlocalmemory.storage.memory_write import memory_write
 from superlocalmemory.server.profile_runtime import (
     commit_daemon_profile_switch,
     get_profile_runtime,
@@ -250,28 +251,26 @@ async def delete_profile(name: str, request: Request):
         # profile being deleted (not the active one).
         from superlocalmemory.server.rbac_enforce import require_manage as _rbac_manage
         _rbac_manage(request, profile=name)
-        # Move data to default before deleting (bypasses CASCADE)
-        conn = get_db_connection()
-        cursor = conn.cursor()
+        # Move data to default before deleting (bypasses CASCADE).
+        # memory_write: write lock + busy_timeout — two UPDATEs are atomic.
         moved = 0
-        try:
-            cursor.execute(
-                "UPDATE atomic_facts SET profile_id = 'default' WHERE profile_id = ?",
-                (name,),
-            )
-            moved = cursor.rowcount
-        except Exception:
-            pass
-        try:
-            cursor.execute(
-                "UPDATE memories SET profile_id = 'default' WHERE profile_id = ?",
-                (name,),
-            )
-            moved += cursor.rowcount
-        except Exception:
-            pass
-        conn.commit()
-        conn.close()
+        with memory_write(DB_PATH) as conn:
+            try:
+                cur = conn.execute(
+                    "UPDATE atomic_facts SET profile_id = 'default' WHERE profile_id = ?",
+                    (name,),
+                )
+                moved = cur.rowcount
+            except Exception:
+                pass
+            try:
+                cur2 = conn.execute(
+                    "UPDATE memories SET profile_id = 'default' WHERE profile_id = ?",
+                    (name,),
+                )
+                moved += cur2.rowcount
+            except Exception:
+                pass
 
         # Delete from BOTH stores
         delete_profile_from_db(name)

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

@@ -158,7 +158,6 @@ def _require_authority_over_user(request: Request, target_user_id: str) -> None:
     shares at least one workspace on which the admin holds MANAGE.
     """
     from superlocalmemory.access.rbac import Permission
-    from superlocalmemory.server.rbac_enforce import resolve_principal
 
     principal = resolve_principal(request)
     if principal["kind"] == "owner":

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

@@ -19,6 +19,7 @@ from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
 
 from superlocalmemory.server.route_mutations import authorize_route_mutation
+from superlocalmemory.storage.memory_write import memory_read, memory_write
 
 from .helpers import DB_PATH, get_active_profile
 
@@ -36,15 +37,9 @@ class PinRequest(BaseModel):
 
 @contextmanager
 def _db():
-    """Context-managed DB connection with WAL + busy_timeout."""
-    conn = sqlite3.connect(str(DB_PATH))
-    conn.execute("PRAGMA journal_mode=WAL")
-    conn.execute("PRAGMA busy_timeout=5000")
-    conn.row_factory = sqlite3.Row
-    try:
+    """Yield a short-lived query-only snapshot for tier dashboard reads."""
+    with memory_read(DB_PATH) as conn:
         yield conn
-    finally:
-        conn.close()
 
 
 def _validate_profile(profile_id: str) -> str:
@@ -154,21 +149,20 @@ async def pin_fact_route(
         fact_id=body.fact_id,
     )
 
-    with _db() as conn:
-        try:
+    # memory_write: process write lock + busy_timeout.
+    # SELECT + INSERT + lifecycle update are atomic inside the same connection.
+    try:
+        with memory_write(DB_PATH) as conn:
             # Verify fact exists in this profile
-            c = conn.cursor()
-            c.execute(
+            if conn.execute(
                 "SELECT fact_id FROM atomic_facts "
                 "WHERE fact_id = ? AND profile_id = ?",
                 (body.fact_id, profile_id),
-            )
-            if c.fetchone() is None:
+            ).fetchone() is None:
                 raise HTTPException(
                     status_code=404,
                     detail=f"Fact {body.fact_id[:8]}... not found",
                 )
-
             now = datetime.now(UTC).isoformat()
             conn.execute(
                 "INSERT OR REPLACE INTO pinned_facts "
@@ -180,16 +174,15 @@ async def pin_fact_route(
             set_fact_lifecycle_zone(
                 conn, [body.fact_id], "active", profile_id=profile_id,
             )
-            conn.commit()
-            authorization.complete()
-            return {"success": True, "message": f"Fact {body.fact_id[:8]}... pinned"}
-        except HTTPException:
-            raise
-        except Exception as exc:
-            logger.error("pin_fact failed: %s", exc, exc_info=True)
-            raise HTTPException(
-                status_code=500, detail="Failed to pin fact",
-            ) from None
+        authorization.complete()
+        return {"success": True, "message": f"Fact {body.fact_id[:8]}... pinned"}
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error("pin_fact failed: %s", exc, exc_info=True)
+        raise HTTPException(
+            status_code=500, detail="Failed to pin fact",
+        ) from None
 
 
 @router.post("/api/tiers/unpin")
@@ -213,17 +206,17 @@ async def unpin_fact_route(
         fact_id=body.fact_id,
     )
 
-    with _db() as conn:
-        try:
+    # memory_write: process write lock + busy_timeout.
+    try:
+        with memory_write(DB_PATH) as conn:
             conn.execute(
                 "DELETE FROM pinned_facts WHERE fact_id = ? AND profile_id = ?",
                 (body.fact_id, profile_id),
             )
-            conn.commit()
-            authorization.complete()
-            return {"success": True, "unpinned": True}
-        except Exception as exc:
-            logger.error("unpin_fact failed: %s", exc, exc_info=True)
-            raise HTTPException(
-                status_code=500, detail="Failed to unpin fact",
-            ) from None
+        authorization.complete()
+        return {"success": True, "unpinned": True}
+    except Exception as exc:
+        logger.error("unpin_fact failed: %s", exc, exc_info=True)
+        raise HTTPException(
+            status_code=500, detail="Failed to unpin fact",
+        ) from None

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

@@ -13,11 +13,10 @@ from __future__ import annotations
 import logging
 import re
 import sqlite3
-from typing import Any
 
 from fastapi import APIRouter, Query
 from fastapi.responses import JSONResponse
-from superlocalmemory.server.routes.helpers import DB_PATH, get_active_profile
+from superlocalmemory.server.routes.helpers import DB_PATH, get_active_profile, get_read_connection
 
 logger = logging.getLogger(__name__)
 
@@ -65,8 +64,7 @@ async def get_timeline(
     if not DB_PATH.exists():
         return {"range": range, "group_by": group_by, "count": 0, "events": [], "total_available": 0, "offset": 0}
 
-    conn = sqlite3.connect(str(DB_PATH))
-    conn.row_factory = sqlite3.Row
+    conn = get_read_connection(DB_PATH)
 
     try:
         start_date = conn.execute("SELECT datetime('now', ?)", (modifier,)).fetchone()[0]