superlocalmemory 3.7.7 → 3.8.0

package/src/superlocalmemory/server/profile_runtime.py

@@ -6,6 +6,7 @@ import json
 import os
 import tempfile
 import threading
+import time as _time
 from contextlib import contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
@@ -20,6 +21,20 @@ _REQUEST_PROFILE: ContextVar[str | None] = ContextVar(
     "slm_request_profile", default=None,
 )
 
+# Maximum seconds to wait for in-flight operations to drain before a
+# profile switch or engine reconfigure is aborted with HTTP 503.
+# Tests can monkeypatch this module-level value to keep runs fast.
+_DRAIN_TIMEOUT_SECS: float = 5.0
+
+
+class TransitionDrainTimeout(Exception):
+    """Raised when in-flight operations do not drain within _DRAIN_TIMEOUT_SECS.
+
+    The caller (HTTP switch route) maps this to HTTP 503 so the client
+    receives a clear error instead of a silent hang.  After the timeout,
+    `_transitioning` is always reset to False so the daemon stays responsive.
+    """
+
 
 def current_request_profile() -> str | None:
     """Return the immutable profile snapshot admitted for this request."""
@@ -61,6 +76,18 @@ class ProfileRuntime:
             self._active_operations += 1
             return self._snapshot
 
+    def _try_acquire_operation_nowait(self) -> ProfileSnapshot | None:
+        """Non-blocking acquire: returns None immediately when a transition is pending.
+
+        Used by cooperative background maintenance tasks so they never block the
+        drain window of a pending profile switch.
+        """
+        with self._condition:
+            if self._transitioning:
+                return None
+            self._active_operations += 1
+            return self._snapshot
+
     def release_operation(self) -> None:
         with self._condition:
             if self._active_operations <= 0:
@@ -77,20 +104,64 @@ class ProfileRuntime:
         finally:
             self.release_operation()
 
+    @contextmanager
+    def operation_nowait(self) -> Iterator[ProfileSnapshot | None]:
+        """Cooperatively skip when a profile transition is pending.
+
+        Background maintenance tasks that do NOT mutate profile-scoped engine
+        state (cache warmup, health probes) MUST use this instead of
+        ``operation()`` so they never hold the drain window hostage.
+
+        Yields ``None`` (preempted — skip this work cycle) when a switch is
+        already in progress.  Yields a :class:`ProfileSnapshot` and holds the
+        lease normally when no transition is pending.
+
+        The caller is responsible for checking ``if snap is None: return``.
+
+        Unlike ``operation()``, this context manager never blocks — it either
+        admits immediately or preempts immediately.
+        """
+        snapshot = self._try_acquire_operation_nowait()
+        acquired = snapshot is not None
+        try:
+            yield snapshot
+        finally:
+            if acquired:
+                self.release_operation()
+
     def transition(
         self,
         target_profile: str,
         commit: Callable[[ProfileSnapshot, str], None],
     ) -> ProfileSnapshot:
-        """Drain admitted operations, commit, then publish a new generation."""
+        """Drain admitted operations, commit, then publish a new generation.
+
+        Raises TransitionDrainTimeout if in-flight operations do not drain
+        within _DRAIN_TIMEOUT_SECS.  The flag is always reset on timeout so
+        the daemon remains responsive (no permanent _transitioning=True wedge).
+        """
+        deadline = _time.monotonic() + _DRAIN_TIMEOUT_SECS
         with self._condition:
             while self._transitioning:
                 self._condition.wait()
             if target_profile == self._snapshot.profile_id:
                 return self._snapshot
             self._transitioning = True
-            while self._active_operations:
-                self._condition.wait()
+            while self._active_operations > 0:
+                remaining = deadline - _time.monotonic()
+                if remaining <= 0:
+                    # Reset before raising — never leave the daemon wedged.
+                    self._transitioning = False
+                    self._condition.notify_all()
+                    raise TransitionDrainTimeout(
+                        f"Profile switch to '{target_profile}' timed out after "
+                        f"{_DRAIN_TIMEOUT_SECS:.0f}s: {self._active_operations} "
+                        "in-flight operation(s) did not drain. "
+                        "Try again when no active requests are in progress."
+                    )
+                # Use short sleep slices so we react quickly to notifications
+                # and to timeout expiry without busy-spinning.
+                self._condition.wait(timeout=min(remaining, 0.25))
             previous = self._snapshot
 
         try:
@@ -111,13 +182,26 @@ class ProfileRuntime:
             return self._snapshot
 
     def reconfigure(self, commit: Callable[[ProfileSnapshot], None]) -> ProfileSnapshot:
-        """Run a same-profile engine transition behind the operation barrier."""
+        """Run a same-profile engine transition behind the operation barrier.
+
+        Raises TransitionDrainTimeout if in-flight operations do not drain
+        within _DRAIN_TIMEOUT_SECS (same semantics as transition()).
+        """
+        deadline = _time.monotonic() + _DRAIN_TIMEOUT_SECS
         with self._condition:
             while self._transitioning:
                 self._condition.wait()
             self._transitioning = True
-            while self._active_operations:
-                self._condition.wait()
+            while self._active_operations > 0:
+                remaining = deadline - _time.monotonic()
+                if remaining <= 0:
+                    self._transitioning = False
+                    self._condition.notify_all()
+                    raise TransitionDrainTimeout(
+                        f"Engine reconfigure timed out after {_DRAIN_TIMEOUT_SECS:.0f}s: "
+                        f"{self._active_operations} in-flight operation(s) did not drain."
+                    )
+                self._condition.wait(timeout=min(remaining, 0.25))
             snapshot = self._snapshot
 
         try:
@@ -362,12 +446,44 @@ class ProfileRuntimeMiddleware:
             raise
         scope.setdefault("state", {})["profile_snapshot"] = snapshot
         token = _REQUEST_PROFILE.set(snapshot.profile_id)
+
+        # The operation lease guards the SYNCHRONOUS route work that produces
+        # the response — not the streaming of its body. A long-lived SSE body
+        # would otherwise hold the lease for its whole lifetime and make every
+        # profile switch time out during drain (HTTP 503):
+        #   * /events/stream runs `while True: await sleep(1)` FOREVER while a
+        #     dashboard tab is open;
+        #   * /api/v3/chat/stream streams LLM tokens for up to 120s.
+        # Release the lease the instant the response starts. By then the route
+        # handler has finished its engine work and returned its Response
+        # (FastAPI buffers normal responses before sending response.start).
+        # Streaming generators that still need the engine (chat recall) already
+        # re-acquire their own short-lived lease internally, and /events/stream
+        # only reads the EventBus DB — neither depends on this outer lease.
+        released = False
+
+        def _release_lease_once() -> None:
+            # Single-task coroutine chain — a plain flag is sufficient; the
+            # underlying release_operation() is lock-guarded and idempotent-safe
+            # only via this guard, so never call it twice.
+            nonlocal released
+            if not released:
+                released = True
+                runtime.release_operation()
+
+        async def _send(message) -> None:
+            if message.get("type") == "http.response.start":
+                _release_lease_once()
+            await send(message)
+
         try:
-            await self._app(scope, receive, send)
+            await self._app(scope, receive, _send)
         finally:
             _REQUEST_PROFILE.reset(token)
+            # Safety net: a request that errors before emitting response.start
+            # (or an ASGI app that never sends one) must still release its lease.
             # Release is lock-only and must not itself be cancellation-prone.
-            runtime.release_operation()
+            _release_lease_once()
 
 
 __all__ = [
@@ -375,6 +491,7 @@ __all__ = [
     "ProfileRuntime",
     "ProfileRuntimeMiddleware",
     "ProfileSnapshot",
+    "TransitionDrainTimeout",
     "bind_profile_runtime",
     "commit_daemon_profile_switch",
     "current_request_profile",

package/src/superlocalmemory/server/rbac_enforce.py

@@ -0,0 +1,142 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 — RBAC / teams (C3)
+
+"""RBAC enforcement boundary for HTTP routes.
+
+This is the single place that turns "who is calling" + "what are they trying to
+do" into an allow/deny decision, on top of the existing machine-auth layer
+(write_identity). It is deliberately small so every mutation route calls the
+same code path — the research warning was explicit: an RBAC layer that is
+defined but not consistently called is worse than none.
+
+Principal model
+---------------
+* **user**  — a logged-in dashboard user (valid session token). Always enforced
+  against their role on the active profile.
+* **owner** — the machine operator (already proved machine auth via
+  write_identity; no user session). In personal mode the owner bypasses RBAC
+  (all permissions). When the org turns on *require_login* (company mode) the
+  owner bypass is disabled and a user session is mandatory.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, Request
+
+from superlocalmemory.access.rbac import Permission, Role, permissions_for_role
+
+_SESSION_HEADER = "X-SLM-User-Session"
+_SESSION_COOKIE = "slm_session"
+
+OWNER_PRINCIPAL = {
+    "kind": "owner",
+    "user_id": "owner",
+    "username": "owner",
+    "display_name": "Machine Owner",
+}
+
+
+def get_rbac_engine(app_state: Any) -> Any | None:
+    return getattr(app_state, "rbac", None)
+
+
+def _session_token(request: Request) -> str:
+    tok = request.headers.get(_SESSION_HEADER, "")
+    if tok:
+        return tok
+    try:
+        return request.cookies.get(_SESSION_COOKIE, "") or ""
+    except Exception:
+        return ""
+
+
+def resolve_principal(request: Request) -> dict:
+    """Resolve the caller to a user (valid session) or the machine owner."""
+    rbac = get_rbac_engine(request.app.state)
+    token = _session_token(request)
+    if rbac is not None and token:
+        user = rbac.resolve_session(token)
+        if user:
+            return {"kind": "user", **user}
+    return dict(OWNER_PRINCIPAL)
+
+
+def _active_profile() -> str:
+    from superlocalmemory.server.routes.helpers import get_active_profile
+
+    return get_active_profile()
+
+
+def require_permission(
+    request: Request,
+    permission: Permission,
+    *,
+    profile: str | None = None,
+) -> dict:
+    """Authorize ``permission`` on ``profile`` (default: active profile).
+
+    Returns the principal on success. Raises 401 when a login is required but
+    absent, or 403 when the user's role does not grant the permission.
+    """
+    rbac = get_rbac_engine(request.app.state)
+    principal = resolve_principal(request)
+    require_login = bool(rbac is not None and rbac.require_login())
+    prof = profile or _active_profile()
+
+    if principal["kind"] == "owner":
+        # The machine operator is root — they always retain MANAGE (they have
+        # shell access to the box regardless), so company mode can never lock
+        # administration out of the dashboard. require_login only gates the
+        # owner's DATA operations, forcing per-user login for read/write/etc.
+        if require_login and permission != Permission.MANAGE:
+            raise HTTPException(
+                401,
+                detail="Login required: this workspace enforces per-user access.",
+            )
+        return principal  # personal mode — operator is owner
+
+    # Logged-in user: always enforced against their role.
+    if rbac is not None and rbac.has_permission(principal["user_id"], prof, permission):
+        return principal
+    raise HTTPException(
+        403,
+        detail=(
+            f"Your role does not allow '{permission.value}' on this workspace."
+        ),
+    )
+
+
+def require_manage(request: Request, *, profile: str | None = None) -> dict:
+    """Guard for user/role administration (MANAGE permission)."""
+    return require_permission(request, Permission.MANAGE, profile=profile)
+
+
+def principal_info(request: Request) -> dict:
+    """Rich identity for /whoami: principal + role + effective permissions on
+    the active profile. Never raises — used by the dashboard to render UI."""
+    rbac = get_rbac_engine(request.app.state)
+    principal = resolve_principal(request)
+    prof = _active_profile()
+    info = {
+        "kind": principal["kind"],
+        "user_id": principal["user_id"],
+        "username": principal["username"],
+        "display_name": principal.get("display_name", principal["username"]),
+        "profile": prof,
+        "rbac_active": bool(rbac is not None and rbac.user_count() > 0),
+        "require_login": bool(rbac is not None and rbac.require_login()),
+    }
+    if principal["kind"] == "owner":
+        # Owner has every permission (personal mode) unless login is required.
+        info["role"] = "owner"
+        info["permissions"] = [p.value for p in Permission]
+        return info
+    role = rbac.get_role(principal["user_id"], prof) if rbac is not None else None
+    info["role"] = role.value if role else None
+    info["permissions"] = (
+        [p.value for p in permissions_for_role(role)] if role else []
+    )
+    return info

package/src/superlocalmemory/server/recall_health.py

@@ -124,15 +124,36 @@ def run_health_tick(engine, state: RecallHealth, *, probe: str = DEFAULT_PROBE,
 
     Mutates and returns ``state``. Never raises — a timed-out / failing recall
     marks the path unhealthy instead of propagating.
+
+    Uses ``operation_nowait()`` when a runtime is supplied so that a pending
+    profile switch is not blocked by the health-probe recall.  If a transition
+    is in progress the tick is skipped entirely — the next scheduled tick will
+    re-warm once the switch has committed.
     """
     state.checks += 1
 
     # Tier 1: re-warm. A real full-fusion recall keeps the graph page cache hot
     # and the embedder resident.
+    # Cooperative preemption: use operation_nowait() so a pending profile switch
+    # is not held hostage by a slow full-fusion recall (2–10s with fast=False).
     try:
-        lease = runtime.operation() if runtime is not None else nullcontext()
-        with lease:
-            resp = engine.recall(probe, limit=3, fast=False)
+        if runtime is not None:
+            lease = runtime.operation_nowait()
+        else:
+            lease = nullcontext()
+        with lease as _snap:
+            if runtime is not None and _snap is None:
+                # A profile transition is in progress — skip this tick so we
+                # do not hold the drain window.  Health state is unchanged;
+                # the next tick fires after the switch commits.
+                log.debug(
+                    "recall-health: tick skipped — profile transition in progress"
+                )
+                return state
+            # fast=True: a health probe must release its operation lease well
+            # within the 5s profile-switch drain window (fast=False is 2-10s and
+            # would make every profile switch time out while a tick is in flight).
+            resp = engine.recall(probe, limit=3, fast=True)
     except Exception as exc:
         state.healthy = False
         state.consecutive_failures += 1

package/src/superlocalmemory/server/recall_serializer.py

@@ -24,6 +24,7 @@ import re
 from typing import Any
 
 from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
+from superlocalmemory.retrieval.temporal_frame import relative_age, temporal_frame
 
 
 # ---------------------------------------------------------------------------
@@ -190,9 +191,13 @@ def serialize_recall_response(
         is the evidence-floor signal lifted from the response (additive).
     """
     memory_map = memory_map or {}
+    # T-inject: one shared "now" so every result's age label is consistent.
+    from datetime import datetime as _dt, timezone as _tz
+    _now = _dt.now(_tz.utc)
     raw: list[dict] = []
     for r in (response.results or [])[:limit]:
         fact = r.fact
+        _created = getattr(fact, "created_at", "") or ""
         fact_type = getattr(fact, "fact_type", None)
         lifecycle = getattr(fact, "lifecycle", None)
         raw.append({
@@ -225,7 +230,10 @@ def serialize_recall_response(
                 if lifecycle is not None and hasattr(lifecycle, "value")
                 else (lifecycle or ""),
             "access_count": getattr(fact, "access_count", 0),
-            "created_at": getattr(fact, "created_at", "") or "",
+            "created_at": _created,
+            # T-inject: human-relative age so consumers (and the LLM) can
+            # weigh recency without doing date math. "" when undated.
+            "age_label": relative_age(_created, _now),
             "evidence_chain": list(getattr(r, "evidence_chain", []) or []),
         })
 
@@ -241,6 +249,12 @@ def serialize_recall_response(
 
 def recall_response_metadata(response: Any) -> dict:
     """Return Score Contract v2 response metadata for transport envelopes."""
+    # T-inject: a one-line temporal frame anchoring the result set to "now"
+    # and its age span, so time-blind LLMs get an explicit recency signal.
+    _timestamps = [
+        getattr(getattr(r, "fact", None), "created_at", "") or ""
+        for r in (getattr(response, "results", None) or [])
+    ]
     return {
         "score_contract_version": getattr(response, "score_contract_version", "2"),
         "calibration_status": getattr(response, "calibration_status", "uncalibrated"),
@@ -248,4 +262,8 @@ def recall_response_metadata(response: Any) -> dict:
         "answer_confidence": getattr(response, "answer_confidence", None),
         "abstained": bool(getattr(response, "abstained", False)),
         "abstention_reason": getattr(response, "abstention_reason", None),
+        "temporal_frame": temporal_frame(_timestamps),
+        # Q2b: thematic community summary (pure pass-through; computed upstream
+        # in the engine where DB access is available). None on most recalls.
+        "thematic_context": getattr(response, "community_context", None),
     }

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

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later — see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com
+
+"""Progressive-abstraction read API (Wave Q3).
+
+Exposes the abstraction hierarchy so the dashboard can browse it and drill
+down to source atoms:
+
+  GET /api/v3/abstraction/persona      — the per-profile persona roll-up
+  GET /api/v3/abstraction/communities  — community summaries (Q2)
+  GET /api/v3/abstraction/sources      — drill-down (node -> source atoms)
+
+Read-only, profile-scoped (Rule 01), direct sqlite3 (Rule 06). All handlers
+fail-soft: a missing DB or table returns an empty payload, never a 500.
+"""
+
+from __future__ import annotations
+
+import logging
+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
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v3/abstraction", tags=["abstraction"])
+
+
+class _ReadDB:
+    """Adapt a raw sqlite3 connection to the .execute(...) -> list contract
+    the read-only builder methods expect (matches DatabaseManager.execute)."""
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def execute(self, sql: str, params: tuple = ()) -> list:
+        return self._conn.execute(sql, params).fetchall()
+
+
+def _conn() -> sqlite3.Connection | None:
+    if not DB_PATH.exists():
+        return None
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+@router.get("/persona")
+def get_persona(profile: str = Query("")) -> JSONResponse:
+    pid = profile or get_active_profile()
+    conn = _conn()
+    if conn is None:
+        return JSONResponse({"profile": pid, "persona": None})
+    try:
+        from superlocalmemory.core.progressive_abstraction import ProgressiveAbstraction
+
+        persona = ProgressiveAbstraction(_ReadDB(conn)).get_persona(pid)
+        return JSONResponse({"profile": pid, "persona": persona})
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("persona read failed: %s", exc)
+        return JSONResponse({"profile": pid, "persona": None})
+    finally:
+        conn.close()
+
+
+@router.get("/communities")
+def get_communities(profile: str = Query("")) -> JSONResponse:
+    pid = profile or get_active_profile()
+    conn = _conn()
+    if conn is None:
+        return JSONResponse({"profile": pid, "communities": []})
+    try:
+        from superlocalmemory.core.community_summary import CommunitySummaryBuilder
+
+        summaries = CommunitySummaryBuilder(_ReadDB(conn)).get_summaries(pid)
+        return JSONResponse({"profile": pid, "communities": summaries})
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("communities read failed: %s", exc)
+        return JSONResponse({"profile": pid, "communities": []})
+    finally:
+        conn.close()
+
+
+@router.get("/sources")
+def get_sources(
+    profile: str = Query(""), node: str = Query("persona"),
+) -> JSONResponse:
+    pid = profile or get_active_profile()
+    conn = _conn()
+    empty: dict[str, Any] = {
+        "node_id": node, "node_type": "unknown", "communities": [], "fact_ids": [],
+    }
+    if conn is None:
+        return JSONResponse({"profile": pid, "sources": empty})
+    try:
+        from superlocalmemory.core.progressive_abstraction import ProgressiveAbstraction
+
+        node_val: Any = node
+        if node != "persona":
+            try:
+                node_val = int(node)
+            except (ValueError, TypeError):
+                node_val = node
+        sources = ProgressiveAbstraction(_ReadDB(conn)).get_sources(pid, node_val)
+        return JSONResponse({"profile": pid, "sources": sources})
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("sources read failed: %s", exc)
+        return JSONResponse({"profile": pid, "sources": empty})
+    finally:
+        conn.close()