superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/compliance/retention.py

@@ -17,7 +17,7 @@ import json
 import logging
 import sqlite3
 from datetime import datetime, timezone
-from typing import Any, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -45,6 +45,7 @@ CREATE TABLE IF NOT EXISTS retention_rules (
 _ACTION_LIFECYCLE = {"archive": "archived", "tombstone": "archived"}
 _TOMBSTONE_ACTIONS = frozenset({"tombstone"})
 _VALID_ACTIONS = ("archive", "tombstone", "notify")
+_SUPPORTED_APPLIES_TO = frozenset({"scope", "fact_type", "signal_type", "session_id"})
 
 _FACTS_TABLE_CHECK = """
 SELECT name FROM sqlite_master
@@ -59,8 +60,9 @@ class RetentionEngine:
     The engine can identify expired facts and enforce deletion.
     """
 
-    def __init__(self, db: sqlite3.Connection) -> None:
+    def __init__(self, db: sqlite3.Connection, *, autocommit: bool = True) -> None:
         self._db = db
+        self._autocommit = autocommit
         self._ensure_table()
 
     # ------------------------------------------------------------------
@@ -84,7 +86,12 @@ class RetentionEngine:
         ):
             if col not in cols:
                 self._db.execute(f"ALTER TABLE retention_rules ADD COLUMN {ddl}")
-        self._db.commit()
+        self._commit_if_owned()
+
+    def _commit_if_owned(self) -> None:
+        """Commit only when this engine owns the transaction boundary."""
+        if self._autocommit:
+            self._db.commit()
 
     def _has_facts_table(self) -> bool:
         """Check if atomic_facts table exists in the database."""
@@ -131,7 +138,7 @@ class RetentionEngine:
             "VALUES (?, ?, ?, ?)",
             (profile_id, rule_name, days, description),
         )
-        self._db.commit()
+        self._commit_if_owned()
         logger.info(
             "Added retention rule '%s' (%d days) to profile '%s'",
             rule_name, days, profile_id,
@@ -149,7 +156,7 @@ class RetentionEngine:
             "WHERE profile_id = ? AND rule_name = ?",
             (profile_id, rule_name),
         )
-        self._db.commit()
+        self._commit_if_owned()
         logger.info(
             "Removed retention rule '%s' from profile '%s'",
             rule_name, profile_id,
@@ -205,14 +212,22 @@ class RetentionEngine:
         """
         if action not in _VALID_ACTIONS:
             raise ValueError(f"action must be one of {_VALID_ACTIONS}")
+        selectors = applies_to or {}
+        if not isinstance(selectors, dict):
+            raise ValueError("applies_to must be an object")
+        unsupported = set(selectors) - _SUPPORTED_APPLIES_TO
+        if unsupported:
+            raise ValueError(
+                "unsupported applies_to selectors: " + ", ".join(sorted(unsupported))
+            )
         cur = self._db.execute(
             "INSERT OR REPLACE INTO retention_rules "
             "(profile_id, rule_name, days, description, framework, action, applies_to) "
             "VALUES (?, ?, ?, ?, ?, ?, ?)",
             (profile_id, name, int(retention_days), "", framework, action,
-             json.dumps(applies_to or {})),
+             json.dumps(selectors, sort_keys=True)),
         )
-        self._db.commit()
+        self._commit_if_owned()
         logger.info(
             "Created retention rule '%s' (%dd, %s/%s) for profile '%s'",
             name, retention_days, framework, action, profile_id,
@@ -237,7 +252,7 @@ class RetentionEngine:
             "DELETE FROM retention_rules WHERE profile_id = ? AND rule_name = ?",
             (profile_id, name),
         )
-        self._db.commit()
+        self._commit_if_owned()
         return cur.rowcount > 0
 
     # ------------------------------------------------------------------
@@ -287,6 +302,23 @@ class RetentionEngine:
     # ------------------------------------------------------------------
 
     def enforce(self, profile_id: str) -> dict[str, Any]:
+        """Atomically enforce all rules for one profile."""
+        if not self._autocommit and not self._db.in_transaction:
+            self._db.execute("BEGIN")
+        savepoint = "slm_retention_profile"
+        self._db.execute(f"SAVEPOINT {savepoint}")
+        try:
+            result = self._enforce_uncommitted(profile_id)
+            self._db.execute(f"RELEASE SAVEPOINT {savepoint}")
+            if self._autocommit:
+                self._db.commit()
+            return result
+        except Exception:
+            self._db.execute(f"ROLLBACK TO SAVEPOINT {savepoint}")
+            self._db.execute(f"RELEASE SAVEPOINT {savepoint}")
+            raise
+
+    def _enforce_uncommitted(self, profile_id: str) -> dict[str, Any]:
         """Enforce every retention rule for a profile, honoring each action.
 
         For each rule, facts in the profile older than its retention_days are
@@ -312,19 +344,43 @@ class RetentionEngine:
         if not rules or not self._has_facts_table():
             return result
 
+        fact_columns = {
+            row[1] for row in self._db.execute("PRAGMA table_info(atomic_facts)").fetchall()
+        }
+        selector_columns = sorted(_SUPPORTED_APPLIES_TO & fact_columns)
+        selected_columns = ["fact_id", "created_at", *selector_columns]
         rows = self._db.execute(
-            "SELECT fact_id, created_at FROM atomic_facts WHERE profile_id = ?",
+            f"SELECT {', '.join(selected_columns)} FROM atomic_facts "
+            "WHERE profile_id = ?",
             (profile_id,),
         ).fetchall()
+        facts = [dict(zip(selected_columns, row, strict=True)) for row in rows]
 
         affected: set[str] = set()
         for rule in rules:
             action = rule.get("action", "archive")
             days = rule.get("retention_days", rule.get("days", 0))
-            expired = [
-                str(r[0]) for r in rows
-                if r[1] and self._age_in_days(r[1]) > days
-            ]
+            selectors = rule.get("applies_to") or {}
+            if set(selectors) - set(selector_columns):
+                logger.warning(
+                    "Retention rule %r skipped unsupported/unavailable selectors: %s",
+                    rule.get("name"),
+                    sorted(set(selectors) - set(selector_columns)),
+                )
+                continue
+            expired = []
+            for fact in facts:
+                created_at = fact.get("created_at")
+                if not created_at or self._age_in_days(created_at) <= days:
+                    continue
+                matches = True
+                for field, expected in selectors.items():
+                    accepted = expected if isinstance(expected, list) else [expected]
+                    if fact.get(field) not in accepted:
+                        matches = False
+                        break
+                if matches:
+                    expired.append(str(fact["fact_id"]))
             if not expired:
                 continue
             if action == "notify":
@@ -342,18 +398,14 @@ class RetentionEngine:
             )
             if action in _TOMBSTONE_ACTIONS:
                 # Flag purgeable without violating the lifecycle CHECK.
-                try:
-                    self._db.execute(
-                        f"UPDATE atomic_facts SET archive_status = 'tombstoned' "
-                        f"WHERE profile_id = ? AND fact_id IN ({placeholders})",
-                        [profile_id, *expired],
-                    )
-                except Exception:
-                    pass
+                self._db.execute(
+                    f"UPDATE atomic_facts SET archive_status = 'tombstoned' "
+                    f"WHERE profile_id = ? AND fact_id IN ({placeholders})",
+                    [profile_id, *expired],
+                )
             result["archived" if action == "archive" else "tombstoned"] += len(expired)
             affected.update(expired)
 
-        self._db.commit()
         result["affected_ids"] = sorted(affected)
         result["deleted_count"] = result["tombstoned"]  # legacy alias
         logger.info(

package/src/superlocalmemory/compliance/scheduler.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import logging
 import sqlite3
 import threading
+from pathlib import Path
 from typing import Any, Optional
 
 from .retention import RetentionEngine
@@ -32,14 +33,20 @@ class RetentionScheduler:
 
     def __init__(
         self,
-        retention_engine: RetentionEngine,
+        retention_engine: RetentionEngine | None = None,
         interval_seconds: int = DEFAULT_INTERVAL_SECONDS,
+        *,
+        db_path: str | Path | None = None,
     ) -> None:
+        if retention_engine is None and db_path is None:
+            raise ValueError("retention_engine or db_path is required")
         self._engine = retention_engine
+        self._db_path = Path(db_path) if db_path is not None else None
         self._interval = interval_seconds
         self._timer: Optional[threading.Timer] = None
         self._running = False
         self._lock = threading.Lock()
+        self._stop_event = threading.Event()
 
     @property
     def is_running(self) -> bool:
@@ -59,6 +66,7 @@ class RetentionScheduler:
         with self._lock:
             if self._running:
                 return
+            self._stop_event.clear()
             self._running = True
             self._schedule_next()
             logger.info(
@@ -66,17 +74,30 @@ class RetentionScheduler:
                 self._interval,
             )
 
-    def stop(self) -> None:
+    def stop(self) -> bool:
         """Stop the background scheduler.
 
-        Cancels the pending timer. Safe to call even if not running.
+        Cancels the pending timer and waits briefly for an active cycle. Safe
+        to call even if not running. Returns False only when an active cycle
+        does not exit within the bounded shutdown window.
         """
+        timer: threading.Timer | None
         with self._lock:
             self._running = False
-            if self._timer is not None:
-                self._timer.cancel()
-                self._timer = None
+            self._stop_event.set()
+            timer = self._timer
+            self._timer = None
+            if timer is not None:
+                timer.cancel()
+        stopped = True
+        if timer is not None and timer is not threading.current_thread():
+            timer.join(timeout=10.0)
+            if timer.is_alive():
+                stopped = False
+                logger.warning("Retention scheduler did not stop within 10 seconds")
+        if stopped:
             logger.info("Retention scheduler stopped")
+        return stopped
 
     # ------------------------------------------------------------------
     # Execution
@@ -103,7 +124,8 @@ class RetentionScheduler:
     def _run_cycle(self) -> None:
         """Run one enforcement cycle, then schedule the next."""
         try:
-            self._execute_cycle()
+            if not self._stop_event.is_set():
+                self._execute_cycle()
         except Exception as exc:
             # Scheduler must not crash — log and continue
             logger.error("Retention scheduler cycle failed: %s", exc)
@@ -117,10 +139,51 @@ class RetentionScheduler:
 
         Discovers all profiles with retention rules and enforces each.
         """
+        if self._db_path is not None:
+            return self._execute_db_path_cycle()
+        if self._engine is None:  # pragma: no cover - constructor invariant
+            raise RuntimeError("retention scheduler has no engine")
+        return self._execute_with_engine(self._engine)
+
+    def _execute_db_path_cycle(self) -> dict[str, Any]:
+        """Discover read-only, then enforce each profile in its own write transaction."""
+        from superlocalmemory.storage.memory_write import memory_read, memory_write
+
+        try:
+            with memory_read(self._db_path) as connection:
+                rows = connection.execute(
+                    "SELECT DISTINCT profile_id FROM retention_rules"
+                ).fetchall()
+                profile_ids = [str(row[0]) for row in rows]
+        except sqlite3.OperationalError:
+            profile_ids = []
+
+        results: list[dict[str, Any]] = []
+        for profile_id in profile_ids:
+            if self._stop_event.is_set():
+                break
+            try:
+                with memory_write(self._db_path) as connection:
+                    result = RetentionEngine(
+                        connection, autocommit=False
+                    ).enforce(profile_id)
+                results.append(result)
+            except Exception as exc:
+                logger.error(
+                    "Retention enforcement failed for profile '%s': %s",
+                    profile_id,
+                    exc,
+                )
+                results.append({"profile_id": profile_id, "error": str(exc)})
+        return {"profiles_processed": len(results), "results": results}
+
+    @staticmethod
+    def _execute_with_engine(engine: RetentionEngine) -> dict[str, Any]:
+        """Enforce one cycle through the supplied short-lived engine."""
         results: list[dict[str, Any]] = []
 
         try:
-            db = self._engine._db
+            db = engine._db
             rows = db.execute(
                 "SELECT DISTINCT profile_id FROM retention_rules"
             ).fetchall()
@@ -130,9 +193,15 @@ class RetentionScheduler:
 
         for profile_id in profile_ids:
             try:
-                result = self._engine.enforce(profile_id)
+                result = engine.enforce(profile_id)
                 results.append(result)
             except Exception as exc:
+                try:
+                    engine._db.rollback()
+                except sqlite3.Error:
+                    logger.exception(
+                        "Retention rollback failed for profile '%s'", profile_id
+                    )
                 logger.error(
                     "Retention enforcement failed for profile '%s': %s",
                     profile_id, exc,

package/src/superlocalmemory/core/actor_context.py

@@ -0,0 +1,166 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Server-derived actor identity for the V4 admission / policy layer.
+
+INVARIANT: ActorContext is ALWAYS constructed from server-authenticated state —
+session tokens, daemon descriptors, profile runtime, RBAC result — NEVER from
+the request body. This constraint is enforced by construction convention and
+audited in OperationPolicyRegistry.evaluate().
+
+Part of SuperLocalMemory V4 | Phase 4: Admission/Policy Layer
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import FrozenSet
+
+# Hosts that indicate a local-machine origin (loopback or in-process).
+_LOCAL_HOSTS: frozenset[str] = frozenset({"127.0.0.1", "::1", "localhost", ""})
+
+
+class ActorRole(str, Enum):
+    """Coarse role for an authenticated principal.
+
+    Roles form a permission lattice: OWNER ≥ ADMIN ≥ MEMBER ≥ VIEWER.
+    SYSTEM is for internal daemon operations; ANONYMOUS marks unauthenticated.
+    """
+
+    OWNER = "owner"
+    ADMIN = "admin"
+    MEMBER = "member"
+    VIEWER = "viewer"
+    SYSTEM = "system"
+    ANONYMOUS = "anonymous"
+
+
+class Transport(str, Enum):
+    """Physical transport through which the operation arrived.
+
+    Used by OperationPolicy.allowed_transports to restrict sensitive operations
+    to known-safe channels (e.g. SCHEMA_MIGRATE only via CLI or INTERNAL).
+    """
+
+    HTTP = "http"
+    MCP = "mcp"
+    CLI = "cli"
+    MESH = "mesh"
+    HOOK = "hook"
+    ADAPTER = "adapter"
+    DASHBOARD = "dashboard"
+    INTERNAL = "internal"  # In-process Python API path
+
+
+@dataclass(frozen=True, slots=True)
+class ActorContext:
+    """Immutable, server-derived actor identity for a single operation.
+
+    All fields come from server-side resolution (session store, RBAC, daemon
+    descriptor). None may originate from the request body. Callers that build
+    an ActorContext from untrusted input violate this contract — the registry
+    evaluator cannot detect this, so the constraint must be audited at the
+    construction site.
+
+    Field semantics
+    ---------------
+    principal_id        Stable user/operator identifier (never a raw token).
+    roles               Coarse permission set; OWNER means unrestricted writes.
+    allowed_profiles    Empty frozenset ≡ unrestricted (all profiles allowed).
+                        Non-empty ≡ explicit allowlist; any other profile is
+                        denied at the coordinator level, not here.
+    active_profile_id   Profile this operation targets.
+    scopes              Scope labels this actor may write to.
+    delegations         Signed capability tokens (future use).
+    transport           Channel through which the call arrived.
+    client_host         Resolved remote address; empty string ≡ in-process.
+    session_token_hash  First 16 hex chars of SHA-256 of session token.
+                        The raw token is NEVER stored here.
+    """
+
+    principal_id: str = ""
+    roles: FrozenSet[ActorRole] = field(
+        default_factory=lambda: frozenset({ActorRole.OWNER})
+    )
+    # empty = all profiles allowed; non-empty = explicit allowlist
+    allowed_profiles: FrozenSet[str] = field(default_factory=frozenset)
+    active_profile_id: str = ""
+    active_profile_generation: int = 0
+    scopes: FrozenSet[str] = field(
+        default_factory=lambda: frozenset({"personal", "project", "shared", "global"})
+    )
+    delegations: tuple[str, ...] = ()
+    transport: Transport = Transport.HTTP
+    client_host: str = ""
+    session_token_hash: str = ""  # SHA-256[:16] of session token — NEVER raw
+
+    # ------------------------------------------------------------------
+    # Derived predicates (pure, no I/O)
+    # ------------------------------------------------------------------
+
+    @property
+    def is_local(self) -> bool:
+        """True when the request originates from the local machine (loopback)."""
+        return self.client_host in _LOCAL_HOSTS
+
+    @property
+    def is_authenticated(self) -> bool:
+        """True when principal_id is non-empty and not an anonymous role."""
+        return self.principal_id != "" and ActorRole.ANONYMOUS not in self.roles
+
+
+# ---------------------------------------------------------------------------
+# Convenience constructors (server-side only — never call from request parsers)
+# ---------------------------------------------------------------------------
+
+def make_internal_owner_context(
+    *,
+    principal_id: str,
+    profile_id: str = "",
+) -> ActorContext:
+    """Build the standard ActorContext for the in-process Python API path.
+
+    Use this when the caller is the daemon itself or an authenticated local
+    operator using the Python SDK directly. The transport is INTERNAL and the
+    client_host is empty (treated as local).
+    """
+    return ActorContext(
+        principal_id=principal_id,
+        roles=frozenset({ActorRole.OWNER}),
+        active_profile_id=profile_id,
+        transport=Transport.INTERNAL,
+        client_host="",
+    )
+
+
+def make_http_actor_context(
+    *,
+    principal_id: str,
+    profile_id: str = "",
+    client_host: str = "",
+    session_token_hash: str = "",
+    roles: FrozenSet[ActorRole] | None = None,
+) -> ActorContext:
+    """Build the standard ActorContext for the HTTP /remember endpoint.
+
+    ``principal_id`` comes from ``_require_write_actor`` (server-side); it is
+    never the raw session token and never from the request body.
+    """
+    return ActorContext(
+        principal_id=principal_id,
+        roles=roles if roles is not None else frozenset({ActorRole.OWNER}),
+        active_profile_id=profile_id,
+        transport=Transport.HTTP,
+        client_host=client_host,
+        session_token_hash=session_token_hash,
+    )
+
+
+__all__ = [
+    "ActorContext",
+    "ActorRole",
+    "Transport",
+    "make_internal_owner_context",
+    "make_http_actor_context",
+]