superlocalmemory 3.4.25 → 3.4.31

package/src/superlocalmemory/core/rate_limit.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Layered token-bucket rate limiter.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+
+from superlocalmemory.core.error_envelope import ErrorCode
+
+
+class RateLimitedError(Exception):
+    def __init__(
+        self,
+        layer: str,
+        retry_after_ms: int,
+        message: str | None = None,
+        **extras: object,
+    ) -> None:
+        self.layer = layer
+        self.retry_after_ms = retry_after_ms
+        self.code = ErrorCode.RATE_LIMITED
+        self.extras = extras
+        super().__init__(message or f"{layer} rate limit exceeded")
+
+
+class TokenBucket:
+    __slots__ = ("rate", "capacity", "tokens", "last_refill")
+
+    def __init__(self, rate_per_sec: float, capacity: float | None = None) -> None:
+        self.rate = float(rate_per_sec)
+        self.capacity = float(capacity) if capacity is not None else float(rate_per_sec)
+        self.tokens = self.capacity
+        self.last_refill = time.monotonic()
+
+    def _refill(self, now: float) -> None:
+        delta = now - self.last_refill
+        if delta > 0:
+            self.tokens = min(self.capacity, self.tokens + delta * self.rate)
+            self.last_refill = now
+
+    def can_consume(self, cost: float = 1.0) -> bool:
+        self._refill(time.monotonic())
+        return self.tokens >= cost
+
+    def try_consume(self, cost: float = 1.0) -> bool:
+        now = time.monotonic()
+        self._refill(now)
+        if self.tokens >= cost:
+            self.tokens -= cost
+            return True
+        return False
+
+    def consume(self, cost: float = 1.0) -> None:
+        self.tokens -= cost
+
+    def ms_to_refill(self, cost: float = 1.0) -> int:
+        self._refill(time.monotonic())
+        needed = max(0.0, cost - self.tokens)
+        if self.rate <= 0:
+            return 1_000_000
+        return int((needed / self.rate) * 1000) + 1
+
+
+@dataclass
+class _PidEntry:
+    bucket: TokenBucket
+    last_used: float = field(default_factory=time.monotonic)
+
+
+class LayeredRateLimiter:
+    def __init__(
+        self,
+        *,
+        global_rps: float = 100.0,
+        per_pid_rps: float = 30.0,
+        per_agent_rps: float = 10.0,
+        idle_ttl_s: float = 60.0,
+    ) -> None:
+        self._global = TokenBucket(global_rps)
+        self._per_pid_rps = per_pid_rps
+        self._per_agent_rps = per_agent_rps
+        self._idle_ttl_s = idle_ttl_s
+        self._per_pid: dict[int, _PidEntry] = {}
+        self._per_agent: dict[str, _PidEntry] = {}
+        self._lock = threading.RLock()
+
+    def _sweep(self, now: float) -> None:
+        cutoff = now - self._idle_ttl_s
+        for k in [p for p, e in self._per_pid.items() if e.last_used < cutoff]:
+            del self._per_pid[k]
+        for k in [a for a, e in self._per_agent.items() if e.last_used < cutoff]:
+            del self._per_agent[a]
+
+    def _get_pid(self, pid: int, now: float) -> TokenBucket:
+        entry = self._per_pid.get(pid)
+        if entry is None:
+            entry = _PidEntry(TokenBucket(self._per_pid_rps), now)
+            self._per_pid[pid] = entry
+        entry.last_used = now
+        return entry.bucket
+
+    def _get_agent(self, agent_id: str, now: float) -> TokenBucket:
+        entry = self._per_agent.get(agent_id)
+        if entry is None:
+            entry = _PidEntry(TokenBucket(self._per_agent_rps), now)
+            self._per_agent[agent_id] = entry
+        entry.last_used = now
+        return entry.bucket
+
+    def check_and_consume(self, *, pid: int, agent_id: str | None = None) -> None:
+        """Peek all layers; raise on any reject without touching others.
+
+        On admission, consume one token from each applicable bucket.
+        """
+        with self._lock:
+            now = time.monotonic()
+            self._sweep(now)
+            pid_bucket = self._get_pid(pid, now)
+            agent_bucket = self._get_agent(agent_id, now) if agent_id else None
+            if not self._global.can_consume():
+                raise RateLimitedError(
+                    "global", self._global.ms_to_refill(),
+                )
+            if not pid_bucket.can_consume():
+                raise RateLimitedError(
+                    "per-pid", pid_bucket.ms_to_refill(), pid=pid,
+                )
+            if agent_bucket is not None and not agent_bucket.can_consume():
+                raise RateLimitedError(
+                    "per-agent", agent_bucket.ms_to_refill(), agent=agent_id,
+                )
+            self._global.consume()
+            pid_bucket.consume()
+            if agent_bucket is not None:
+                agent_bucket.consume()
+
+    def per_pid_size(self) -> int:
+        with self._lock:
+            return len(self._per_pid)
+
+    def per_agent_size(self) -> int:
+        with self._lock:
+            return len(self._per_agent)

package/src/superlocalmemory/core/recall_queue.py

@@ -0,0 +1,370 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""DB-backed recall queue — schema, enqueue, claim, complete, poll.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+from superlocalmemory.core.safe_fs import _safe_open_db
+
+
+class QueueTimeoutError(Exception):
+    def __init__(self, request_id: str, elapsed_s: float) -> None:
+        self.request_id = request_id
+        self.elapsed_s = elapsed_s
+        super().__init__(f"poll timed out after {elapsed_s:.2f}s")
+
+
+class QueueCancelledError(Exception):
+    def __init__(self, request_id: str) -> None:
+        self.request_id = request_id
+        super().__init__(f"request {request_id} was cancelled")
+
+
+class DeadLetterError(Exception):
+    def __init__(self, request_id: str, reason: str) -> None:
+        self.request_id = request_id
+        self.reason = reason
+        super().__init__(f"request {request_id}: {reason}")
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS recall_requests (
+    request_id        TEXT    PRIMARY KEY,
+    query_hash        TEXT    NOT NULL,
+    job_type          TEXT    NOT NULL DEFAULT 'recall',
+    idempotency_key   TEXT,
+    session_id        TEXT    NOT NULL DEFAULT '',
+    agent_id          TEXT    NOT NULL DEFAULT '',
+    namespace         TEXT    NOT NULL DEFAULT '',
+    tenant_id         TEXT    NOT NULL DEFAULT '',
+    query             TEXT    NOT NULL DEFAULT '',
+    limit_n           INTEGER NOT NULL DEFAULT 10,
+    mode              TEXT    NOT NULL DEFAULT 'B',
+    priority          TEXT    NOT NULL DEFAULT 'high',
+    weight            INTEGER NOT NULL DEFAULT 70,
+    claim_expires_at  REAL,
+    received          INTEGER NOT NULL DEFAULT 0,
+    completed         INTEGER NOT NULL DEFAULT 0,
+    cancelled         INTEGER NOT NULL DEFAULT 0,
+    dead_letter       INTEGER NOT NULL DEFAULT 0,
+    result_json       TEXT,
+    error_reason      TEXT,
+    subscriber_count  INTEGER NOT NULL DEFAULT 1,
+    last_subscribe_at REAL,
+    created_at        REAL    NOT NULL,
+    worker_pid        INTEGER,
+    worker_create_time INTEGER,
+    worker_progress   TEXT,
+    stall_timeout_s   REAL,
+    cost_usd          REAL    NOT NULL DEFAULT 0.0,
+    CHECK (completed IN (0, 1)),
+    CHECK (cancelled IN (0, 1)),
+    CHECK (dead_letter IN (0, 1)),
+    CHECK (completed + cancelled + dead_letter <= 1),
+    CHECK (NOT (completed = 1 AND result_json IS NULL)),
+    CHECK (subscriber_count >= 0)
+);
+
+CREATE INDEX IF NOT EXISTS idx_recall_visible
+    ON recall_requests(priority, created_at, request_id)
+    WHERE completed = 0 AND cancelled = 0 AND dead_letter = 0;
+
+CREATE INDEX IF NOT EXISTS idx_recall_dedup
+    ON recall_requests(query_hash)
+    WHERE completed = 0 AND cancelled = 0 AND dead_letter = 0;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_recall_idem_key
+    ON recall_requests(job_type, idempotency_key)
+    WHERE idempotency_key IS NOT NULL
+          AND completed = 0 AND cancelled = 0 AND dead_letter = 0;
+"""
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _make_request_id() -> str:
+    return "r-" + uuid.uuid4().hex[:12]
+
+
+def _query_hash(
+    *, session_id: str, agent_id: str, query: str, limit_n: int,
+    mode: str, tenant_id: str,
+) -> str:
+    blob = "||".join((
+        tenant_id, session_id, agent_id, mode, str(limit_n), query,
+    )).encode("utf-8")
+    return hashlib.blake2b(blob, digest_size=16).hexdigest()
+
+
+class RecallQueue:
+    def __init__(self, db_path: Path | str) -> None:
+        self._db_path = Path(db_path)
+        self._lock = threading.RLock()
+        self._conn = _safe_open_db(self._db_path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA synchronous=NORMAL")
+        self._conn.execute("PRAGMA busy_timeout=5000")
+        self._conn.execute("PRAGMA foreign_keys=ON")
+        self._conn.execute("PRAGMA mmap_size=67108864")
+        for stmt in _SCHEMA.strip().split(";"):
+            s = stmt.strip()
+            if s:
+                self._conn.execute(s)
+        self._closed = False
+
+    # ----- schema-level helpers (tests / ops) -----
+    def _raw_execute(self, sql: str, params: Iterable[Any] = ()) -> None:
+        with self._lock:
+            self._conn.execute(sql, tuple(params))
+
+    def _get_row(self, request_id: str) -> Optional[sqlite3.Row]:
+        with self._lock:
+            cur = self._conn.execute(
+                "SELECT * FROM recall_requests WHERE request_id = ?",
+                (request_id,),
+            )
+            return cur.fetchone()
+
+    def _force_cancelled(self, request_id: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                "UPDATE recall_requests SET cancelled=1 WHERE request_id=?",
+                (request_id,),
+            )
+
+    # ----- enqueue -----
+    def enqueue(
+        self,
+        *,
+        query: str,
+        limit_n: int,
+        mode: str,
+        agent_id: str,
+        session_id: str,
+        tenant_id: str = "",
+        namespace: str = "",
+        priority: str = "high",
+        stall_timeout_s: float = 25.0,
+    ) -> str:
+        qhash = _query_hash(
+            session_id=session_id, agent_id=agent_id, query=query,
+            limit_n=limit_n, mode=mode, tenant_id=tenant_id,
+        )
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                cur = self._conn.execute(
+                    "SELECT request_id FROM recall_requests "
+                    "WHERE query_hash = ? AND completed = 0 "
+                    "AND cancelled = 0 AND dead_letter = 0 "
+                    "LIMIT 1",
+                    (qhash,),
+                )
+                existing = cur.fetchone()
+                if existing is not None:
+                    rid = existing["request_id"]
+                    self._conn.execute(
+                        "UPDATE recall_requests "
+                        "SET subscriber_count = subscriber_count + 1, "
+                        "    last_subscribe_at = ? "
+                        "WHERE request_id = ?",
+                        (_now(), rid),
+                    )
+                    self._conn.execute("COMMIT")
+                    return rid
+                rid = _make_request_id()
+                self._conn.execute(
+                    "INSERT INTO recall_requests "
+                    "(request_id, query_hash, job_type, session_id, agent_id, "
+                    " namespace, tenant_id, query, limit_n, mode, priority, "
+                    " weight, created_at, subscriber_count, last_subscribe_at, "
+                    " stall_timeout_s) "
+                    "VALUES (?, ?, 'recall', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)",
+                    (
+                        rid, qhash, session_id, agent_id, namespace, tenant_id,
+                        query, limit_n, mode, priority,
+                        70 if priority == "high" else 30,
+                        _now(), _now(), stall_timeout_s,
+                    ),
+                )
+                self._conn.execute("COMMIT")
+                return rid
+            except Exception:
+                self._conn.execute("ROLLBACK")
+                raise
+
+    def enqueue_job(
+        self,
+        *,
+        job_type: str,
+        idempotency_key: str,
+        agent_id: str,
+        session_id: str,
+        priority: str = "low",
+        stall_timeout_s: float = 40.0,
+        query: str = "",
+    ) -> str:
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                cur = self._conn.execute(
+                    "SELECT request_id FROM recall_requests "
+                    "WHERE job_type = ? AND idempotency_key = ? "
+                    "AND completed = 0 AND cancelled = 0 AND dead_letter = 0 "
+                    "LIMIT 1",
+                    (job_type, idempotency_key),
+                )
+                existing = cur.fetchone()
+                if existing is not None:
+                    self._conn.execute("COMMIT")
+                    return existing["request_id"]
+                rid = _make_request_id()
+                self._conn.execute(
+                    "INSERT INTO recall_requests "
+                    "(request_id, query_hash, job_type, idempotency_key, "
+                    " session_id, agent_id, query, priority, weight, "
+                    " created_at, subscriber_count, last_subscribe_at, "
+                    " stall_timeout_s) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)",
+                    (
+                        rid, idempotency_key, job_type, idempotency_key,
+                        session_id, agent_id, query, priority,
+                        70 if priority == "high" else 30,
+                        _now(), _now(), stall_timeout_s,
+                    ),
+                )
+                self._conn.execute("COMMIT")
+                return rid
+            except Exception:
+                self._conn.execute("ROLLBACK")
+                raise
+
+    # ----- claim / complete / fence -----
+    def claim_pending(
+        self,
+        *,
+        priority: str = "high",
+        stall_timeout_s: float = 25.0,
+    ) -> Optional[dict[str, Any]]:
+        now = _now()
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                cur = self._conn.execute(
+                    "SELECT request_id, received FROM recall_requests "
+                    "WHERE priority = ? "
+                    "AND completed = 0 AND cancelled = 0 AND dead_letter = 0 "
+                    "AND (claim_expires_at IS NULL OR claim_expires_at < ?) "
+                    "ORDER BY created_at, request_id LIMIT 1",
+                    (priority, now),
+                )
+                row = cur.fetchone()
+                if row is None:
+                    self._conn.execute("COMMIT")
+                    return None
+                rid = row["request_id"]
+                received = row["received"] + 1
+                expires = now + stall_timeout_s
+                self._conn.execute(
+                    "UPDATE recall_requests "
+                    "SET received = ?, claim_expires_at = ? "
+                    "WHERE request_id = ?",
+                    (received, expires, rid),
+                )
+                self._conn.execute("COMMIT")
+                out = self._get_row(rid)
+                return dict(out) if out is not None else None
+            except Exception:
+                self._conn.execute("ROLLBACK")
+                raise
+
+    def complete(
+        self, request_id: str, *, received: int, result_json: str,
+    ) -> int:
+        with self._lock:
+            cur = self._conn.execute(
+                "UPDATE recall_requests "
+                "SET completed = 1, result_json = ? "
+                "WHERE request_id = ? AND received = ? "
+                "AND completed = 0 AND cancelled = 0 AND dead_letter = 0",
+                (result_json, request_id, received),
+            )
+            if cur.rowcount == 0:
+                import logging as _log
+                _log.getLogger(__name__).warning(
+                    "fenced out: request_id=%s received=%d (stale or already terminal)",
+                    request_id, received,
+                )
+            return cur.rowcount
+
+    def mark_dead_letter(self, request_id: str, *, reason: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                "UPDATE recall_requests "
+                "SET dead_letter = 1, error_reason = ? "
+                "WHERE request_id = ? AND completed = 0 AND cancelled = 0",
+                (reason, request_id),
+            )
+
+    def unsubscribe(self, request_id: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                "UPDATE recall_requests "
+                "SET subscriber_count = MAX(0, subscriber_count - 1) "
+                "WHERE request_id = ?",
+                (request_id,),
+            )
+
+    # ----- poll with DLQ fast-fail -----
+    _POLL_SCHEDULE = (0.05, 0.1, 0.2, 0.3, 0.5)
+
+    def poll_result(self, request_id: str, *, timeout_s: float) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout_s
+        idx = 0
+        while True:
+            row = self._get_row(request_id)
+            if row is not None:
+                if row["dead_letter"]:
+                    raise DeadLetterError(
+                        request_id,
+                        reason=row["error_reason"] or "max_receives_exceeded",
+                    )
+                if row["cancelled"] and not row["completed"]:
+                    raise QueueCancelledError(request_id)
+                if row["completed"]:
+                    return json.loads(row["result_json"])
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise QueueTimeoutError(request_id, timeout_s)
+            sleep_for = min(
+                self._POLL_SCHEDULE[min(idx, len(self._POLL_SCHEDULE) - 1)],
+                remaining,
+            )
+            time.sleep(sleep_for)
+            idx += 1
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._conn.close()
+        except Exception:
+            pass

package/src/superlocalmemory/core/recall_worker.py

@@ -69,6 +69,8 @@ def _handle_recall(query: str, limit: int, session_id: str = "") -> dict:
 
     results = []
     for r in response.results[:limit]:
+        fact_type = getattr(r.fact, "fact_type", None)
+        lifecycle = getattr(r.fact, "lifecycle", None)
         results.append({
             "fact_id": r.fact.fact_id,
             "memory_id": r.fact.memory_id,
@@ -80,6 +82,10 @@ def _handle_recall(query: str, limit: int, session_id: str = "") -> dict:
             "channel_scores": {
                 k: round(v, 4) for k, v in (r.channel_scores or {}).items()
             },
+            "fact_type": fact_type.value if fact_type and hasattr(fact_type, "value") else "",
+            "lifecycle": lifecycle.value if lifecycle and hasattr(lifecycle, "value") else "",
+            "access_count": getattr(r.fact, "access_count", 0),
+            "evidence_chain": list(getattr(r, "evidence_chain", []) or []),
         })
     return {
         "ok": True,
@@ -87,6 +93,10 @@ def _handle_recall(query: str, limit: int, session_id: str = "") -> dict:
         "query_type": response.query_type,
         "result_count": len(results),
         "retrieval_time_ms": round(response.retrieval_time_ms, 1),
+        "channel_weights": {
+            k: round(v, 3) for k, v in (response.channel_weights or {}).items()
+        },
+        "total_candidates": getattr(response, "total_candidates", 0),
         "results": results,
     }
 

package/src/superlocalmemory/core/safe_fs.py

@@ -0,0 +1,108 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Filesystem safety helpers for SQLite DB open paths.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import stat
+import sys
+from pathlib import Path
+
+
+class SafeFsError(RuntimeError):
+    """Raised when a data-directory or DB-open precondition fails."""
+
+
+_FORBIDDEN_COMPONENTS = (
+    "iCloud Drive", "Mobile Documents", "CloudDocs",
+    "Dropbox", "Google Drive", "OneDrive", "Box Sync",
+    # macOS 13+ canonical cloud-storage mount point. Every modern
+    # Dropbox / OneDrive / Google Drive / Box install on macOS routes
+    # through here, bypassing the brand-name checks above.
+    "Library/CloudStorage",
+)
+
+
+def validate_data_dir(path: Path) -> None:
+    """Refuse paths that live under a cloud-sync folder.
+
+    Cloud-synced directories silently corrupt SQLite WAL files.
+    """
+    resolved = str(path.resolve())
+    lowered = resolved.lower()
+    for comp in _FORBIDDEN_COMPONENTS:
+        if comp.lower() in lowered:
+            raise SafeFsError(
+                f"SLM data directory {resolved} appears to live under "
+                f"{comp!r} — cloud-synced folders are not supported "
+                f"(SQLite WAL corrupts silently on replication). "
+                f"Set SLM_DATA_DIR to a local path such as "
+                f"{Path.home()}/.slm-local"
+            )
+
+
+def _ensure_parent_0700(path: Path) -> None:
+    parent = path.parent
+    if not parent.exists():
+        parent.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "win32":
+        return
+    st = parent.stat()
+    if st.st_uid != os.getuid():
+        raise SafeFsError(
+            f"{parent} is not owned by current user (uid={os.getuid()})"
+        )
+    if (st.st_mode & 0o077) != 0:
+        os.chmod(parent, 0o700)
+
+
+def _safe_open_db(path: Path) -> sqlite3.Connection:
+    """Open a SQLite DB with TOCTOU-tight symlink protection.
+
+    Pattern:
+      1. Enforce parent directory 0700.
+      2. lstat the DB path; refuse if it's already a symlink.
+      3. Open with O_NOFOLLOW to catch a last-moment swap.
+      4. fstat and compare inode with the pre-open lstat.
+      5. Close the fd and let sqlite3.connect reopen by path so WAL
+         and SHM sibling files can be created naturally.
+    """
+    _ensure_parent_0700(path)
+    if sys.platform != "win32":
+        if path.exists():
+            pre_st = os.lstat(str(path))
+            if stat.S_ISLNK(pre_st.st_mode):
+                raise SafeFsError(f"{path} is a symlink — refused")
+            if pre_st.st_uid != os.getuid():
+                raise SafeFsError(f"{path} not owned by current user")
+            if (pre_st.st_mode & 0o077) != 0:
+                os.chmod(str(path), 0o600)
+        else:
+            pre_st = None
+        try:
+            flags = os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW
+            fd = os.open(str(path), flags, 0o600)
+        except OSError as exc:
+            raise SafeFsError(f"Cannot safely open {path}: {exc}") from exc
+        try:
+            post_st = os.fstat(fd)
+            if pre_st is not None and (
+                (pre_st.st_ino, pre_st.st_dev)
+                != (post_st.st_ino, post_st.st_dev)
+            ):
+                raise SafeFsError(
+                    f"{path} changed between lstat and open — refused"
+                )
+        finally:
+            os.close(fd)
+    conn = sqlite3.connect(
+        str(path), isolation_level=None, timeout=5.0, check_same_thread=False,
+    )
+    return conn