superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/mesh/state_sync.py

@@ -1,286 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
-
-"""LWW remote state convergence for the SLM mesh (3c-1).
-
-Convergence guarantee
----------------------
-Leaderless, pull-based, deterministic Last-Writer-Wins.  Every node that
-exchanges deltas converges on the same ``(value, revision, node_id)`` for
-every key.
-
-This is NOT linearizable consensus.  Concurrent writes can interleave; the
-winner is chosen deterministically by a TOTAL ORDER on ``(revision: int,
-node_id: str)``.  Same revision → higher ``node_id`` wins (lexicographic).
-Because the order is total, every node independently computes the same
-winner given the same set of writes.
-
-Backward compatibility
-----------------------
-``set_state`` in the broker never sets ``origin_node``; rows it writes have
-``origin_node = ''`` (the column default added here).  At merge and
-serialization time ``''`` is interpreted as the LOCAL node_id, so existing
-rows participate correctly in the LWW protocol without any change to
-``broker.py``.
-
-Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import logging
-import sqlite3
-from typing import Any
-
-from superlocalmemory.mesh.node_identity import get_node_id
-
-logger = logging.getLogger("superlocalmemory.mesh.state_sync")
-
-# ---------------------------------------------------------------------------
-# Schema migration (additive, idempotent)
-# ---------------------------------------------------------------------------
-
-_ALTER_ORIGIN_NODE = (
-    "ALTER TABLE mesh_state ADD COLUMN origin_node TEXT NOT NULL DEFAULT ''"
-)
-
-
-# ---------------------------------------------------------------------------
-# StateSyncer
-# ---------------------------------------------------------------------------
-
-
-class StateSyncer:
-    """Pull-based LWW convergence helper for the ``mesh_state`` table.
-
-    Designed to be instantiated on-demand (route handler, sync loop); all DB
-    connections are short-lived.  Every operation is fail-soft: errors are
-    logged and the caller never receives an unhandled exception from here.
-    """
-
-    def __init__(self, broker: Any) -> None:
-        self._broker = broker
-        self._db_path: str = str(broker._db_path)
-        # Resolved once; stable for the lifetime of this instance.
-        self._node_id: str = get_node_id(self._db_path)
-        self._ensure_origin_node_column()
-
-    # ------------------------------------------------------------------
-    # Schema bootstrap
-    # ------------------------------------------------------------------
-
-    def _ensure_origin_node_column(self) -> None:
-        """Add ``origin_node`` to ``mesh_state``; no-op if already present."""
-        try:
-            conn = sqlite3.connect(self._db_path, timeout=5.0)
-            try:
-                conn.execute(_ALTER_ORIGIN_NODE)
-                conn.commit()
-            except sqlite3.OperationalError as exc:
-                if "duplicate column" in str(exc).lower():
-                    pass  # Expected on second startup / upgrade
-                else:
-                    logger.error(
-                        "StateSyncer._ensure_origin_node_column: unexpected "
-                        "OperationalError at %s: %s",
-                        self._db_path, exc,
-                    )
-            finally:
-                conn.close()
-        except sqlite3.Error as exc:
-            logger.error(
-                "StateSyncer._ensure_origin_node_column: DB error at %s: %s",
-                self._db_path, exc,
-            )
-
-    # ------------------------------------------------------------------
-    # Internal helpers
-    # ------------------------------------------------------------------
-
-    def _effective_node(self, stored_origin: str) -> str:
-        """Resolve ``origin_node=''`` (BC rows) to this node's id at call time."""
-        return stored_origin if stored_origin else self._node_id
-
-    def _open_conn(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(self._db_path, timeout=5.0)
-        conn.row_factory = sqlite3.Row
-        return conn
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def local_delta(
-        self,
-        profile_id: str = "default",
-        since_revision: int = 0,
-    ) -> list[dict]:
-        """Return rows with ``revision > since_revision`` for a profile.
-
-        The ``node_id`` field in each entry reflects the *effective* node:
-        the stored ``origin_node`` when non-empty, or the local node_id for
-        BC rows written by the broker (``origin_node = ''``).
-
-        Returns ``[]`` on any DB error (fail-soft).
-        """
-        try:
-            conn = self._open_conn()
-            try:
-                rows = conn.execute(
-                    "SELECT key, value, set_by, updated_at,"
-                    " COALESCE(revision, 0) AS revision,"
-                    " COALESCE(origin_node, '') AS origin_node"
-                    " FROM mesh_state"
-                    " WHERE profile_id = ? AND COALESCE(revision, 0) > ?",
-                    (profile_id, int(since_revision)),
-                ).fetchall()
-                return [
-                    {
-                        "key": row["key"],
-                        "value": row["value"],
-                        "set_by": row["set_by"],
-                        "updated_at": row["updated_at"],
-                        "revision": int(row["revision"]),
-                        "node_id": self._effective_node(row["origin_node"]),
-                    }
-                    for row in rows
-                ]
-            finally:
-                conn.close()
-        except sqlite3.Error as exc:
-            logger.error(
-                "StateSyncer.local_delta: DB error at %s: %s",
-                self._db_path, exc,
-            )
-            return []
-
-    def merge_remote(
-        self,
-        profile_id: str,
-        remote_entries: list[dict],
-    ) -> dict:
-        """Merge remote delta entries using deterministic LWW.
-
-        For each entry ``{key, value, set_by, updated_at, revision, node_id}``:
-
-        * If ``(remote_rev, remote_node) > (local_rev, local_node)`` (total
-          order): UPSERT the local row.  The winning ``revision`` is preserved
-          as-is — never incremented — so re-merging the same delta is a no-op
-          (idempotent convergence).
-        * Otherwise: do nothing.
-
-        Returns ``{"applied": N, "skipped": M}``.  Errors per-entry are
-        logged and counted as skipped; they never propagate to the caller.
-        """
-        applied = 0
-        skipped = 0
-        for entry in remote_entries:
-            # Compute a safe log key BEFORE the try so a non-dict entry can
-            # never make the error handler itself raise (audit P0/P2 — the
-            # handler previously called entry.get() on possibly-non-dict).
-            entry_key = entry.get("key") if isinstance(entry, dict) else repr(entry)
-            try:
-                if self._merge_one(profile_id, entry):
-                    applied += 1
-                else:
-                    skipped += 1
-            except sqlite3.Error as exc:
-                logger.error(
-                    "StateSyncer.merge_remote: DB error on key=%r: %s",
-                    entry_key, exc,
-                )
-                skipped += 1
-            except (KeyError, TypeError, ValueError, AttributeError) as exc:
-                logger.error(
-                    "StateSyncer.merge_remote: malformed entry key=%r: %s",
-                    entry_key, exc,
-                )
-                skipped += 1
-        return {"applied": applied, "skipped": skipped}
-
-    def _merge_one(self, profile_id: str, entry: dict) -> bool:
-        """Apply one remote entry if it wins the LWW comparison.
-
-        Returns ``True`` if the local row was updated; ``False`` if local
-        won or the comparison was a tie (same revision, same node_id).
-
-        CRITICAL: ``revision`` is never incremented here.  Preserving the
-        winning revision is what makes convergence idempotent — a second
-        merge of the same delta computes the identical comparison result and
-        takes no action.
-        """
-        # Audit P0/P2: a non-dict entry must never crash the merge.
-        if not isinstance(entry, dict):
-            return False
-        key = str(entry["key"])
-        # Guard: cast revision to int to prevent string lexicographic miscompare
-        # (e.g. "10" < "9" as strings but 10 > 9 as ints).
-        remote_rev: int = int(entry["revision"])
-        remote_node: str = str(entry.get("node_id", "")).strip()
-        # Audit P1: an empty node_id would be stored as origin_node='' and then
-        # re-exported under THIS node's id, rewriting provenance and corrupting
-        # the tie-break. Refuse an entry without a real origin.
-        if not remote_node:
-            return False
-        # Audit P2: never persist a NULL value as the literal string "None".
-        if entry.get("value") is None:
-            return False
-
-        conn = self._open_conn()
-        # Audit P1 (TOCTOU): the read-compare-write MUST be atomic against a
-        # concurrent broker.set_state on the same key. Without a write lock, a
-        # stale local read lets a lower remote revision overwrite a fresher
-        # local write (losing local-highest-revision). BEGIN IMMEDIATE takes the
-        # write lock for the whole critical section.
-        conn.isolation_level = None  # manual transaction control
-        try:
-            conn.execute("BEGIN IMMEDIATE")
-            row = conn.execute(
-                "SELECT COALESCE(revision, 0) AS revision,"
-                " COALESCE(origin_node, '') AS origin_node"
-                " FROM mesh_state"
-                " WHERE profile_id = ? AND key = ?",
-                (profile_id, key),
-            ).fetchone()
-
-            if row is None:
-                local_rev: int = 0
-                local_node: str = ""  # No row — treat as the absolute minimum
-            else:
-                local_rev = int(row["revision"])
-                local_node = self._effective_node(row["origin_node"])
-
-            # Total order: compare revision (int) first; break ties by node_id (str lex).
-            # A strict > means ties-to-local (same rev, same node) → do nothing (idempotent).
-            remote_wins: bool = (remote_rev, remote_node) > (local_rev, local_node)
-            if not remote_wins:
-                conn.execute("ROLLBACK")
-                return False
-
-            # UPSERT: set origin_node = remote_node so subsequent merges of the
-            # same delta compute the same winner without re-resolving local node_id.
-            conn.execute(
-                "INSERT INTO mesh_state"
-                " (profile_id, key, value, set_by, updated_at, revision, origin_node)"
-                " VALUES (?, ?, ?, ?, ?, ?, ?)"
-                " ON CONFLICT(profile_id, key) DO UPDATE SET"
-                " value     = excluded.value,"
-                " set_by    = excluded.set_by,"
-                " updated_at = excluded.updated_at,"
-                " revision  = excluded.revision,"
-                " origin_node = excluded.origin_node",
-                (
-                    profile_id,
-                    key,
-                    str(entry["value"]),
-                    str(entry["set_by"]),
-                    str(entry["updated_at"]),
-                    remote_rev,
-                    remote_node,
-                ),
-            )
-            conn.execute("COMMIT")
-            return True
-        finally:
-            conn.close()

package/src/superlocalmemory/migrations/__init__.py

@@ -1,5 +0,0 @@
-# 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
-
-"""Schema and data migrations."""

package/src/superlocalmemory/migrations/v3_4_25_to_v3_4_26.py

@@ -1,144 +0,0 @@
-# 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
-
-"""Idempotent migration from v3.4.25 to v3.4.26 data layout.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import logging
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-
-def _daemon_running() -> bool:
-    """Return True if an SLM daemon is holding the data dir.
-
-    Defined as a module-level indirection so tests can monkey-patch it
-    without reaching into ``cli.daemon``.
-    """
-    from superlocalmemory.cli.daemon import is_daemon_running
-    return bool(is_daemon_running())
-
-
-def migrate_if_safe(data_dir: Path) -> dict[str, object]:
-    """Run :func:`migrate` only when it's safe to touch the data dir.
-
-    Safety guarantees:
-
-    1. A live daemon means defer — the daemon is the authoritative DB
-       holder and will apply the migration on its next start.
-    2. If the daemon probe itself fails, err on the safe side and defer.
-    3. Concurrent CLI + daemon-start + npm-postinstall invocations on
-       the same data dir serialize through a file lock, so no two
-       processes can race into ``migrate()`` at the same moment.
-
-    Returns a dict with a ``status`` in
-    ``{applied, already_applied, deferred}``.
-    """
-    data_dir = Path(data_dir)
-
-    if is_ready(data_dir):
-        return {"status": "already_applied", "data_dir": str(data_dir)}
-
-    try:
-        daemon_up = _daemon_running()
-    except Exception as exc:
-        logger.warning(
-            "daemon probe failed, deferring migrate_if_safe: %s", exc,
-        )
-        daemon_up = True
-
-    if daemon_up:
-        return {
-            "status": "deferred",
-            "data_dir": str(data_dir),
-            "reason": "daemon is running — migration will apply on next daemon start",
-        }
-
-    # Serialize concurrent CLI / postinstall / daemon-boot callers.
-    data_dir.mkdir(parents=True, exist_ok=True)
-    lock_path = data_dir / ".migrate-v3.4.26.lock"
-    lock_fd = None
-    try:
-        import os
-        lock_fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o600)
-        import sys
-        if sys.platform == "win32":
-            try:
-                import msvcrt
-                msvcrt.locking(lock_fd, msvcrt.LK_LOCK, 1)
-            except (IOError, OSError):
-                # Another process is mid-migrate — they will apply it.
-                return {
-                    "status": "deferred",
-                    "data_dir": str(data_dir),
-                    "reason": "concurrent migrate_if_safe in progress",
-                }
-        else:
-            try:
-                import fcntl
-                fcntl.flock(lock_fd, fcntl.LOCK_EX)
-            except (IOError, OSError):
-                return {
-                    "status": "deferred",
-                    "data_dir": str(data_dir),
-                    "reason": "concurrent migrate_if_safe in progress",
-                }
-
-        # Re-check the sentinel now that we own the lock — another
-        # process may have applied the migration while we waited.
-        if is_ready(data_dir):
-            return {"status": "already_applied", "data_dir": str(data_dir)}
-
-        result = migrate(data_dir)
-        result["status"] = "applied"
-        return result
-    finally:
-        if lock_fd is not None:
-            try:
-                import os as _os
-                _os.close(lock_fd)
-            except OSError:
-                pass
-
-
-def migrate(data_dir: Path) -> dict[str, object]:
-    """Prepare v3.4.26 data directory. Safe to run any number of times.
-
-    memory.db is untouched; the migration only provisions the new
-    recall_queue.db and marks readiness with a sentinel file.
-    """
-    result: dict[str, object] = {
-        "data_dir": str(data_dir),
-        "created": [],
-        "already_present": [],
-    }
-    data_dir = Path(data_dir)
-    data_dir.mkdir(parents=True, exist_ok=True)
-
-    from superlocalmemory.core.recall_queue import RecallQueue
-
-    queue_path = data_dir / "recall_queue.db"
-    if queue_path.exists():
-        result["already_present"].append(str(queue_path))
-    else:
-        result["created"].append(str(queue_path))
-    q = RecallQueue(db_path=queue_path)
-    q.close()
-
-    marker = data_dir / ".slm-v3.4.26-ready"
-    if marker.exists():
-        result["already_present"].append(str(marker))
-    else:
-        marker.write_text("3.4.26\n", encoding="utf-8")
-        result["created"].append(str(marker))
-    return result
-
-
-def is_ready(data_dir: Path) -> bool:
-    return (Path(data_dir) / ".slm-v3.4.26-ready").exists()

package/src/superlocalmemory/optimize/NOTICE

@@ -1,6 +0,0 @@
-Third-party components used by SLM v3.6 Optimize module:
-
-1. LLMLingua-2 (MIT)
-   Copyright (c) 2024 Microsoft Corporation
-   Source: https://github.com/microsoft/LLMLingua
-   License: MIT

package/src/superlocalmemory/optimize/adapters/__init__.py

@@ -1,68 +0,0 @@
-"""optimize/adapters — SDK adapters for OpenAI / Anthropic / LangChain.
-
-SECURITY: No pickle anywhere. JSON+pydantic only (SEC-C-04, CWE-502).
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-logger = logging.getLogger("superlocalmemory.optimize.adapters")
-
-
-def withSLM(client: Any, *, tenant_id: str = "default") -> Any:
-    """Wrap any supported SDK client with SLM cache hooks.
-
-    FAIL-OPEN GUARANTEE:
-      - If Optimize is disabled (config.enabled == False) → return client unchanged.
-      - If cache is unavailable → return client unchanged, log WARNING.
-      - If client type unrecognized → return client unchanged, log WARNING.
-    """
-    try:
-        from superlocalmemory.optimize.config import get_optimize_config
-        from superlocalmemory.optimize.cache.manager import CacheManager
-    except ImportError as exc:
-        logger.warning("SLM Optimize not available (%s) — pass-through active", exc)
-        return client
-
-    config = get_optimize_config()
-    if not config.enabled:
-        return client  # DEFAULT STATE — zero behavioral change
-
-    try:
-        cache_manager = CacheManager.get_instance()
-    except Exception as exc:
-        logger.warning("SLM cache unavailable (%s) — pass-through active", exc)
-        return client
-
-    # Anthropic (.messages.create)
-    if hasattr(client, "messages") and hasattr(client.messages, "create"):
-        try:
-            from superlocalmemory.optimize.adapters.anthropic_adapter import (
-                SLMAnthropicAdapter,
-            )
-            return SLMAnthropicAdapter(client, cache_manager, config, tenant_id)
-        except Exception as exc:
-            logger.warning("SLM Anthropic adapter init failed: %s", exc)
-            return client
-
-    # OpenAI (.chat.completions)
-    if hasattr(client, "chat") and hasattr(client.chat, "completions"):
-        try:
-            from superlocalmemory.optimize.adapters.openai_adapter import (
-                SLMOpenAIAdapter,
-            )
-            return SLMOpenAIAdapter(client, cache_manager, config, tenant_id)
-        except Exception as exc:
-            logger.warning("SLM OpenAI adapter init failed: %s", exc)
-            return client
-
-    logger.warning(
-        "withSLM: unrecognized client type %s — pass-through active",
-        type(client).__name__,
-    )
-    return client
-
-
-__all__ = ["withSLM"]

package/src/superlocalmemory/optimize/adapters/_agent_registry.py

@@ -1,120 +0,0 @@
-"""Agent redirect registry — DATA ONLY, no logic.
-
-PORT: 8765 (INTERFACE-CONTRACT §0). There is NO port 52415 anywhere.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-AGENT_REGISTRY: dict[str, dict[str, Any]] = {
-    "claude": {
-        "binary": "claude",
-        "mechanism": "env",
-        "env_vars": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8765"},
-        "settings_path": None,
-        "protocol": "anthropic",
-        "print_only": False,
-        "help_text": (
-            "Launches `claude` with ANTHROPIC_BASE_URL pointing at the SLM proxy.\n"
-            "All Claude Code calls are intercepted: cache checked, response stored."
-        ),
-    },
-    "claude-settings": {
-        "binary": None,
-        "mechanism": "settings-file",
-        "settings_path": "~/.claude/settings.json",
-        "env_vars": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8765"},
-        "protocol": "anthropic",
-        "print_only": False,
-        "help_text": (
-            "Writes ANTHROPIC_BASE_URL into ~/.claude/settings.json env block."
-        ),
-    },
-    "antigravity": {
-        "binary": "agy",
-        "mechanism": "print-only",
-        "protocol": "anthropic",
-        "print_only": True,
-        "help_text": (
-            "Antigravity (agy) redirect must be verified at runtime.\n"
-            "Run: agy --help | grep -i base\n"
-            "Then export the appropriate env var manually."
-        ),
-    },
-    "cline": {
-        "binary": None,
-        "mechanism": "config-file",
-        "config_path": "{vscode_user_dir}/settings.json",
-        "config_key": "cline.openAiApiBase",
-        "config_value": "http://127.0.0.1:8765/v1",
-        "protocol": "openai",
-        "print_only": False,
-        "help_text": (
-            "Edits VS Code user settings to set cline.openAiApiBase."
-        ),
-    },
-    "opencode": {
-        "binary": "opencode",
-        "mechanism": "print-only",
-        "protocol": "openai",
-        "print_only": True,
-        "help_text": (
-            "OpenCode redirect must be verified at runtime.\n"
-            "Run: opencode --print-config"
-        ),
-    },
-    "cursor": {
-        "binary": "cursor",
-        "mechanism": "print-only",
-        "protocol": "openai",
-        "print_only": True,
-        "help_text": (
-            "Cursor settings cannot be automated via env vars.\n"
-            "Manual: Settings → Models → Override OpenAI Base URL → http://127.0.0.1:8765/v1"
-        ),
-    },
-    "aider": {
-        "binary": "aider",
-        "mechanism": "env",
-        "env_vars": {
-            "OPENAI_API_BASE": "http://127.0.0.1:8765/v1",
-            "ANTHROPIC_BASE_URL": "http://127.0.0.1:8765",
-        },
-        "protocol": "both",
-        "print_only": False,
-        "help_text": (
-            "Launches `aider` with both OpenAI and Anthropic base URLs set."
-        ),
-    },
-    "codex": {
-        "binary": "codex",
-        "mechanism": "env",
-        "env_vars": {"OPENAI_BASE_URL": "http://127.0.0.1:8765/v1"},
-        "protocol": "openai",
-        "print_only": False,
-        "help_text": (
-            "Launches `codex` with OPENAI_BASE_URL pointing at the SLM proxy."
-        ),
-    },
-    "copilot": {
-        "binary": "copilot",
-        "mechanism": "print-only",
-        "protocol": "anthropic",
-        "print_only": True,
-        "help_text": (
-            "Copilot redirect must be verified at runtime.\n"
-            "Run: gh copilot --help | grep -i provider"
-        ),
-    },
-    "generic": {
-        "binary": None,
-        "mechanism": "print-only",
-        "protocol": "openai",
-        "print_only": True,
-        "help_text": (
-            "Generic OpenAI-compatible client:\n"
-            "  export OPENAI_BASE_URL=http://127.0.0.1:8765/v1"
-        ),
-    },
-}