superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/cli/db_migrate.py

@@ -1,150 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — LLD-06 §7.2
-
-"""CLI handler for ``slm db migrate``.
-
-
-Thin wrapper over the canonical runner in
-``superlocalmemory.storage.migration_runner``. This module owns only
-the user-facing surface (stdout formatting + exit codes). All DDL +
-runner logic lives in LLD-07 territory — per H15, no migration schema
-is defined or duplicated here.
-"""
-from __future__ import annotations
-
-from argparse import Namespace
-from pathlib import Path
-
-from superlocalmemory.infra.data_root import DynamicStatePath
-
-
-# Canonical paths — match LLD-01 / LLD-07 layout. Callers can override
-# via the ``learning_db_path`` / ``memory_db_path`` attributes on args
-# (tests rely on this to point at fixture DBs).
-DEFAULT_HOME = DynamicStatePath()
-
-
-def _resolve_paths(args: Namespace) -> tuple[Path, Path]:
-    learning = getattr(args, "learning_db_path", None)
-    memory = getattr(args, "memory_db_path", None)
-    if learning is None:
-        learning = DEFAULT_HOME / "learning.db"
-    if memory is None:
-        memory = DEFAULT_HOME / "memory.db"
-    return Path(learning), Path(memory)
-
-
-def _end_state_disagreements(learning_db, memory_db) -> dict[str, str]:
-    """Migrations recorded complete whose own verification no longer passes.
-
-    ``--status`` reads ``migration_log``, which records what was *done*. The
-    daemon re-runs each completed migration's ``verify()`` on every start, which
-    checks whether what was done still *holds*. When those two answers differ
-    the log says ``complete`` and the health endpoint says the migration failed,
-    and until now nothing on any surface showed the two were even asking
-    different questions -- so the only available reading was that one of them
-    was lying. Reported as #125.
-
-    Read-only and fail-quiet: this is a diagnostic printed beside a status line,
-    and it must never be the reason a status command exits non-zero.
-    """
-    import sqlite3
-
-    from superlocalmemory.storage._migration_internals import _MODULES
-    from superlocalmemory.storage.migration_runner import MIGRATIONS
-
-    try:
-        from superlocalmemory.storage.migration_runner import DEFERRED_MIGRATIONS
-    except ImportError:  # pragma: no cover — older layouts
-        DEFERRED_MIGRATIONS = ()
-
-    out: dict[str, str] = {}
-    for migration in list(MIGRATIONS) + list(DEFERRED_MIGRATIONS):
-        verify_fn = getattr(_MODULES.get(migration.name), "verify", None)
-        if not callable(verify_fn):
-            continue
-        db_path = memory_db if migration.db_target != "learning" else learning_db
-        try:
-            conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
-        except sqlite3.Error:
-            continue
-        try:
-            row = conn.execute(
-                "SELECT status FROM migration_log WHERE name = ? LIMIT 1",
-                (migration.name,),
-            ).fetchone()
-            if not row or row[0] != "complete":
-                continue
-            if not bool(verify_fn(conn)):
-                out[migration.name] = "  <- recorded complete, end-state no longer holds"
-        except Exception:  # noqa: BLE001 — a diagnostic must not break status
-            pass
-        finally:
-            try:
-                conn.close()
-            except sqlite3.Error:  # pragma: no cover
-                pass
-    return out
-
-
-def cmd_db_migrate(args: Namespace) -> int:
-    """Apply pending migrations or report status.
-
-    Behaviour:
-      - ``--status`` prints the per-migration status recorded in each
-        DB's ``migration_log``. Exit 0 unless reading fails.
-      - ``--dry-run`` runs the runner in dry-run mode (no writes).
-      - Default: runs ``apply_all``.
-
-    Exit codes (also returned for tests that capture return value):
-      - 0 on success (no failed migrations).
-      - 1 if any migration is reported as ``failed``.
-    """
-    from superlocalmemory.storage.migration_runner import apply_all, status
-
-    learning_db, memory_db = _resolve_paths(args)
-
-    if getattr(args, "status", False):
-        report = status(learning_db, memory_db)
-        if not report:
-            print("(no migrations registered)")
-        else:
-            disagreements = _end_state_disagreements(learning_db, memory_db)
-            for name, state in report.items():
-                note = disagreements.get(name, "")
-                print(f"  {name}: {state}{note}")
-            if disagreements:
-                print()
-                print(
-                    "  A migration marked complete is re-checked on every start "
-                    "by its own\n"
-                    "  verification. The ones flagged above are recorded as done "
-                    "and their\n"
-                    "  end-state no longer holds, which is what the daemon "
-                    "reports as a\n"
-                    "  migration failure while this log still reads complete. "
-                    "Run `slm db\n"
-                    "  migrate` to let each one try to repair itself, and see "
-                    "`migration_failure_reasons`\n"
-                    "  in `slm health --json` for what specifically did not hold."
-                )
-        return 0
-
-    dry_run = bool(getattr(args, "dry_run", False))
-    result = apply_all(learning_db, memory_db, dry_run=dry_run)
-    applied = result.get("applied", [])
-    skipped = result.get("skipped", [])
-    failed = result.get("failed", [])
-    print(
-        f"Applied={len(applied)} Skipped={len(skipped)} Failed={len(failed)}"
-    )
-    if failed:
-        details = result.get("details", {})
-        for name in failed:
-            print(f"  FAILED {name}: {details.get(name, '(no detail)')}")
-        return 1
-    return 0
-
-
-__all__ = ("cmd_db_migrate", "DEFAULT_HOME")

package/src/superlocalmemory/cli/diagnostics_cmd.py

@@ -1,101 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Explicit manual export for local aggregate diagnostics."""
-
-from __future__ import annotations
-
-from argparse import Namespace
-
-
-def cmd_diagnostics(args: Namespace) -> None:
-    action = getattr(args, "diagnostics_command", None)
-    if action == "reliability":
-        _cmd_reliability(args)
-        return
-    if action != "export":
-        raise SystemExit("choose a diagnostics subcommand: export, reliability")
-
-    from superlocalmemory.cli.json_output import json_print
-    from superlocalmemory.infra.local_diagnostics import default_diagnostics
-
-    default_diagnostics().export_json(args.destination)
-    data = {"exported": True, "reporting": "manual_export_only"}
-    if bool(getattr(args, "json", False)):
-        json_print("diagnostics", data=data)
-        return
-    print("Local aggregate diagnostics exported by explicit request.")
-    print("No automatic reporting was enabled.")
-
-
-def _cmd_reliability(args: Namespace) -> None:
-    """Report whether wired mechanisms are effective, not merely present.
-
-    ``implemented``, ``reachable`` and ``effective`` are three different
-    questions. A grep answers the first and an import answers the second; only
-    querying this store answers the third. Both checks are read-only.
-    """
-    from superlocalmemory.cli.json_output import json_print
-    from superlocalmemory.infra.data_root import state_path
-    from superlocalmemory.reliability import (
-        DEFAULT_MIN_OBSERVATIONS,
-        check_beta_learners,
-        check_schema_guards,
-    )
-
-    floor = getattr(args, "min_observations", None) or DEFAULT_MIN_OBSERVATIONS
-    learners = check_beta_learners(state_path("learning.db"), min_observations=floor)
-    guards = check_schema_guards(state_path("memory.db"))
-
-    payload = {
-        "learners": [
-            {
-                "table": v.table,
-                "verdict": v.verdict,
-                "units": v.units,
-                "units_at_prior_mean": v.units_at_prior_mean,
-                "units_matching_neutral_identity": v.units_matching_neutral_identity,
-                "observations": v.observations,
-                "detail": v.detail,
-            }
-            for v in learners
-        ],
-        "schema_guards": [
-            {
-                "name": g.name,
-                "verdict": g.verdict,
-                "missing": list(g.missing),
-                "found_elsewhere": [
-                    {
-                        "table": tbl,
-                        "column": col,
-                        "populated_rows": n,
-                        # -1 when coverage over the guarded table could not be
-                        # measured. Populated rows alone overstate the remedy.
-                        "coverage_pct_of_guarded_table": cov,
-                    }
-                    for tbl, col, n, cov in g.found_elsewhere
-                ],
-                "detail": g.detail,
-            }
-            for g in guards
-        ],
-    }
-
-    if bool(getattr(args, "json", False)):
-        json_print("diagnostics-reliability", data=payload)
-        return
-
-    if not learners and not guards:
-        print("No Bayesian learners or schema-guarded paths found in this store.")
-        return
-
-    for v in learners:
-        print(f"[{v.verdict}] {v.table}")
-        print(f"    {v.detail}")
-    for g in guards:
-        print(f"[{g.verdict}] {g.name}")
-        print(f"    {g.detail}")
-
-
-__all__ = ["cmd_diagnostics"]

package/src/superlocalmemory/cli/escape_hatch.py

@@ -1,220 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — Stage 8 SB-5
-
-"""CLI escape-hatch commands.
-
-Implements the user-facing kill switches and reset commands promised
-by MASTER-PLAN §8 that were previously advertised but missing:
-
-- ``slm disable``      — write ``~/.superlocalmemory/.disabled`` marker
-  and stop the daemon. Hooks and MCP tools no-op until re-enabled.
-- ``slm enable``       — remove the marker; prompt user to start daemon.
-- ``slm clear-cache``  — wipe cache-only databases (preserves memory.db
-  — user memories are NEVER deleted here).
-- ``slm reconfigure``  — invoke the interactive postinstall with the
-  ``--reconfigure`` flag so users can change profile/knobs safely.
-- ``slm benchmark``    — run the evo-memory benchmark harness against
-  an isolated tmp DB (never touches ``~/.superlocalmemory``).
-
-All handlers are stdlib-only at the command boundary; import heavier
-modules lazily inside each function so CLI help stays snappy.
-"""
-
-from __future__ import annotations
-
-import os
-import shutil
-import subprocess
-import sys
-from argparse import Namespace
-from pathlib import Path
-
-
-def cmd_disable(args: Namespace) -> None:
-    """Write the ``.disabled`` marker and stop the daemon."""
-    from superlocalmemory.core.slm_disabled import write_marker, is_disabled
-
-    reason = getattr(args, "reason", "") or ""
-    marker = write_marker(reason)
-    print(f"SLM disabled. Marker: {marker}")
-
-    # Best-effort daemon stop — non-fatal.
-    try:
-        from superlocalmemory.cli.daemon import stop_daemon
-        if stop_daemon():
-            print("Daemon stopped.")
-    except Exception as exc:  # pragma: no cover — defensive
-        print(f"(daemon stop skipped: {exc})", file=sys.stderr)
-
-    # Sanity check
-    if not is_disabled():  # pragma: no cover
-        print("warning: disable marker wrote but is_disabled() returned False",
-              file=sys.stderr)
-
-
-def cmd_enable(args: Namespace) -> None:
-    """Remove the ``.disabled`` marker. Daemon is NOT auto-started —
-    print the one-liner so the user can start it when ready."""
-    from superlocalmemory.core.slm_disabled import remove_marker, marker_path
-
-    removed = remove_marker()
-    if removed:
-        print("SLM enabled. To start the daemon: slm serve start")
-    else:
-        print(f"SLM was already enabled (no marker at {marker_path()}).")
-
-
-_CACHE_DBS = (
-    "active_brain_cache.db",
-    "context_cache.db",
-    "entity_trigram_cache.db",
-)
-
-
-def cmd_clear_cache(args: Namespace) -> None:
-    """Delete cache-only DBs. Preserves ``memory.db`` and ``learning.db``.
-
-    This is an explicitly non-destructive command — user memories live
-    in ``memory.db`` which is NEVER touched here. Only regenerable
-    caches are wiped so SLM can rebuild them on next daemon start.
-    """
-    from superlocalmemory.core.slm_disabled import _slm_home
-
-    home = _slm_home()
-    removed: list[str] = []
-    missing: list[str] = []
-    protected = {"memory.db", "learning.db", "audit.db", "audit_chain.db",
-                 "pending.db"}
-    for name in _CACHE_DBS:
-        if name in protected:  # pragma: no cover — defensive belt
-            continue
-        path = home / name
-        try:
-            path.unlink()
-            removed.append(name)
-        except FileNotFoundError:
-            missing.append(name)
-        except OSError as exc:
-            print(f"  skip {name}: {exc}", file=sys.stderr)
-
-    if removed:
-        print("Removed cache DBs:")
-        for name in removed:
-            print(f"  - {name}")
-    else:
-        print("No cache DBs present — nothing to do.")
-    print("memory.db / learning.db preserved (user memories are never "
-          "touched by clear-cache).")
-
-
-def cmd_reconfigure(args: Namespace) -> None:
-    """Re-run the interactive postinstall with ``--reconfigure``.
-
-    Backs up the existing ``config.toml`` to ``config.toml.bak`` before
-    writing the new one.
-    """
-    script = _find_postinstall_script()
-    if script is None:
-        print("postinstall-interactive.js not found; reinstall the npm "
-              "package to run this command.", file=sys.stderr)
-        sys.exit(2)
-
-    cmd = ["node", str(script), "--reconfigure"]
-    # Pass through any extra CLI flags untouched.
-    extras = getattr(args, "extras", None) or []
-    cmd.extend(extras)
-    result = subprocess.run(cmd, check=False)
-    sys.exit(result.returncode)
-
-
-def _find_postinstall_script() -> Path | None:
-    """Locate ``scripts/postinstall-interactive.js`` next to the package."""
-    # 1. Walk up from this file.
-    here = Path(__file__).resolve()
-    for parent in here.parents:
-        candidate = parent / "scripts" / "postinstall-interactive.js"
-        if candidate.is_file():
-            return candidate
-    # 2. npm global-install layout — sibling of the bin dir.
-    bin_path = shutil.which("slm")
-    if bin_path:
-        bin_dir = Path(bin_path).resolve().parent
-        candidate = bin_dir.parent / "lib" / "node_modules" / \
-            "superlocalmemory" / "scripts" / "postinstall-interactive.js"
-        if candidate.is_file():
-            return candidate
-    return None
-
-
-def cmd_benchmark(args: Namespace) -> None:
-    """Run the evo-memory benchmark harness against an isolated tmp DB.
-
-    The benchmark refuses to touch the user's ``~/.superlocalmemory`` —
-    it spins up its own tmp_path DB, runs day-0 → day-30 simulation,
-    prints MRR / Recall / lift tiers, and exits. CI-safe.
-    """
-    # Import locally — keeps the CLI top-level light.
-    try:
-        # The harness lives in the test tree so we add it to sys.path lazily.
-        repo_root = Path(__file__).resolve().parents[3]
-        tests_dir = repo_root / "tests" / "test_benchmarks"
-        if tests_dir.is_dir() and str(tests_dir) not in sys.path:
-            sys.path.insert(0, str(tests_dir))
-        from evo_memory import EvoMemoryBenchmark  # type: ignore
-    except ImportError as exc:
-        print(f"evo-memory harness not available in this install "
-              f"(bench fixture excluded from binary wheels): {exc}",
-              file=sys.stderr)
-        sys.exit(2)
-
-    import json
-    import tempfile
-    as_json = bool(getattr(args, "json", False))
-
-    with tempfile.TemporaryDirectory(prefix="slm-bench-") as d:
-        bench = EvoMemoryBenchmark(profile_id="bench_v1", data_dir=Path(d))
-        result = bench.run_full_30_day_simulation()
-
-    if as_json:
-        print(json.dumps(result, default=str))
-        return
-
-    print("== Evo-Memory Benchmark ==")
-    print(f"fixture:       {result.get('fixture_version', 'v1')}")
-    print(f"wall_seconds:  {result.get('wall_seconds'):.2f}")
-    cmp = result.get("comparison", {})
-    print(f"day_1 MRR@10:  {cmp.get('day_1_mrr', 0):.4f}")
-    print(f"day_30 MRR@10: {cmp.get('day_n_mrr', 0):.4f}")
-    print(f"lift:          {cmp.get('mrr_lift_pct', 0):.2f}%  "
-          f"(gate: {'STABLE' if cmp.get('passes_10pct_gate') else 'DRAFT'})")
-
-
-def cmd_rotate_token(args: Namespace) -> None:
-    """S-M07: rotate the install token.
-
-    Prints the new token's last-4 suffix for operator audit + a line
-    reminding the user to restart the daemon so HMAC marker caches
-    converge on the new token.
-    """
-    from superlocalmemory.core.security_primitives import rotate_install_token
-    old, new = rotate_install_token()
-    if not new:
-        print("install-token rotation failed (check permissions on "
-              "~/.superlocalmemory/.install_token)")
-        return
-    old_tail = old[-4:] if old else "(absent)"
-    new_tail = new[-4:]
-    print(f"install-token rotated: ...{old_tail} -> ...{new_tail}")
-    print("NOTE: restart the daemon so HMAC marker caches pick up "
-          "the new token (run: slm restart).")
-
-
-__all__ = (
-    "cmd_disable",
-    "cmd_enable",
-    "cmd_clear_cache",
-    "cmd_reconfigure",
-    "cmd_benchmark",
-    "cmd_rotate_token",
-)

package/src/superlocalmemory/cli/evidence_cmd.py

@@ -1,103 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""CLI for versioned evidence export, verification, import, and rebuild."""
-
-from __future__ import annotations
-
-import json
-from argparse import Namespace
-from pathlib import Path
-
-
-def _database():
-    from superlocalmemory.core.config import SLMConfig
-    from superlocalmemory.storage.database import DatabaseManager
-
-    config = SLMConfig.load()
-    return DatabaseManager(config.db_path)
-
-
-def _emit(value: dict, *, as_json: bool) -> None:
-    if as_json:
-        print(json.dumps(value, sort_keys=True))
-        return
-    for key, item in value.items():
-        print(f"{key}: {item}")
-
-
-def cmd_evidence(args: Namespace) -> None:
-    """Dispatch ``slm evidence`` without implicit destructive behavior."""
-    from superlocalmemory.core.evidence_bundle import (
-        export_evidence_bundle,
-        import_evidence_bundle,
-        rebuild_derived_state,
-        verify_evidence_bundle,
-    )
-
-    action = getattr(args, "evidence_command", None)
-    as_json = bool(getattr(args, "json", False))
-    profile = str(getattr(args, "profile", "default") or "default")
-
-    if action == "verify":
-        report = verify_evidence_bundle(args.bundle)
-        _emit({
-            "valid": report.valid,
-            "bundle_id": report.bundle_id,
-            "counts": report.counts,
-            "errors": list(report.errors),
-            "warnings": list(report.warnings),
-        }, as_json=as_json)
-        if not report.valid:
-            raise SystemExit(1)
-        return
-
-    if action == "export":
-        db = _database()
-        if not Path(db.db_path).is_file():
-            raise SystemExit(f"memory database not found: {db.db_path}")
-        manifest = export_evidence_bundle(db, profile, args.destination)
-        _emit({
-            "bundle_id": manifest["bundle_id"],
-            "profile_id": profile,
-            "destination": str(Path(args.destination).resolve()),
-            "unresolved_source_links": manifest["unresolved_source_links"],
-        }, as_json=as_json)
-        return
-
-    if action == "import":
-        if not bool(getattr(args, "execute", False)):
-            print(
-                "Dry run only. Verify the bundle, then re-run with --execute; "
-                "replacement also requires --rollback-dir."
-            )
-            return
-        report = import_evidence_bundle(
-            _database(),
-            args.bundle,
-            target_profile_id=profile,
-            replace=bool(getattr(args, "replace", False)),
-            rollback_dir=getattr(args, "rollback_dir", None),
-        )
-        _emit({
-            "valid": report.valid,
-            "bundle_id": report.bundle_id,
-            "profile_id": profile,
-            "counts": report.counts,
-        }, as_json=as_json)
-        return
-
-    if action == "rebuild":
-        if not bool(getattr(args, "execute", False)):
-            print(
-                "Dry run only. Re-run with --execute to rebuild derived lexical state."
-            )
-            return
-        result = rebuild_derived_state(_database(), profile)
-        _emit({"profile_id": profile, **result}, as_json=as_json)
-        return
-
-    raise SystemExit("choose an evidence subcommand: export, verify, import, or rebuild")
-
-
-__all__ = ["cmd_evidence"]