superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/storage/_schema_version.py

@@ -1,174 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Schema-version singleton: read, write, and version-conflict guard.
-
-Encapsulates the one-row ``schema_version`` table written to the learning DB
-after each zero-failure migration run.  A stored version that exceeds the
-runner's supported ceiling means a newer build wrote the database and this
-installation must not operate on it.
-
-Design:
-  - ``_read_schema_version_from_db`` is strictly read-only (no writes).
-  - ``_ensure_schema_version_table`` + ``_write_schema_version`` are only
-    called by the runner after a confirmed zero-failure apply_all.
-  - Missing table or unreadable DB → version 0 (legacy; safe to upgrade).
-"""
-
-from __future__ import annotations
-
-import sqlite3
-from pathlib import Path
-
-#: Highest schema_version this runner can write.  Matches the trailing serial of
-#: the latest migration (M050).  Increment when adding new migrations or
-#: table-level breaking changes.
-#:
-#: This sat at 42 while M043, M044 and M045 shipped, so for three migrations the
-#: ceiling did not move and nothing prevented an older build from opening a
-#: newer store.  That was tolerable only because those three were additive: a
-#: build that did not know about a new column or table simply never read it.
-#:
-#: M046 is not additive.  It rebuilds ``atomic_facts`` with a constraint that
-#: rejects the value an older build classifies planned events as, so an older
-#: writer against a migrated store fails its INSERT.  The ceiling is what turns
-#: that from a lost memory into a refusal to start, which is why it moves here
-#: and why it moves to the trailing serial rather than to 43.
-#:
-#: M049 is additive — a unique index on ``schema_version`` plus the removal of
-#: the duplicate rows that index could not otherwise be created over — so an
-#: older build could in principle read a store it has touched.  The ceiling
-#: still moves, because the convention is "trailing serial, always": the cost of
-#: moving it for an additive migration is an older build declining a store it
-#: could have read, and the cost of NOT moving it for one that turns out not to
-#: be additive is a silent bad write.  Those are not comparable, and judging
-#: additivity per migration is exactly the judgement that let it fall three
-#: behind.
-SUPPORTED_SCHEMA_VERSION: int = 50
-
-
-class SchemaVersionError(RuntimeError):
-    """Raised when the DB's recorded schema_version exceeds the supported max.
-
-    The caller must not attempt any write after catching this — the DB was
-    produced by a newer installation and this build is too old for it.
-    """
-
-
-# NOTE: this singleton lives in its OWN table ``slm_schema_version`` rather than
-# ``schema_version``.  The legacy multi-row migration-history table
-# ``schema_version`` (columns version/applied_at/description, seeded by
-# schema.py + the schema_v34x migrations) already exists on every real database
-# — fresh installs and upgrades alike — so a ``CREATE TABLE IF NOT EXISTS
-# schema_version`` here would no-op against that legacy shape and every
-# ``id``-keyed read/write would fail ("no column named id").  A distinct table
-# name decouples the version-ceiling guard from that legacy history table.
-_SCHEMA_VERSION_DDL = """\
-CREATE TABLE IF NOT EXISTS slm_schema_version (
-    id          INTEGER PRIMARY KEY CHECK (id = 1),
-    version     INTEGER NOT NULL DEFAULT 0,
-    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
-);
-INSERT OR IGNORE INTO slm_schema_version (id, version, updated_at)
-VALUES (1, 0, datetime('now'));
-"""
-
-
-def read_schema_version(db_path: Path) -> int:
-    """Read the stored schema_version without any write.  Returns 0 if absent."""
-    try:
-        conn = sqlite3.connect(str(db_path))
-        try:
-            row = conn.execute(
-                "SELECT version FROM slm_schema_version WHERE id = 1"
-            ).fetchone()
-            return int(row[0]) if row is not None else 0
-        except sqlite3.OperationalError:
-            return 0  # slm_schema_version table does not exist (legacy DB)
-        finally:
-            conn.close()
-    except sqlite3.Error:
-        return 0  # cannot open DB; let the runner surface the open error
-
-
-def ensure_schema_version_table(conn: sqlite3.Connection) -> None:
-    """Create the schema_version table if absent and seed the singleton row."""
-    conn.executescript(_SCHEMA_VERSION_DDL)
-
-
-def write_schema_version(conn: sqlite3.Connection, version: int) -> None:
-    """Overwrite the singleton version record."""
-    conn.execute(
-        "UPDATE slm_schema_version "
-        "SET version = ?, updated_at = datetime('now') WHERE id = 1",
-        (version,),
-    )
-
-
-def _detect_all_installs() -> list:
-    """Delegate to core.install_detector; fail-open (returns [] on any error)."""
-    try:
-        from superlocalmemory.core.install_detector import (
-            _detect_all_installs as _real,
-        )
-        return _real()
-    except Exception:  # import error, timeout, etc.
-        return []
-
-
-def _format_install_block(installs: list) -> str:
-    """Return a formatted multi-line string listing all detected installs."""
-    if not installs:
-        return ""
-
-    _upgrade_hints = {
-        "pipx": "  pipx upgrade superlocalmemory",
-        "venv": "  pip install -U superlocalmemory  (in ~/.slm-venv)",
-        "npm": "  npm install -g superlocalmemory@latest",
-    }
-
-    lines = ["\nAll detected installs:"]
-    seen_types: set[str] = set()
-    for entry in installs:
-        install_type = entry.get("type", "unknown")
-        version = entry.get("version", "unknown")
-        path = entry.get("path", "")
-        lines.append(f"  {install_type:<6} ({version}): {path}")
-        seen_types.add(install_type)
-
-    lines.append("\nUpgrade all installs to the latest version:")
-    for install_type, cmd in _upgrade_hints.items():
-        if install_type in seen_types:
-            lines.append(cmd)
-
-    return "\n".join(lines)
-
-
-def check_version_or_raise(db_path: Path) -> None:
-    """Raise SchemaVersionError if the DB's stored version exceeds supported max.
-
-    When raising, the error message lists every SLM installation detected on
-    this machine so the user knows which copies to upgrade.
-
-    Non-mutating.  Must be called before any write at startup.
-    """
-    stored = read_schema_version(db_path)
-    if stored > SUPPORTED_SCHEMA_VERSION:
-        installs = _detect_all_installs()
-        install_block = _format_install_block(installs)
-        raise SchemaVersionError(
-            f"Database schema_version={stored} exceeds the maximum "
-            f"supported version={SUPPORTED_SCHEMA_VERSION}. "
-            "This installation is too old for this database."
-            + install_block
-        )
-
-
-__all__ = (
-    "SUPPORTED_SCHEMA_VERSION",
-    "SchemaVersionError",
-    "read_schema_version",
-    "ensure_schema_version_table",
-    "write_schema_version",
-    "check_version_or_raise",
-)

package/src/superlocalmemory/storage/access_log.py

@@ -1,170 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3
-
-"""Exposure log for fact retrieval events.
-
-Tracks when facts are accessed (recall, auto_invoke, search).
-The historical table name is retained for compatibility.  A ``recall`` row is
-exposure telemetry only and must never be interpreted as positive feedback.
-All SQL parameterized (Rule 11). Silent errors (Rule 19).
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import logging
-import uuid
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from superlocalmemory.storage.database import DatabaseManager
-
-logger = logging.getLogger(__name__)
-
-
-def _new_log_id() -> str:
-    """Generate a short unique log ID."""
-    return uuid.uuid4().hex[:16]
-
-
-class AccessLog:
-    """CRUD operations for fact_access_log table."""
-
-    def __init__(self, db: DatabaseManager) -> None:
-        self._db = db
-
-    def store_access(
-        self,
-        fact_id: str,
-        profile_id: str,
-        access_type: str = "recall",
-        session_id: str = "",
-    ) -> str:
-        """Record a fact access event. Returns log_id.
-
-        Validates access_type against allowed values.
-        Returns empty string on failure (Rule 19).
-        """
-        allowed = ("recall", "auto_invoke", "search", "consolidation")
-        if access_type not in allowed:
-            access_type = "recall"
-
-        log_id = _new_log_id()
-        try:
-            self._db.execute(
-                "INSERT INTO fact_access_log "
-                "(log_id, fact_id, profile_id, access_type, session_id) "
-                "VALUES (?, ?, ?, ?, ?)",
-                (log_id, fact_id, profile_id, access_type, session_id),
-            )
-            return log_id
-        except Exception as exc:
-            logger.debug("store_access failed for fact_id=%s: %s", fact_id, exc)
-            return ""
-
-    def store_access_batch(
-        self,
-        fact_ids: list[str],
-        profile_id: str,
-        access_type: str = "recall",
-        session_id: str = "",
-    ) -> int:
-        """Record access events for multiple facts. Returns count stored.
-
-        Catches exceptions per-fact (Rule 19: silent errors).
-        """
-        count = 0
-        for fact_id in fact_ids:
-            result = self.store_access(
-                fact_id, profile_id, access_type, session_id,
-            )
-            if result:
-                count += 1
-        return count
-
-    def get_latest_access_time(
-        self, fact_id: str, profile_id: str,
-    ) -> str | None:
-        """Most recent access timestamp for a fact.
-
-        Returns ISO datetime string or None if never accessed.
-        """
-        try:
-            rows = self._db.execute(
-                "SELECT MAX(accessed_at) AS latest "
-                "FROM fact_access_log "
-                "WHERE fact_id = ? AND profile_id = ?",
-                (fact_id, profile_id),
-            )
-            if rows and rows[0]["latest"] is not None:
-                return str(rows[0]["latest"])
-            return None
-        except Exception as exc:
-            logger.debug("get_latest_access_time failed: %s", exc)
-            return None
-
-    def get_access_count(
-        self, fact_id: str, profile_id: str,
-    ) -> int:
-        """Total access count for a fact."""
-        try:
-            rows = self._db.execute(
-                "SELECT COUNT(*) AS c "
-                "FROM fact_access_log "
-                "WHERE fact_id = ? AND profile_id = ?",
-                (fact_id, profile_id),
-            )
-            if rows:
-                return int(rows[0]["c"])
-            return 0
-        except Exception as exc:
-            logger.debug("get_access_count failed: %s", exc)
-            return 0
-
-    def get_all_access_times(
-        self, profile_id: str, limit: int = 1000,
-    ) -> dict[str, str]:
-        """Latest access time for all facts in a profile.
-
-        Returns {fact_id: latest_accessed_at} dict.
-        """
-        try:
-            rows = self._db.execute(
-                "SELECT fact_id, MAX(accessed_at) AS latest "
-                "FROM fact_access_log "
-                "WHERE profile_id = ? "
-                "GROUP BY fact_id "
-                "ORDER BY latest DESC "
-                "LIMIT ?",
-                (profile_id, limit),
-            )
-            return {str(r["fact_id"]): str(r["latest"]) for r in rows}
-        except Exception as exc:
-            logger.debug("get_all_access_times failed: %s", exc)
-            return {}
-
-    def get_frequently_accessed(
-        self, profile_id: str, min_count: int = 3, limit: int = 100,
-    ) -> list[tuple[str, int]]:
-        """Facts accessed at least min_count times.
-
-        Returns [(fact_id, access_count)] sorted by count desc.
-        """
-        try:
-            rows = self._db.execute(
-                "SELECT fact_id, COUNT(*) AS cnt "
-                "FROM fact_access_log "
-                "WHERE profile_id = ? "
-                "GROUP BY fact_id "
-                "HAVING cnt >= ? "
-                "ORDER BY cnt DESC "
-                "LIMIT ?",
-                (profile_id, min_count, limit),
-            )
-            return [(str(r["fact_id"]), int(r["cnt"])) for r in rows]
-        except Exception as exc:
-            logger.debug("get_frequently_accessed failed: %s", exc)
-            return []

package/src/superlocalmemory/storage/admission_codec.py

@@ -1,129 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Production encryption codec for durable remember admission commands."""
-
-from __future__ import annotations
-
-import os
-import stat
-import time
-from pathlib import Path
-
-from cryptography.hazmat.primitives.ciphers.aead import AESGCM
-
-from superlocalmemory.infra.data_root import state_path
-
-_KEY_BYTES = 32
-_NONCE_BYTES = 12
-_FORMAT_VERSION = b"\x01"
-_ASSOCIATED_DATA = b"superlocalmemory:remember-admission:v1"
-_KEY_READ_ATTEMPTS = 100
-_KEY_READ_RETRY_SECONDS = 0.005
-
-
-class AdmissionKeyError(RuntimeError):
-    """The machine-local admission key cannot be created or loaded safely."""
-
-
-class MachineKeyCommandCodec:
-    """AES-256-GCM codec backed by a machine-local, permission-bound key.
-
-    The key is intentionally separate from cache encryption keys.  Exclusive
-    creation makes concurrent daemon startup converge on one key, while the
-    format byte and AEAD associated data prevent cross-protocol ciphertext use.
-    """
-
-    def __init__(self, key_path: str | Path | None = None) -> None:
-        self.key_path = Path(key_path) if key_path is not None else state_path(
-            "admission-key.bin"
-        )
-        self._key = _load_or_create_key(self.key_path)
-
-    def encrypt(self, plaintext: bytes) -> bytes:
-        if not isinstance(plaintext, bytes):
-            raise TypeError("plaintext must be bytes")
-        nonce = os.urandom(_NONCE_BYTES)
-        ciphertext = AESGCM(self._key).encrypt(nonce, plaintext, _ASSOCIATED_DATA)
-        return _FORMAT_VERSION + nonce + ciphertext
-
-    def decrypt(self, ciphertext: bytes) -> bytes:
-        if not isinstance(ciphertext, bytes):
-            raise TypeError("ciphertext must be bytes")
-        minimum = len(_FORMAT_VERSION) + _NONCE_BYTES + 16
-        if len(ciphertext) < minimum or ciphertext[:1] != _FORMAT_VERSION:
-            raise ValueError("unsupported admission ciphertext format")
-        nonce = ciphertext[1 : 1 + _NONCE_BYTES]
-        payload = ciphertext[1 + _NONCE_BYTES :]
-        return AESGCM(self._key).decrypt(nonce, payload, _ASSOCIATED_DATA)
-
-
-def _load_or_create_key(path: Path) -> bytes:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    if os.name != "nt":
-        os.chmod(path.parent, 0o700)
-
-    try:
-        fd = os.open(
-            path,
-            os.O_WRONLY
-            | os.O_CREAT
-            | os.O_EXCL
-            | getattr(os, "O_BINARY", 0),
-            0o600,
-        )
-    except FileExistsError:
-        fd = -1
-    except OSError as exc:
-        try:
-            info = path.lstat()
-        except OSError:
-            raise AdmissionKeyError("admission key cannot be created") from exc
-        if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
-            raise AdmissionKeyError(
-                "admission key path must be a regular file"
-            ) from exc
-        raise AdmissionKeyError("admission key cannot be created") from exc
-    else:
-        try:
-            key = os.urandom(_KEY_BYTES)
-            view = memoryview(key)
-            written = 0
-            while written < _KEY_BYTES:
-                count = os.write(fd, view[written:])
-                if count <= 0:
-                    raise AdmissionKeyError("admission key write was incomplete")
-                written += count
-            os.fsync(fd)
-        except BaseException:
-            try:
-                path.unlink()
-            except OSError:
-                pass
-            raise
-        finally:
-            os.close(fd)
-
-    for attempt in range(_KEY_READ_ATTEMPTS):
-        try:
-            info = path.lstat()
-        except OSError as exc:
-            raise AdmissionKeyError("admission key is unavailable") from exc
-        if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
-            raise AdmissionKeyError("admission key path must be a regular file")
-        if os.name != "nt":
-            if info.st_uid != os.getuid():
-                raise AdmissionKeyError("admission key is not owned by the current user")
-            os.chmod(path, 0o600)
-        try:
-            key = path.read_bytes()
-        except OSError as exc:
-            raise AdmissionKeyError("admission key cannot be read") from exc
-        if len(key) == _KEY_BYTES:
-            return key
-        # A process that lost O_EXCL may observe the winning creator between
-        # file creation and its final fsync/close. Wait only for that bounded
-        # window; a persistently truncated or oversized key still fails closed.
-        if attempt + 1 < _KEY_READ_ATTEMPTS:
-            time.sleep(_KEY_READ_RETRY_SECONDS)
-    raise AdmissionKeyError("admission key has an invalid length")