superlocalmemory 4.0.7 → 4.0.9

package/src/superlocalmemory/core/security_primitives.py

@@ -4,8 +4,6 @@
 
 """Shared security primitives for SLM v3.4.22.
 
-LLD reference: `.backup/active-brain/lld/LLD-07-schema-migrations-and-security-primitives.md`
-Section: 6.1 through 6.10.
 
 Every file write, subprocess spawn, and secret-bearing string across SLM
 daemon, adapters, hooks, and binary installer routes through this module.
@@ -155,10 +153,9 @@ def safe_resolve(base: Path, rel: str | Path) -> Path:
 # enforces the LLD-00 regex AND the base-containment check. Callers in
 # LLD-09 (session state files) and LLD-11 (evolution.lock) MUST use this.
 #
-# Naming deviation from IMPLEMENTATION-MANIFEST P0.2: the manifest reused
-# the name ``safe_resolve`` but the existing path-style helper is used in
-# 9+ call sites. A separate name avoids breakage. See
-# ``.backup/active-brain/MANIFEST-DEVIATION.md`` P0.2 entry.
+# Naming deviation note: the name ``safe_resolve`` was already used by an
+# existing path-style helper that has 9+ call sites. A separate name
+# (``safe_resolve_identifier``) avoids silent breakage at those call sites.
 
 _SAFE_ID_RE = re.compile(r"^[a-zA-Z0-9_-]{1,128}$")
 

package/src/superlocalmemory/core/store_pipeline.py

@@ -311,8 +311,13 @@ def enrich_fact(
 # Vector dual-write helper (P1-2 / embeddings-vector-01)
 # ---------------------------------------------------------------------------
 
-def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None):
-    """Dual-write a fact's embedding to the ANN index + sqlite-vec store.
+def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None) -> bool:
+    """Dual-write a fact's embedding to the sqlite-vec projection and the ANN index.
+
+    Write order mirrors _attach_vector: the sqlite-vec projection is attempted
+    first because that is what a meaning-based search reads.  The ANN index is
+    updated only when the projection accepts the vector.  Returns True when the
+    fact is now findable by meaning (the projection accepted the vector).
 
     Embeds on-demand when the fact has no embedding (e.g. consolidated
     summary facts created without one), so UPDATE/SUPERSEDE and consolidated
@@ -325,18 +330,44 @@ def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=Non
         except Exception as _emb_exc:  # pragma: no cover - defensive
             _reraise_materialization_deferral(_emb_exc)
             logger.debug("on-demand embed failed for %s: %s", fact.fact_id, _emb_exc)
-            return
+            return False
     if not getattr(fact, "embedding", None):
-        return
-    if ann_index:
-        ann_index.add(fact.fact_id, fact.embedding)
-    # V3.2: VectorStore upsert (sqlite-vec) -- dual-write (Rule 12)
+        return False
+
+    projected = False
+    # Projection first: what a meaning-based search reads.
     if vector_store and getattr(vector_store, "available", False):
-        vector_store.upsert(
-            fact_id=fact.fact_id,
-            profile_id=profile_id,
-            embedding=fact.embedding,
-        )
+        try:
+            projected = bool(vector_store.upsert(
+                fact_id=fact.fact_id,
+                profile_id=profile_id,
+                embedding=fact.embedding,
+            ))
+            if not projected:
+                logger.warning(
+                    "vector projection refused for %s — stored but not "
+                    "findable by meaning", fact.fact_id[:12],
+                )
+        except Exception as _vs_exc:
+            logger.warning(
+                "vector projection failed for %s (%s: %s) — stored but not "
+                "findable by meaning",
+                fact.fact_id[:12], type(_vs_exc).__name__, _vs_exc,
+            )
+
+    # ANN index only when the projection accepted the vector so both
+    # representations stay consistent.  Writing ANN without a vector-store
+    # entry creates a ghost that disappears on restart (ANN is rebuilt from
+    # the vector store at startup).
+    if projected and ann_index:
+        try:
+            ann_index.add(fact.fact_id, fact.embedding)
+        except Exception:
+            logger.warning(
+                "in-memory index rejected %s", fact.fact_id[:12], exc_info=True,
+            )
+
+    return projected
 
 
 class _TombstoneReadError(Exception):
@@ -741,6 +772,15 @@ def run_store(
             materialization_progress["relational_started"] = True
 
         is_queryable_promotion = fact.fact_id in queryable_ids
+        # When a promoted fact is being materialised the embedding column is
+        # written in a separate step AFTER the projection attempt so that the
+        # two representations stay in the correct order: projection first,
+        # canonical column second (mirroring _attach_vector's invariant).
+        # Writing the column before the projection and then failing the
+        # projection leaves the fact with embedding IS NOT NULL but no entry
+        # in fact_embeddings — invisible to meaning-search and invisible to
+        # every repair pass that selects WHERE embedding IS NULL.
+        _deferred_canonical_embedding = None  # set below if promotion path taken
         if is_queryable_promotion:
             db.update_fact(fact.fact_id, {
                 "content": fact.content,
@@ -757,15 +797,22 @@ def run_store(
                 "access_count": fact.access_count,
                 "source_turn_ids_json": fact.source_turn_ids,
                 "session_id": fact.session_id,
-                "embedding": fact.embedding,
-                "fisher_mean": fact.fisher_mean,
-                "fisher_variance": fact.fisher_variance,
+                # embedding / fisher fields omitted here — written after
+                # the projection attempt below so canonical is never ahead
+                # of the projection.
                 "lifecycle": fact.lifecycle,
                 "langevin_position": fact.langevin_position,
                 "emotional_valence": fact.emotional_valence,
                 "emotional_arousal": fact.emotional_arousal,
                 "signal_type": fact.signal_type,
             })
+            if fact.embedding:
+                _deferred_canonical_embedding = (
+                    fact.fact_id,
+                    fact.embedding,
+                    fact.fisher_mean,
+                    fact.fisher_variance,
+                )
         if consolidator:
             try:
                 action = consolidator.consolidate(
@@ -793,6 +840,9 @@ def run_store(
                     target_id = action.existing_fact_id
                     if is_queryable_promotion and target_id:
                         db.delete_fact(fact.fact_id)
+                        # The original promoted fact was deleted; its deferred
+                        # canonical embedding write must not happen.
+                        _deferred_canonical_embedding = None
                     existing_fact = db.get_fact(target_id) if target_id else None
                     if existing_fact is None:
                         continue
@@ -838,9 +888,31 @@ def run_store(
             if materialization_progress is not None:
                 materialization_progress["fact_ids"] = tuple(stored_ids)
 
-        # Dual-write embedding to ANN index + vector store (embed on-demand if
-        # a consolidated ADD fact arrived without one). See _upsert_fact_vectors.
+        # Projection first (vector store then ANN index, on-demand embed for
+        # consolidated facts that arrived without one).
         _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder)
+
+        # Canonical embedding write: deferred to here from the queryable-
+        # promotion block above so the projection is always attempted first.
+        # The column is written regardless of whether the projection accepted
+        # the vector (the vector is real data; withholding it would force
+        # every repair pass to re-compute a model call that the same
+        # installation condition would refuse again anyway).
+        if _deferred_canonical_embedding is not None:
+            _dc_fid, _dc_emb, _dc_fmean, _dc_fvar = _deferred_canonical_embedding
+            try:
+                db.update_fact(_dc_fid, {
+                    "embedding": _dc_emb,
+                    "fisher_mean": _dc_fmean,
+                    "fisher_variance": _dc_fvar,
+                })
+            except Exception as _dc_exc:
+                logger.warning(
+                    "canonical embedding write failed for %s: %s",
+                    _dc_fid[:12], _dc_exc,
+                )
+            _deferred_canonical_embedding = None
+
         # Phase 2: Generate contextual description (after consolidator, before graph_builder)
         if context_generator:
             try:
@@ -1139,15 +1211,11 @@ def run_store_fact_direct(
         )
         fact.canonical_entities = list(canonical.values())
     db.store_fact(fact)
-    if fact.embedding and ann_index:
-        ann_index.add(fact.fact_id, fact.embedding)
-    # V3.2: VectorStore upsert (dual-write)
-    if fact.embedding and vector_store and vector_store.available:
-        vector_store.upsert(
-            fact_id=fact.fact_id,
-            profile_id=profile_id,
-            embedding=fact.embedding,
-        )
+    # Projection first (vector store), ANN only on success — matching
+    # _attach_vector's invariant.  The return value (projected) is not used
+    # here because run_store_fact_direct is a fire-and-forget path with no
+    # receipt to update; the caller is responsible for any enrichment status.
+    _upsert_fact_vectors(fact, profile_id, ann_index, vector_store)
     if graph_builder:
         graph_builder.build_edges(fact, profile_id)
     # The graph projection must run after GraphBuilder: syncing immediately

package/src/superlocalmemory/core/topic_signature.py

@@ -4,8 +4,6 @@
 
 """Topic signature — deterministic, Unicode-safe, ReDoS-resistant 16-char hex.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.2.
 
 Hot-path contract:
   - stdlib-only imports (no third-party packages).

package/src/superlocalmemory/core/transactions/concrete_owners.py

@@ -15,6 +15,7 @@ from superlocalmemory.core.transactions.owners import (
     OwnerResult,
 )
 from superlocalmemory.core.transactions.service import MemoryTransactionService
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 REQUIRED_ADMISSION_OWNERS: tuple[str, ...] = ("bm25", "temporal", "vector")
 
@@ -438,10 +439,16 @@ class VectorOwner(_FactScopedOwner):
         for row in rows:
             record = dict(row)
             fid = record.get("fact_id")
-            embedding = record.get("embedding")
-            if fid is None or not embedding:
+            raw_embedding = record.get("embedding")
+            if fid is None or not raw_embedding:
                 continue
-            result[fid] = _fingerprint("vector", str(embedding))
+            # Decode so TEXT and BLOB rows produce the same fingerprint for the
+            # same embedding values.  A ValueError here (corrupt buffer) must
+            # propagate — a bad fingerprint is worse than no fingerprint.
+            decoded = decode_embedding(raw_embedding, fact_id=fid)
+            if decoded is None:
+                continue
+            result[fid] = _fingerprint("vector", str(decoded))
         return result
 
     def _table_present(
@@ -496,11 +503,11 @@ class VectorOwner(_FactScopedOwner):
         raw = dict(rows[0]).get("embedding")
         if not raw:
             return False
-        try:
-            embedding = json.loads(raw)
-        except (TypeError, json.JSONDecodeError):
-            return False
-        if not isinstance(embedding, list) or not embedding:
+        # decode_embedding accepts both TEXT (JSON) and BLOB (float32 binary);
+        # ValueError for corrupt data propagates — a heal that silently
+        # returns False on corruption is indistinguishable from "not present".
+        embedding = decode_embedding(raw, fact_id=fact_id)
+        if not embedding:
             return False
         ok = self._vector_store.upsert(
             fact_id=fact_id, profile_id=context.profile_id, embedding=embedding,

package/src/superlocalmemory/dynamics/eap_scheduler.py

@@ -29,12 +29,14 @@ from __future__ import annotations
 
 import json
 import logging
+import sqlite3
 from typing import TYPE_CHECKING
 
 import numpy as np
 from numpy.typing import NDArray
 
 from superlocalmemory.core.config import QuantizationConfig
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 if TYPE_CHECKING:
     from superlocalmemory.math.ebbinghaus import EbbinghausCurve
@@ -262,7 +264,13 @@ class EAPScheduler:
         Tries embedding_metadata -> fact_embeddings (vec0 table).
         Falls back to atomic_facts.embedding JSON column.
         """
-        # Try atomic_facts.embedding (JSON column)
+        # Try atomic_facts.embedding (TEXT JSON or BLOB float32).
+        # Two-stage error handling:
+        #   - DB query failures (any exception from execute) → log + return None.
+        #   - Format errors from decode_embedding (ValueError) → propagate.
+        #     A corrupt embedding must NOT be silently collapsed to None because
+        #     the caller cannot distinguish "embedding absent" from "data lost".
+        raw = None
         try:
             rows = self._db.execute(
                 "SELECT embedding FROM atomic_facts WHERE fact_id = ?",
@@ -270,14 +278,17 @@ class EAPScheduler:
             )
             if rows:
                 raw = dict(rows[0]).get("embedding")
-                if raw and raw != "null":
-                    data = json.loads(raw) if isinstance(raw, str) else raw
-                    if data:
-                        return np.array(data, dtype=np.float64)
-        except Exception as exc:
+        except Exception as exc:  # noqa: BLE001 — isolates DB failure from decode failure
             logger.debug(
                 "Could not load embedding from atomic_facts for %s: %s",
                 fact_id, exc,
             )
+            return None
+
+        if raw and raw != "null":
+            # ValueError from decode_embedding propagates intentionally.
+            vec = decode_embedding(raw, fact_id=fact_id)
+            if vec:
+                return np.array(vec, dtype=np.float64)
 
         return None

package/src/superlocalmemory/encoding/graph_builder.py

@@ -9,7 +9,7 @@ last 50 memories; this version searches ALL facts per canonical entity.
 
 Edge types: ENTITY (shared entity, weight 1.0), TEMPORAL (exp-decay,
 1-week window), SEMANTIC (ANN cosine > 0.7), CAUSAL (causal markers,
-weight 0.8). CONTRADICTION exposed for external Sheaf module (Wave 4).
+weight 0.8). CONTRADICTION exposed for external Sheaf module (added in v3.5).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
 License: AGPL-3.0-or-later
@@ -101,7 +101,7 @@ class GraphBuilder:
         self, fact_id_a: str, fact_id_b: str, profile_id: str,
         severity: float = 1.0,
     ) -> GraphEdge:
-        """Add a contradiction edge. Called by Sheaf module (Wave 4)."""
+        """Add a contradiction edge. Called by the Sheaf module (introduced in v3.5)."""
         edge = GraphEdge(
             profile_id=profile_id,
             source_id=fact_id_a,

package/src/superlocalmemory/encoding/scene_builder.py

@@ -15,6 +15,8 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import json
+
+from superlocalmemory.storage.embedding_codec import decode_embedding
 import logging
 from datetime import UTC, datetime
 
@@ -357,8 +359,12 @@ class SceneBuilder:
             embedding = None
             if raw_embedding:
                 try:
-                    embedding = json.loads(raw_embedding)
-                except (TypeError, ValueError, json.JSONDecodeError):
+                    embedding = decode_embedding(
+                        raw_embedding, fact_id=str(data.get("scene_id", "<scene>")),
+                    )
+                except ValueError:
+                    # A malformed stored value, not an absent one. Scenes are an
+                    # optimisation, so one bad row must not sink the batch.
                     embedding = None
             result[str(data["scene_id"])] = embedding
         return result

package/src/superlocalmemory/evolution/skill_evolver.py

@@ -140,9 +140,24 @@ class SkillEvolver:
         # automatically. Tests inject their own.
         if budget is None:
             slm_home = canonical_data_root()
+            # ``learning_db`` must be learning.db: migration M010 creates
+            # evolution_llm_cost_log there. Every production caller
+            # (consolidation_engine, routes/evolution, MCP, CLI) passes
+            # memory.db as db_path, so handing db_path straight to the budget
+            # pointed it at a database where that table does not exist. Every
+            # evolution cycle then died with "no such table:
+            # evolution_llm_cost_log" — swallowed at debug level in
+            # consolidation step 11, so skill evolution silently never ran.
+            #
+            # Redirect only for the exact production filename. Tests pass
+            # ":memory:" or their own tmp file and must keep the old behaviour,
+            # rather than having a learning.db invented beside them.
+            learning_db = Path(self._db_path)
+            if learning_db.name == "memory.db":
+                learning_db = learning_db.parent / "learning.db"
             budget = EvolutionBudget(
                 profile_id=profile_id,
-                learning_db=Path(self._db_path),
+                learning_db=learning_db,
                 lock_dir=slm_home,
             )
         self._budget = budget

package/src/superlocalmemory/hooks/adapter_base.py

@@ -4,8 +4,6 @@
 
 """Cross-platform adapter base — shared Protocol and atomic write primitive.
 
-LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
-Sections: 2 (component catalog), 4.4 (atomic write), 9.3 (sync log contract).
 
 Every adapter (Cursor, Antigravity, Copilot) implements the ``Adapter``
 Protocol. The shared ``_atomic_write`` primitive enforces the hard-rule

package/src/superlocalmemory/hooks/context_payload.py

@@ -4,8 +4,6 @@
 
 """Shared content builder — single source for every adapter body.
 
-LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
-Section 3 (Content Builder). One builder → five formatters. Every string is
 passed through ``redact_secrets`` before entering the dataclass, so no
 adapter ever writes an unredacted secret.
 

package/src/superlocalmemory/hooks/hook_handlers.py

@@ -768,7 +768,29 @@ def _run_quiet(cmd: list[str], timeout: int = 5, postprocess=None) -> str:
 
 
 def _maybe_consolidate() -> None:
-    """Run cognitive consolidation if last run was >24h ago. Non-blocking."""
+    """Ask the daemon for a full consolidation if the last one was >24h ago.
+
+    Three things were wrong here before 4.0.8, and together they meant the
+    behavioural half of consolidation never ran on a real install:
+
+    1. **It ran the wrong pipeline.** ``slm consolidate --cognitive`` invokes
+       ``CognitiveConsolidator.run_pipeline()``. Behavioural assertion mining,
+       soft prompts, skill performance and skill evolution are steps 8-11 of
+       ``ConsolidationEngine.consolidate()`` — a different class entirely. On a
+       store with thousands of tool events, ``behavioral_assertions`` stayed at
+       zero rows while the miner, run once by hand, produced 9 immediately.
+    2. **It marked success before trying.** The 24h timestamp was written
+       *before* the subprocess launched, so a run that failed instantly still
+       bought a full day of silence. The marker is now written only after the
+       daemon confirms it scheduled the work.
+    3. **It could not fail visibly.** stdout and stderr went to DEVNULL and the
+       handler ended in a bare ``except: pass``, so nothing anywhere recorded a
+       failure. Errors now surface on stderr, where the hook runner logs them.
+
+    Non-blocking: the daemon schedules the pass and returns immediately, so
+    session end is never held up by a run that takes minutes. The daemon's own
+    periodic timer is the backstop for sessions where this hook never fires.
+    """
     try:
         last_ts = 0
         last_consolidation = _last_consolidation_path()
@@ -780,16 +802,21 @@ def _maybe_consolidate() -> None:
         if (now - last_ts) < 86400:  # 24 hours
             return
 
-        # Update timestamp FIRST to prevent concurrent runs
+        started = _daemon_post(
+            "/api/v3/consolidation/trigger",
+            {"lightweight": False, "background": True},
+        )
+        if not started:
+            # No marker written — the next session end retries. The daemon's
+            # consolidation lock makes a duplicate request a cheap no-op.
+            print(
+                "slm: consolidation could not be scheduled (daemon unreachable)",
+                file=sys.stderr,
+            )
+            return
+
         os.makedirs(os.path.dirname(last_consolidation), exist_ok=True)
         with open(last_consolidation, "w") as f:
             f.write(str(now))
-
-        # Run consolidation in background (don't block session end)
-        subprocess.Popen(
-            ["slm", "consolidate", "--cognitive"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-    except Exception:
-        pass
+    except Exception as exc:
+        print(f"slm: consolidation trigger failed: {exc}", file=sys.stderr)

package/src/superlocalmemory/hooks/portable_kit.py

@@ -2,16 +2,16 @@
 # Licensed under AGPL-3.0-or-later - see LICENSE file
 # Part of SuperLocalMemory V3 | https://qualixar.com
 
-"""WP-08 portable kit — ``slm connect <ide>`` MCP-wiring.
+"""Portable kit — ``slm connect <ide>`` MCP-wiring.
 
 Writes SLM's MCP block into the target IDE config via MERGE-NOT-CLOBBER:
 - Only touches the ``superlocalmemory`` server key.
 - All other servers + top-level keys are preserved byte-for-byte.
 - Atomic write (.tmp + os.replace); aborts on parse error (file untouched).
-- claude-code is OUT: short-circuits to a WP-06 plugin pointer, no config written.
+- claude-code is OUT: short-circuits to a plugin pointer, no config written.
 - AGENTS.md is appended with <!-- SLM-START/END --> markers (never overwrite).
 
-IDE_MATRIX verified against ide/configs/* templates (read-only, WP-04 owns).
+IDE_MATRIX verified against ide/configs/* templates (read-only; configs are the authoritative source).
 """
 
 from __future__ import annotations
@@ -39,7 +39,7 @@ SLM_MARKER_END = "<!-- SLM-END -->"
 VALID_TRANSPORTS: frozenset[str] = frozenset({"stdio", "http", "http-mcp-remote"})
 
 CLAUDE_CODE_PLUGIN_POINTER = (
-    "slm connect claude-code: Claude Code is configured via the SLM plugin (WP-06).\n"
+    "slm connect claude-code: Claude Code is configured via the SLM plugin (see plugin/ directory).\n"
     "Run: slm plugin install  OR  see plugin-src/ for manual installation.\n"
     "No MCP config file is written by this command."
 )
@@ -206,17 +206,17 @@ IDE_MATRIX: dict[str, IDEDescriptor] = {
         },
         caveats="contextProviders is a LIST; append+dedupe by serverName",
     ),
-    # --- OUT: claude-code defers to WP-06 ---
+    # --- OUT: claude-code defers to the plugin installer ---
     "claude-code": IDEDescriptor(
         ide_id="claude-code",
-        display="Claude Code (WP-06 plugin)",
+        display="Claude Code (plugin)",
         mcp_path_global="",
         mcp_path_project=None,
         server_key="",
         fmt="",
         agents_md_path=None,
         server_block={},
-        caveats="OUT — WP-06 plugin pointer only; no MCP config written",
+        caveats="OUT — plugin pointer only; no MCP config written",
     ),
     # --- EXPERIMENTAL (gated, not wired by default) ---
     # chatgpt-desktop, perplexity, cody: gated behind --experimental
@@ -702,7 +702,7 @@ if __name__ == "__main__":  # pragma: no cover
         metavar="IDE",
         help=(
             "IDE ids to connect.  Pass 'all' to connect every supported IDE "
-            "(excluding claude-code which uses the WP-06 plugin)."
+            "(excluding claude-code which uses the plugin installer)."
         ),
     )
     _parser.add_argument("--home", help="Override home directory (test hook).")

package/src/superlocalmemory/hooks/post_tool_async_hook.py

@@ -4,8 +4,6 @@
 
 """PostToolUse async:true hook — fire-and-forget prewarm via stdlib urllib.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.4.
 
 HARD RULES (enforced by tests):
   - stdlib only — ``urllib.request``, NOT ``httpx`` / ``requests``.

package/src/superlocalmemory/hooks/prewarm_auth.py

@@ -4,8 +4,6 @@
 
 """Authentication primitives for the /internal/prewarm daemon route.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.5.
 
 Four gates, applied in order, BEFORE any engine work:
   1. Loopback-only — client address must be 127.0.0.1 / ::1.

package/src/superlocalmemory/hooks/user_prompt_hook.py

@@ -4,8 +4,6 @@
 
 """UserPromptSubmit hook — Python fallback (compiled binary preferred).
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.3.
 
 HARD RULES (enforced by tests):
   - stdlib-only imports at module load (SLM modules delayed-imported).

package/src/superlocalmemory/infra/backup.py

@@ -16,6 +16,7 @@ import hashlib
 import json
 import logging
 import shutil
+import tempfile
 import sqlite3
 import time
 import uuid
@@ -735,15 +736,50 @@ class BackupManager:
         target = self.db_path.parent / target_name
 
         try:
-            self.create_backup(label="pre-restore")
+            # Stage the source OUTSIDE backup_dir before anything else runs.
+            #
+            # create_backup() below calls _enforce_retention(), which globs this
+            # same directory and unlinks the oldest files — including, when the
+            # backup being restored is the oldest, the source itself. A plain
+            # sqlite3.connect() on that now-missing path RECREATES it as an
+            # empty database, which is then copied over the live store while the
+            # call returns True, leaving a zero-byte file under the original
+            # name so a second attempt also appears to succeed.
+            #
+            # Reproduced before this fix: 11 snapshots, max_backups=10, a
+            # 500-fact store restored to 0 tables, restore_backup() -> True.
+            with tempfile.TemporaryDirectory(prefix="slm-restore-") as staging:
+                staged = Path(staging) / filename
+
+                # mode=ro fails loudly on a missing file instead of creating one.
+                src_ro = sqlite3.connect(f"file:{backup_path}?mode=ro", uri=True)
+                try:
+                    if not [r[0] for r in src_ro.execute(
+                            "SELECT name FROM sqlite_master WHERE type='table'")]:
+                        logger.error(
+                            "Restore rejected: %s contains no tables — refusing to "
+                            "overwrite %s with an empty database",
+                            filename, target_name,
+                        )
+                        return False
+                    staged_dst = sqlite3.connect(str(staged))
+                    try:
+                        src_ro.backup(staged_dst)
+                    finally:
+                        staged_dst.close()
+                finally:
+                    src_ro.close()
 
-            src = sqlite3.connect(str(backup_path))
-            dst = sqlite3.connect(str(target))
-            try:
-                src.backup(dst)
-            finally:
-                dst.close()
-                src.close()
+                self.create_backup(label="pre-restore")
+
+                # Restore from the staged copy, which retention cannot reach.
+                src = sqlite3.connect(f"file:{staged}?mode=ro", uri=True)
+                dst = sqlite3.connect(str(target))
+                try:
+                    src.backup(dst)
+                finally:
+                    dst.close()
+                    src.close()
 
             logger.info("Restored: %s -> %s", filename, target.name)