superlocalmemory 3.7.2 → 3.7.3

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.7.3] - 2026-07-18 — Scale Engine integrity release
+
+### Fixed
+
+- Added explicit, structurally verified adoption for pre-v3.7 CozoDB/LanceDB projections.
+- Added durable promotion recovery, lifecycle serialization, and a final canonical-source consistency fence.
+- Made Scale Engine status distinguish installed projection paths, lifecycle state, and live daemon backend health.
+- Unified shipped runtime identity metadata at the release version.
+
 ## [3.7.2] - 2026-07-16 — Reliability release
 
 ### Fixed

package/README.md

@@ -1,11 +1,14 @@
 <p align="center">
-  <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/branding/slm-wordmark-dark.svg">
+    <img src="assets/branding/slm-wordmark-light.svg" alt="SuperLocalMemory" width="390">
+  </picture>
 </p>
 
-<h1 align="center">SuperLocalMemory V3.7.2</h1>
+<h1 align="center">SuperLocalMemory V3.7.3</h1>
 <p align="center"><strong>Cache. Compress. Remember. Three surfaces — proxy, MCP tools, or skill. Every setup covered.</strong><br/>
 <em>Local-first agent memory with explicit operating modes, auditable retrieval, and optional Optimize tools.</em></p>
-<p align="center"><code>v3.7.2</code> — <strong>Reliability release: durable local writes, cross-platform installation, and bounded enrichment recovery.</strong><br/>
+<p align="center"><code>v3.7.3</code> — <strong>Scale Engine integrity release: explicit legacy adoption, durable promotion recovery, and honest runtime status.</strong><br/>
 Proxy: <code>slm wrap claude</code> &nbsp;·&nbsp; MCP: add <code>slm_compress</code> to your config &nbsp;·&nbsp; Skill: zero-config</p>
 <p align="center"><strong>3 public research preprints</strong> (arXiv + Zenodo archives) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 
@@ -108,7 +111,7 @@ health surfaces expose the stages actually completed by the installed runtime.
 | **Retrieval and recall** | Semantic, lexical, temporal, Hopfield and spreading-activation candidate channels; RRF fusion, optional reranking and graph score enhancement | Healthy channels participate; response provenance states the evidence used. |
 | **Brain and learning** | Behavioral patterns, feedback/outcome records, rewards, consolidation, LightGBM-related ranking components, soft prompts, and guarded skill-evolution workflows | Learning is evidence-driven; it does not claim autonomous correctness or guaranteed improvement. |
 | **Knowledge graph and entities** | Canonical entities, aliases, entity profiles, graph edges, scenes, timelines, explorer and graph APIs | Stored/derived graph data is evidence, not an instruction authority. |
-| **Scale Engine** | SQLite + sqlite-vec are canonical. CozoDB graph and LanceDB vector projections are packaged and managed with prepare → verify → promote → rollback | Promotion is explicit and parity-gated; do not advertise an unverified projection as the source of truth. |
+| **Scale Engine** | SQLite + sqlite-vec are canonical. CozoDB graph and LanceDB vector projections are managed with prepare → verify → promote → rollback; a structurally detected pre-v3.7 projection can be explicitly adopted. | Promotion is parity-gated and crash-recoverable. Legacy adoption preserves the prior projection as a rollback backup; if proof fails, routing remains on canonical SQLite and status reports repair required. |
 | **Optimize** | Exact cache, tagged invalidation, safe compression, opt-in aggressive prose compression, CCR originals, proxy/MCP/skill surfaces | Only proxy intercepts a primary provider turn. MCP/skill cache results explicitly routed through SLM. |
 | **Mesh** | Authenticated peer messages, inbox/outbox, locks, offline queue, optional discovery and mesh MCP tools | Mesh is coordination, not automatic replicated memory or conflict resolution. |
 | **Governance and operations** | Provenance, audit/retention/policy surfaces, export/erasure controls, diagnostics, health, backups and daemon lifecycle | These are engineering controls, not a legal certification. |
@@ -227,10 +230,15 @@ optional reranking, and entity-graph score enhancement. The entity graph does
 not create an independent candidate in the current implementation. Core memory
 is SQLite-backed. SQLite and sqlite-vec remain the canonical source of truth.
 The packaged Scale Engine can maintain CozoDB graph and LanceDB vector
-projections, and it remains outside active retrieval paths until
-`slm db scale prepare`, `verify`, and `promote` prove parity against the
-canonical store. This makes the capability available on a fresh installation
-without silently migrating an existing user's data.
+projections, and it remains outside active retrieval paths until a staged
+parity witness proves it matches the canonical store. New installations remain
+on Local Core. During upgrade, `slm db scale status` can identify a positive
+pre-v3.7 layout candidate; the operator confirms it with `slm db scale adopt`.
+SLM then rebuilds from canonical SQLite, verifies it, and promotes it with a
+durable recovery journal while retaining the prior directories as a rollback
+backup. `adopt` reports `restart_required: true`; run `slm restart` before
+checking daemon health. If proof fails, recall remains on SQLite and status
+reports repair required.
 
 Canonical ingestion is a durable state machine: `raw → queryable → enriching →
 complete`, with `failed` retaining raw evidence, error details, attempt count,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.7.2",
+  "version": "3.7.3",
   "description": "Local-first agent memory with MCP and an agent-native CLI. Documented clients include Claude Code, Cursor, and Windsurf.",
   "keywords": [
     "ai-memory",

package/plugin/.claude-plugin/plugin.json

@@ -16,5 +16,5 @@
   "mcpServers": "./.mcp.json",
   "name": "superlocalmemory",
   "repository": "https://github.com/qualixar/superlocalmemory",
-  "version": "3.7.2"
+  "version": "3.7.3"
 }

package/plugin/requirements.txt

@@ -1 +1 @@
-superlocalmemory==3.7.2
+superlocalmemory==3.7.3

package/plugin-src/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.7.2",
+  "version": "3.7.3",
   "pluginName": "superlocalmemory",
   "displayName": "SuperLocalMemory",
   "repository": "https://github.com/qualixar/superlocalmemory",

package/plugin-src/requirements.txt

@@ -1 +1 @@
-superlocalmemory==3.7.2
+superlocalmemory==3.7.3

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.7.2"
+version = "3.7.3"
 description = "Local-first agent memory with auditable hybrid retrieval"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

package/src/superlocalmemory/__init__.py

@@ -32,7 +32,7 @@ if "OMP_NUM_THREADS" not in os.environ:
     os.environ["OMP_NUM_THREADS"] = "2"
 # ---------------------------------------------------------------------------
 
-__version__ = "3.7.2"
+__version__ = "3.7.3"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/cli/main.py

@@ -270,8 +270,8 @@ def main() -> None:
     )
     db_scale_p.add_argument(
         "scale_action",
-        choices=("status", "prepare", "verify", "promote", "rollback"),
-        help="Lifecycle action. Prepare and verify never mutate active projection paths.",
+        choices=("status", "adopt", "prepare", "verify", "promote", "rollback"),
+        help="Lifecycle action. Adopt confirms a detected legacy projection; prepare and verify never mutate active paths.",
     )
     db_scale_p.add_argument("--stage-id", help="Stage identifier required by verify/promote")
     db_scale_p.add_argument("--backup-id", help="Backup identifier required by rollback")

package/src/superlocalmemory/cli/scale_engine_cmd.py

@@ -9,11 +9,23 @@ def cmd_db_scale(args: Namespace) -> int:
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.scale_engine import ScaleEngineError, ScaleEngineManager
 
-    manager = ScaleEngineManager(SLMConfig.load())
     action = args.scale_action
+    # Scale Engine projections are currently canonical-default-profile data.
+    # Adoption must not fail merely because the operator is working in another
+    # profile, and it must not rewrite that selected profile.
+    manager = ScaleEngineManager(
+        SLMConfig.load(), profile_id="default" if action == "adopt" else None
+    )
     try:
         if action == "status":
             result = manager.status()
+        elif action == "adopt":
+            result = manager.adopt_legacy_projection()
+            if result is None:
+                raise ScaleEngineError(
+                    "no confirmed legacy projection candidate; see `slm db scale status`"
+                )
+            result = {**result, "restart_required": True}
         elif action == "prepare":
             result = manager.prepare()
         elif action == "verify":

package/src/superlocalmemory/core/backend_orchestrator.py

@@ -97,6 +97,8 @@ class BackendOrchestrator:
         except Exception as exc:
             logger.warning("Initial rebalance failed (non-fatal): %s", exc)
 
+        self._recover_interrupted_scale_promotion()
+
         # Backends may be installed with the product, but installing a wheel
         # is not authorization to mutate an existing data root.  Only a
         # verified, explicit promotion may initialize and migrate projections.
@@ -134,6 +136,19 @@ class BackendOrchestrator:
                      "active" if self._cozo and self._cozo_status() == "active" else "off",
                      "active" if self._lancedb and self._lancedb_status() == "active" else "off")
 
+    def _recover_interrupted_scale_promotion(self) -> None:
+        """Repair an interrupted promotion; never auto-mutate a legacy root."""
+        try:
+            from superlocalmemory.core.scale_engine import ScaleEngineManager
+
+            result = ScaleEngineManager(self._config, profile_id="default").recover_interrupted_promotion()
+            if result:
+                logger.warning("Scale Engine promotion recovery: %s", result)
+        except Exception as exc:
+            # A scale projection is derived data. Startup must keep serving
+            # canonical SQLite even if optional recovery itself is unhealthy.
+            logger.error("Scale Engine recovery requires repair; Local Core remains active: %s", exc)
+
     # ------------------------------------------------------------------
     # Incremental Sync (F-04: called from store_pipeline)
     # ------------------------------------------------------------------

package/src/superlocalmemory/core/scale_engine.py

@@ -41,17 +41,20 @@ class ScaleEngineManager:
 
     MANIFEST_NAME = "scale-engine.json"
     SCHEMA_VERSION = 1
+    LIFECYCLE_LOCK = "scale-engine.lifecycle.lock"
+    PROMOTION_JOURNAL = "scale-engine.promotion.json"
 
     def __init__(
         self,
         config: Any,
         *,
         backend_factory: Callable[[Path, Path], tuple[Any, Any]] | None = None,
+        profile_id: str | None = None,
     ) -> None:
         self.config = config
         self.data_dir = Path(getattr(config, "data_dir", None) or config.base_dir)
         self.db_path = Path(getattr(config, "db_path", None) or self.data_dir / "memory.db")
-        self.profile_id = getattr(config, "active_profile", "default")
+        self.profile_id = profile_id or getattr(config, "active_profile", "default")
         self._backend_factory = backend_factory or self._real_backend_factory
 
     @property
@@ -66,6 +69,14 @@ class ScaleEngineManager:
     def active_paths(self) -> tuple[Path, Path]:
         return self.data_dir / "cozo", self.data_dir / "lance"
 
+    @property
+    def lifecycle_lock_path(self) -> Path:
+        return self.data_dir / self.LIFECYCLE_LOCK
+
+    @property
+    def promotion_journal_path(self) -> Path:
+        return self.data_dir / self.PROMOTION_JOURNAL
+
     def status(self) -> dict[str, Any]:
         manifests: list[dict[str, Any]] = []
         if self.staging_root.exists():
@@ -74,21 +85,93 @@ class ScaleEngineManager:
                     manifests.append(json.loads(path.read_text()))
                 except (OSError, json.JSONDecodeError):
                     manifests.append({"stage_id": path.parent.name, "state": "corrupt"})
+        backups = (
+            sorted(p.name for p in self.backup_root.glob("*") if p.is_dir())
+            if self.backup_root.exists()
+            else []
+        )
+        paths_present = {
+            "cozo": self.active_paths[0].exists(),
+            "lance": self.active_paths[1].exists(),
+        }
+        state = getattr(self.config, "scale_engine_state", "local_core")
+        legacy_projection_candidate = (
+            state == "local_core"
+            and all(paths_present.values())
+            and not manifests
+            and not backups
+            and self._has_legacy_projection_layout()
+        )
+        runtime = self._runtime_backend_status()
         return {
-            "state": getattr(self.config, "scale_engine_state", "local_core"),
-            "active": {"cozo": self.active_paths[0].exists(), "lance": self.active_paths[1].exists()},
+            "state": state,
+            # This command reads persisted state, not the live daemon. Never
+            # turn a last-known backend row into a present-tense routing claim.
+            "active": {"cozo": False, "lance": False},
+            "last_daemon_observation": runtime,
+            "paths_present": paths_present,
+            "retrieval_routing": (
+                "daemon_runtime_check_required" if state == "promoted" else "canonical_sqlite"
+            ),
+            "legacy_projection_candidate": legacy_projection_candidate,
+            "legacy_candidate_requires_confirmation": legacy_projection_candidate,
+            "migration_repair_required": (
+                self.promotion_journal_path.exists()
+                or (state == "local_core" and bool(manifests))
+            ),
             "stages": manifests,
-            "backups": sorted(p.name for p in self.backup_root.glob("*") if p.is_dir()) if self.backup_root.exists() else [],
+            "backups": backups,
         }
 
+    def adopt_legacy_projection(self) -> dict[str, Any] | None:
+        """Safely adopt a v3.5-era projection into the staged lifecycle.
+
+        A legacy projection proves only that an older runtime created files.
+        It cannot establish parity with today's canonical SQLite database.
+        Rebuild a fresh stage, verify it while the canonical database is
+        stable, and promote it atomically; the legacy directories become the
+        explicit rollback copy.
+        """
+        if not self.status()["legacy_projection_candidate"]:
+            return None
+        lock_path = self._acquire_lifecycle_lock()
+        try:
+            # Re-check inside the lock. A concurrent command may have
+            # completed promotion while this caller waited to acquire it.
+            if not self.status()["legacy_projection_candidate"]:
+                return None
+            prepared = self._prepare()
+            self._verify(prepared["stage_id"])
+            return self._promote(prepared["stage_id"])
+        except Exception:
+            # A failed adoption must leave the canonical path selected.  The
+            # stage is retained for operator inspection instead of deleting
+            # evidence about why an upgrade could not be completed.
+            self.config.scale_engine_state = "local_core"
+            self.config.graph_backend = "auto"
+            self.config.vector_backend = "auto"
+            self._save_config()
+            raise
+        finally:
+            self._release_lifecycle_lock(lock_path)
+
     def prepare(self) -> dict[str, Any]:
         """Build a new projection in a private staging directory."""
+        lock_path = self._acquire_lifecycle_lock()
+        try:
+            self._recover_interrupted_promotion()
+            return self._prepare()
+        finally:
+            self._release_lifecycle_lock(lock_path)
+
+    def _prepare(self) -> dict[str, Any]:
+        """Build a new projection while the caller owns the lifecycle lock."""
         self._require_default_profile()
         self._require_canonical_db()
         stage_id = f"{datetime.now(UTC).strftime('%Y%m%dT%H%M%SZ')}-{uuid.uuid4().hex[:8]}"
         stage_dir = self.staging_root / stage_id
         cozo_dir, lance_dir = stage_dir / "cozo", stage_dir / "lance"
-        stage_dir.mkdir(parents=True, exist_ok=False)
+        self._mkdir_durable(stage_dir, exist_ok=False)
         cozo = lance = None
         try:
             cozo, lance = self._backend_factory(cozo_dir, lance_dir)
@@ -96,6 +179,7 @@ class ScaleEngineManager:
                 cozo.bulk_import_from_sqlite(conn, self.profile_id)
                 lance.bulk_import_from_sqlite(conn, self.profile_id)
                 canonical = self._canonical_counts(conn)
+                source_fingerprint = self._projection_fingerprint(conn, canonical)
             observed = self._observed_counts(cozo, lance)
             manifest = {
                 "schema_version": self.SCHEMA_VERSION,
@@ -105,7 +189,7 @@ class ScaleEngineManager:
                 "profile_id": self.profile_id,
                 "canonical": canonical,
                 "observed": observed,
-                "source_fingerprint": self._source_fingerprint(canonical),
+                "source_fingerprint": source_fingerprint,
             }
             self._write_manifest(stage_dir, manifest)
             self.config.scale_engine_state = "prepared"
@@ -120,6 +204,15 @@ class ScaleEngineManager:
 
     def verify(self, stage_id: str) -> dict[str, Any]:
         """Prove a staged projection matches the current canonical SQLite data."""
+        lock_path = self._acquire_lifecycle_lock()
+        try:
+            self._recover_interrupted_promotion()
+            return self._verify(stage_id)
+        finally:
+            self._release_lifecycle_lock(lock_path)
+
+    def _verify(self, stage_id: str) -> dict[str, Any]:
+        """Verify while the caller owns the lifecycle lock."""
         stage_dir, manifest = self._load_stage(stage_id)
         self._validate_manifest(manifest, state="prepared")
         self._require_default_profile()
@@ -128,8 +221,9 @@ class ScaleEngineManager:
             cozo, lance = self._backend_factory(stage_dir / "cozo", stage_dir / "lance")
             with self._readonly_connection() as conn:
                 canonical = self._canonical_counts(conn)
+                source_fingerprint = self._projection_fingerprint(conn, canonical)
             observed = self._observed_counts(cozo, lance)
-            if manifest["source_fingerprint"] != self._source_fingerprint(canonical):
+            if manifest["source_fingerprint"] != source_fingerprint:
                 raise ScaleEngineError("canonical SQLite changed after preparation; prepare a new stage")
             if canonical != manifest["canonical"] or observed != canonical:
                 raise ScaleEngineError(
@@ -146,6 +240,15 @@ class ScaleEngineManager:
 
     def promote(self, stage_id: str) -> dict[str, Any]:
         """Move a verified stage into active paths, preserving a rollback copy."""
+        lock_path = self._acquire_lifecycle_lock()
+        try:
+            self._recover_interrupted_promotion()
+            return self._promote(stage_id)
+        finally:
+            self._release_lifecycle_lock(lock_path)
+
+    def _promote(self, stage_id: str) -> dict[str, Any]:
+        """Promote while the caller owns the lifecycle lock."""
         stage_dir, manifest = self._load_stage(stage_id)
         self._validate_manifest(manifest, state="verified")
         staged = (stage_dir / "cozo", stage_dir / "lance")
@@ -153,39 +256,78 @@ class ScaleEngineManager:
             raise ScaleEngineError("verified stage is incomplete; prepare a new stage")
         backup_dir = self.backup_root / f"{stage_id}-{uuid.uuid4().hex[:6]}"
         active = self.active_paths
-        self.backup_root.mkdir(parents=True, exist_ok=True)
-        # Keep an explicit empty rollback point as well: a first promotion has
-        # no former projection directories, but rollback must still be able to
-        # return the installation to Local Core without deleting anything.
-        backup_dir.mkdir(parents=True, exist_ok=False)
-        moved_active: list[tuple[Path, Path]] = []
-        moved_stage: list[tuple[Path, Path]] = []
+        gate = sqlite3.connect(self.db_path, timeout=30)
         try:
+            # The stage was built from a point-in-time SQLite snapshot. Hold a
+            # short writer fence for the final fingerprint check and directory
+            # swap so no successful promotion can trail a canonical write.
+            gate.execute("BEGIN IMMEDIATE")
+            canonical = self._canonical_counts(gate)
+            if manifest["source_fingerprint"] != self._projection_fingerprint(gate, canonical):
+                raise ScaleEngineError("canonical SQLite changed after verification; prepare a new stage")
+            self._mkdir_durable(self.backup_root)
+            journal = {
+                "schema_version": self.SCHEMA_VERSION,
+                "operation": "promotion",
+                "state": "intent",
+                "stage_id": stage_id,
+                "backup_id": backup_dir.name,
+                "moves": [],
+            }
+            self._write_promotion_journal(journal)
+            self._mkdir_durable(backup_dir, exist_ok=False)
             for name, source, destination in zip(("cozo", "lance"), active, staged):
                 if source.exists():
                     target = backup_dir / name
-                    os.replace(source, target)
-                    moved_active.append((source, target))
-                os.replace(destination, source)
-                moved_stage.append((destination, source))
+                    move = {"name": name, "kind": "active_to_backup", "state": "intent"}
+                    journal["moves"].append(move)
+                    self._write_promotion_journal(journal)
+                    self._replace_durable(source, target)
+                    move["state"] = "complete"
+                    self._write_promotion_journal(journal)
+                move = {"name": name, "kind": "stage_to_active", "state": "intent"}
+                journal["moves"].append(move)
+                self._write_promotion_journal(journal)
+                self._replace_durable(destination, source)
+                move["state"] = "complete"
+                self._write_promotion_journal(journal)
             manifest.update({"state": "promoted", "promoted_at": _utc_now(), "backup_id": backup_dir.name})
             self._write_manifest(stage_dir, manifest)
             self.config.scale_engine_state = "promoted"
             self.config.graph_backend = "cozo"
             self.config.vector_backend = "lancedb"
             self._save_config()
+            journal["state"] = "committed"
+            self._write_promotion_journal(journal)
+            self.promotion_journal_path.unlink(missing_ok=True)
+            gate.rollback()
             return manifest
         except Exception as exc:
-            for staged_path, active_path in reversed(moved_stage):
-                if active_path.exists():
-                    os.replace(active_path, staged_path)
-            for active_path, backup_path in reversed(moved_active):
-                if backup_path.exists():
-                    os.replace(backup_path, active_path)
+            try:
+                gate.rollback()
+            except sqlite3.Error:
+                pass
+            try:
+                self._recover_interrupted_promotion()
+            except ScaleEngineError as recovery_error:
+                raise ScaleEngineError(
+                    f"promotion interrupted; automatic recovery needs repair: {recovery_error}"
+                ) from exc
             raise ScaleEngineError(f"promotion rolled back: {exc}") from exc
+        finally:
+            gate.close()
 
     def rollback(self, backup_id: str) -> dict[str, Any]:
         """Restore an explicitly named pre-promotion backup."""
+        lock_path = self._acquire_lifecycle_lock()
+        try:
+            self._recover_interrupted_promotion()
+            return self._rollback(backup_id)
+        finally:
+            self._release_lifecycle_lock(lock_path)
+
+    def _rollback(self, backup_id: str) -> dict[str, Any]:
+        """Roll back while the caller owns the lifecycle lock."""
         backup_dir = self.backup_root / backup_id
         if not backup_dir.is_dir():
             raise ScaleEngineError(f"backup does not exist: {backup_id}")
@@ -193,19 +335,47 @@ class ScaleEngineManager:
         active = self.active_paths
         displaced = self.backup_root / f"rollback-displaced-{uuid.uuid4().hex[:8]}"
         try:
+            journal = {
+                "schema_version": self.SCHEMA_VERSION,
+                "operation": "rollback",
+                "state": "intent",
+                "backup_id": backup_id,
+                "displaced_id": displaced.name,
+                "moves": [],
+            }
+            self._write_promotion_journal(journal)
             for name, source, target in zip(("cozo", "lance"), active, backup_paths):
                 if source.exists():
-                    displaced.mkdir(parents=True, exist_ok=True)
-                    os.replace(source, displaced / name)
+                    self._mkdir_durable(displaced)
+                    move = {"name": name, "kind": "active_to_displaced", "state": "intent"}
+                    journal["moves"].append(move)
+                    self._write_promotion_journal(journal)
+                    self._replace_durable(source, displaced / name)
+                    move["state"] = "complete"
+                    self._write_promotion_journal(journal)
                 if target.exists():
-                    os.replace(target, source)
+                    move = {"name": name, "kind": "backup_to_active", "state": "intent"}
+                    journal["moves"].append(move)
+                    self._write_promotion_journal(journal)
+                    self._replace_durable(target, source)
+                    move["state"] = "complete"
+                    self._write_promotion_journal(journal)
             self.config.scale_engine_state = "local_core"
             self.config.graph_backend = "auto"
             self.config.vector_backend = "auto"
             self._save_config()
+            journal["state"] = "committed"
+            self._write_promotion_journal(journal)
+            self.promotion_journal_path.unlink(missing_ok=True)
             return {"state": "local_core", "restored_backup": backup_id, "displaced": displaced.name}
         except Exception as exc:
-            raise ScaleEngineError(f"rollback failed; inspect {backup_dir}: {exc}") from exc
+            try:
+                self._recover_interrupted_promotion()
+            except ScaleEngineError as recovery_error:
+                raise ScaleEngineError(
+                    f"rollback interrupted; automatic recovery needs repair: {recovery_error}"
+                ) from exc
+            raise ScaleEngineError(f"rollback recovered: {exc}") from exc
 
     def _real_backend_factory(self, cozo_dir: Path, lance_dir: Path) -> tuple[Any, Any]:
         from superlocalmemory.graph.cozo_backend import CozoDBGraphBackend
@@ -243,17 +413,67 @@ class ScaleEngineManager:
             raise ScaleEngineError(f"projection health failed: cozo={graph}, lancedb={vector}")
         return {"entities": int(graph["entities"]), "edges": int(graph["edges"]), "vectors": int(vector["vectors"])}
 
-    def _source_fingerprint(self, counts: dict[str, int]) -> str:
+    def _projection_fingerprint(
+        self, conn: sqlite3.Connection, counts: dict[str, int]
+    ) -> str:
+        """Hash the exact projection source rows inside one SQLite snapshot."""
         digest = hashlib.sha256()
         digest.update(json.dumps(counts, sort_keys=True).encode())
-        for path in (self.db_path, self.db_path.with_name(self.db_path.name + "-wal")):
-            if path.exists():
-                digest.update(path.name.encode())
-                with path.open("rb") as handle:
-                    for block in iter(lambda: handle.read(1024 * 1024), b""):
-                        digest.update(block)
+        tables = (
+            ("canonical_entities", "entity_id, canonical_name, entity_type, first_seen, last_seen, fact_count, profile_id", "entity_id"),
+            ("atomic_facts", "fact_id, canonical_entities_json, lifecycle, profile_id", "fact_id"),
+            ("graph_edges", "source_id, target_id, edge_type, weight, profile_id", "source_id, target_id, edge_type"),
+        )
+        for table, columns, ordering in tables:
+            try:
+                rows = conn.execute(
+                    f"SELECT {columns} FROM {table} WHERE profile_id=? ORDER BY {ordering}",
+                    (self.profile_id,),
+                )
+                for row in rows:
+                    self._digest_row(digest, table, row)
+            except sqlite3.OperationalError as exc:
+                raise ScaleEngineError(f"canonical SQLite missing required {table} table") from exc
+        try:
+            rows = conn.execute(
+                "SELECT fer.rowid, fer.fact_id, vec.vector FROM fact_embeddings_rowids fer "
+                "JOIN atomic_facts af ON af.fact_id = fer.fact_id "
+                "LEFT JOIN fact_embeddings_vector_chunks00 vec ON vec.rowid = fer.rowid "
+                "WHERE af.profile_id=? ORDER BY fer.rowid",
+                (self.profile_id,),
+            )
+            for row in rows:
+                self._digest_row(digest, "fact_embeddings_rowids", row)
+        except sqlite3.OperationalError:
+            pass
         return digest.hexdigest()
 
+    @staticmethod
+    def _digest_row(digest: Any, table: str, row: Any) -> None:
+        digest.update(table.encode())
+        digest.update(json.dumps(list(row), default=str, separators=(",", ":")).encode())
+
+    def _has_legacy_projection_layout(self) -> bool:
+        cozo, lance = self.active_paths
+        return (cozo / "graph").is_dir() and (lance / "embeddings.lance").exists()
+
+    def _runtime_backend_status(self) -> dict[str, str]:
+        status = {"cozo": "unknown", "lance": "unknown"}
+        try:
+            with self._readonly_connection() as conn:
+                rows = conn.execute(
+                    "SELECT backend_name, status FROM backend_status "
+                    "WHERE backend_name IN ('cozo', 'lancedb')"
+                )
+                for name, value in rows:
+                    if name == "cozo":
+                        status["cozo"] = str(value)
+                    elif name == "lancedb":
+                        status["lance"] = str(value)
+        except sqlite3.OperationalError:
+            pass
+        return status
+
     def _load_stage(self, stage_id: str) -> tuple[Path, dict[str, Any]]:
         stage_dir = self.staging_root / stage_id
         try:
@@ -280,6 +500,201 @@ class ScaleEngineManager:
         if not self.db_path.exists():
             raise ScaleEngineError(f"canonical SQLite database not found: {self.db_path}")
 
+    def _acquire_lifecycle_lock(self) -> Path:
+        """Serialize every mutating lifecycle command across processes."""
+        lock_path = self.lifecycle_lock_path
+        descriptor = None
+        for attempt in range(2):
+            try:
+                descriptor = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                break
+            except FileExistsError as exc:
+                if attempt == 0 and self._clear_dead_legacy_adoption_lock(lock_path):
+                    continue
+                raise ScaleEngineError(
+                    "Scale Engine lifecycle operation already in progress; retry after it completes"
+                ) from exc
+        if descriptor is None:
+            raise ScaleEngineError("could not acquire Scale Engine lifecycle lock")
+        try:
+            with os.fdopen(descriptor, "w") as lock_file:
+                json.dump({"pid": os.getpid(), "started_at": _utc_now()}, lock_file)
+        except Exception:
+            lock_path.unlink(missing_ok=True)
+            raise
+        return lock_path
+
+    @staticmethod
+    def _release_lifecycle_lock(lock_path: Path) -> None:
+        lock_path.unlink(missing_ok=True)
+
+    @staticmethod
+    def _clear_dead_legacy_adoption_lock(lock_path: Path) -> bool:
+        """Recover only a lock whose recorded process no longer exists."""
+        try:
+            owner = json.loads(lock_path.read_text())
+            pid = owner.get("pid")
+            if not isinstance(pid, int) or pid <= 0:
+                return False
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            lock_path.unlink(missing_ok=True)
+            return True
+        except (OSError, ValueError, json.JSONDecodeError):
+            return False
+        return False
+
+    def recover_interrupted_promotion(self) -> str | None:
+        """Recover a durable promotion journal before opening projection paths."""
+        lock_path = self._acquire_lifecycle_lock()
+        try:
+            return self._recover_interrupted_promotion()
+        finally:
+            self._release_lifecycle_lock(lock_path)
+
+    def _recover_interrupted_promotion(self) -> str | None:
+        """Finalize or reverse an interrupted directory swap under lifecycle lock."""
+        if not self.promotion_journal_path.exists():
+            return None
+        try:
+            journal = json.loads(self.promotion_journal_path.read_text())
+            backup_id = str(journal["backup_id"])
+            state = str(journal["state"])
+        except (OSError, KeyError, TypeError, json.JSONDecodeError) as exc:
+            raise ScaleEngineError("invalid promotion journal; manual repair required") from exc
+        operation = str(journal.get("operation", "promotion"))
+        if state == "committed":
+            if operation == "promotion":
+                self.config.scale_engine_state = "promoted"
+                self.config.graph_backend = "cozo"
+                self.config.vector_backend = "lancedb"
+            elif operation == "rollback":
+                self.config.scale_engine_state = "local_core"
+                self.config.graph_backend = "auto"
+                self.config.vector_backend = "auto"
+            else:
+                raise ScaleEngineError(f"unknown journal operation: {operation!r}")
+            self._save_config()
+            self.promotion_journal_path.unlink(missing_ok=True)
+            return f"finalized_committed_{operation}"
+        if state != "intent":
+            raise ScaleEngineError(f"unknown promotion journal state: {state!r}")
+        backup_dir = self.backup_root / backup_id
+        active = dict(zip(("cozo", "lance"), self.active_paths))
+        stage_dir = self.staging_root / str(journal.get("stage_id", ""))
+        displaced_dir = self.backup_root / str(journal.get("displaced_id", ""))
+        moves = journal.get("moves")
+        if not isinstance(moves, list):
+            # Compatibility for journals written by the initial v3.7.3
+            # candidate before per-rename intents existed.
+            moves = [
+                {"name": name, "kind": "active_to_backup", "state": "complete"}
+                for name in journal.get("moved_active", [])
+            ] + [
+                {"name": name, "kind": "stage_to_active", "state": "complete"}
+                for name in journal.get("moved_stage", [])
+            ]
+        for move in reversed(moves):
+            self._reverse_journal_move(move, active, stage_dir, backup_dir, displaced_dir)
+        if operation == "promotion":
+            if backup_dir.exists() and not any(backup_dir.iterdir()):
+                backup_dir.rmdir()
+            self.config.scale_engine_state = "local_core"
+            self.config.graph_backend = "auto"
+            self.config.vector_backend = "auto"
+        elif operation == "rollback":
+            if displaced_dir.exists() and not any(displaced_dir.iterdir()):
+                displaced_dir.rmdir()
+            self.config.scale_engine_state = "promoted"
+            self.config.graph_backend = "cozo"
+            self.config.vector_backend = "lancedb"
+        else:
+            raise ScaleEngineError(f"unknown journal operation: {operation!r}")
+        self._save_config()
+        self.promotion_journal_path.unlink(missing_ok=True)
+        return f"reversed_interrupted_{operation}"
+
+    @staticmethod
+    def _reverse_journal_move(
+        move: Any,
+        active: dict[str, Path],
+        stage_dir: Path,
+        backup_dir: Path,
+        displaced_dir: Path,
+    ) -> None:
+        """Reverse one planned rename based on actual paths, not journal timing."""
+        if not isinstance(move, dict):
+            raise ScaleEngineError("invalid promotion journal move")
+        name = move.get("name")
+        kind = move.get("kind")
+        active_path = active.get(name)
+        if active_path is None:
+            raise ScaleEngineError(f"invalid promotion journal backend: {name!r}")
+        if kind == "stage_to_active":
+            source, target = active_path, stage_dir / name
+        elif kind == "active_to_backup":
+            source, target = backup_dir / name, active_path
+        elif kind == "active_to_displaced":
+            source, target = displaced_dir / name, active_path
+        elif kind == "backup_to_active":
+            source, target = active_path, backup_dir / name
+        else:
+            raise ScaleEngineError(f"invalid promotion journal move kind: {kind!r}")
+        if source.exists() and not target.exists():
+            ScaleEngineManager._replace_durable(source, target)
+        elif target.exists() and not source.exists():
+            return
+        else:
+            raise ScaleEngineError(f"cannot safely reconcile {kind} for {name}")
+
+    def _write_promotion_journal(self, journal: dict[str, Any]) -> None:
+        self._write_json_durable(self.promotion_journal_path, journal)
+
+    @staticmethod
+    def _write_json_durable(target: Path, payload: dict[str, Any]) -> None:
+        temporary = target.with_suffix(target.suffix + ".tmp")
+        with temporary.open("w") as handle:
+            json.dump(payload, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, target)
+        ScaleEngineManager._fsync_directory(target.parent)
+
+    @staticmethod
+    def _replace_durable(source: Path, target: Path) -> None:
+        """Rename a projection path and persist both directory entries."""
+        os.replace(source, target)
+        ScaleEngineManager._fsync_directory(source.parent)
+        if target.parent != source.parent:
+            ScaleEngineManager._fsync_directory(target.parent)
+
+    @staticmethod
+    def _mkdir_durable(path: Path, *, exist_ok: bool = True) -> None:
+        """Create a directory and persist every new parent entry before rename."""
+        missing: list[Path] = []
+        ancestor = path
+        while not ancestor.exists():
+            missing.append(ancestor)
+            ancestor = ancestor.parent
+        path.mkdir(parents=True, exist_ok=exist_ok)
+        for created in reversed(missing):
+            ScaleEngineManager._fsync_directory(created.parent)
+
+    @staticmethod
+    def _fsync_directory(directory_path: Path) -> None:
+        """Best-effort directory-entry durability across local filesystems."""
+        try:
+            directory = os.open(directory_path, os.O_RDONLY)
+            try:
+                os.fsync(directory)
+            finally:
+                os.close(directory)
+        except OSError:
+            # The file itself is already durable where directory fsync is not
+            # supported by the local filesystem (notably some Windows setups).
+            pass
+
     def _save_config(self) -> None:
         save = getattr(self.config, "save", None)
         if callable(save):

package/src/superlocalmemory/hooks/claude_code_hooks.py

@@ -28,6 +28,7 @@ import sys
 import tempfile
 from pathlib import Path
 
+from superlocalmemory import __version__
 from superlocalmemory.infra.data_root import canonical_data_root
 from superlocalmemory.infra.data_root import state_path as runtime_state_path
 
@@ -40,7 +41,7 @@ _DEFAULT_DISABLED_FILE = _DEFAULT_VERSION_DIR / ".hooks-disabled"
 VERSION_DIR = _DEFAULT_VERSION_DIR
 VERSION_FILE = _DEFAULT_VERSION_FILE
 DISABLED_FILE = _DEFAULT_DISABLED_FILE
-HOOKS_VERSION = "3.7.1"
+HOOKS_VERSION = __version__
 
 # Cross-platform temp dir and backwards-compatible marker overrides. Runtime
 # defaults are root-namespaced and resolved when hook definitions are built.

package/src/superlocalmemory/hooks/context_payload.py

@@ -19,10 +19,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Callable, Iterable
 
+from superlocalmemory import __version__
 from superlocalmemory.core.security_primitives import redact_secrets
 
 
-VERSION = "3.7.1"
+VERSION = __version__
 DEFAULT_TOP_K = 10
 DEFAULT_DECISIONS_K = 5
 DEFAULT_MEMORIES_K = 10

package/src/superlocalmemory/mcp/http_transport.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 from mcp.server.fastmcp import FastMCP
 from sse_starlette.sse import EventSourceResponse
 from starlette.types import Receive, Scope, Send
+from superlocalmemory import __version__
 
 
 class ClosingEventSourceResponse(EventSourceResponse):
@@ -40,7 +41,7 @@ def install_streamable_http_resource_guard() -> None:
 class SLMFastMCP(FastMCP):
     """FastMCP with SLM release identity and deterministic SSE cleanup."""
 
-    def __init__(self, *args, product_version: str = "3.7.1", **kwargs) -> None:
+    def __init__(self, *args, product_version: str = __version__, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         # FastMCP delegates the initialize response to the low-level MCP
         # server. Without an explicit value it reports the installed ``mcp``

package/src/superlocalmemory/optimize/proxy/server.py

@@ -12,12 +12,13 @@ from fastapi import APIRouter
 from fastapi.requests import Request
 from fastapi.responses import Response
 
+from superlocalmemory import __version__
 from superlocalmemory.optimize.config.schema import OptimizeConfig
 from superlocalmemory.optimize.proxy.lifecycle import HookChain
 
 logger = logging.getLogger("slm.optimize.proxy")
 
-_PROXY_VERSION = "3.7.1"
+_PROXY_VERSION = __version__
 _REQUEST_TIMEOUT_S = 300.0
 _CONNECT_TIMEOUT_S = 10.0
 _MAX_CONNECTIONS = 100

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

@@ -43,6 +43,7 @@ from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request
+from superlocalmemory import __version__
 
 from superlocalmemory.core.security_primitives import (
     redact_secrets,
@@ -64,7 +65,7 @@ router = APIRouter(prefix="/api/v3", tags=["brain"])
 # LLD-03 v2 stratum space = 4 query types × 3 entity bins × 4 time buckets.
 _STRATA_TOTAL: int = 48
 
-_VERSION: str = "3.7.1"
+_VERSION: str = __version__
 
 # Banned metric names (LLD-04 U4). Kept as a tuple for grep visibility;
 # the source-level test asserts we don't accidentally reintroduce them.