superlocalmemory 4.0.4 → 4.0.6

package/src/superlocalmemory/compliance/gdpr.py

@@ -14,11 +14,65 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import logging
+import sqlite3
 from datetime import UTC, datetime
 from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
+# C1 — Backup residue obligations
+# Imported lazily inside methods to avoid circular-import risk at module load.
+# The sentinel guards against environments where infra.backup_obligations is
+# unavailable (e.g. minimal test installs); compliance logic degrades safely.
+_BACKUP_OBLIGATIONS_AVAILABLE: bool | None = None
+
+
+def _get_backup_obligations_module():
+    """Lazy import guard — returns module or None if unavailable."""
+    global _BACKUP_OBLIGATIONS_AVAILABLE
+    try:
+        import superlocalmemory.infra.backup_obligations as _m
+        _BACKUP_OBLIGATIONS_AVAILABLE = True
+        return _m
+    except Exception as exc:  # noqa: BLE001
+        if _BACKUP_OBLIGATIONS_AVAILABLE is None:
+            logger.warning("backup_obligations module unavailable: %s", exc)
+        _BACKUP_OBLIGATIONS_AVAILABLE = False
+        return None
+
+
+def _retention_days_from_config() -> int:
+    """Read the configured obligation retention window (default 90 days).
+
+    Consumes ``SLMConfig.backup_retention_days`` or any attribute matching
+    ('retention', 'retain') with numeric value on ``SLMConfig``.  The config
+    field is owned by another agent; we consume it here and fall back to 90.
+    """
+    try:
+        from superlocalmemory.core.config import SLMConfig
+        cfg = SLMConfig()
+        # Try the canonical field name first
+        for attr in ("backup_retention_days", "obligation_retention_days",
+                     "retention_window_days", "backup_obligation_retention_days"):
+            val = getattr(cfg, attr, None)
+            if isinstance(val, int) and val > 0:
+                return val
+        # Fallback: search nested sub-configs
+        for attr in dir(cfg):
+            if attr.startswith("_"):
+                continue
+            sub = getattr(cfg, attr, None)
+            if not hasattr(sub, "__dict__") and not hasattr(sub, "__dataclass_fields__"):
+                continue
+            for sub_attr in dir(sub):
+                if any(h in sub_attr.lower() for h in ("retention", "retain")):
+                    v = getattr(sub, sub_attr, None)
+                    if isinstance(v, int) and v > 0:
+                        return v
+    except Exception:  # noqa: BLE001
+        pass
+    return 90  # owner-set default
+
 # Friendly export keys → canonical table names (stable Art.20 export contract).
 _EXPORT_ALIASES = {
     "facts": "atomic_facts",
@@ -238,6 +292,13 @@ class GDPRCompliance:
         except Exception:
             data["profile_record"] = []
 
+        # C2 — include code_graph.db in Art.15 export (repo paths, file names,
+        # and symbol names are identifying data in a work context).
+        if self._data_root is not None:
+            code_graph_data = self._export_code_graph(self._data_root)
+            if code_graph_data is not None:
+                data["code_graph"] = code_graph_data
+
         # total_items counts the canonical (table-name) keys only, before
         # friendly aliases are added, so it is not double-counted.
         data["total_items"] = sum(len(v) for v in data.values() if isinstance(v, list))
@@ -437,6 +498,16 @@ class GDPRCompliance:
             counts["receipt_error"] = str(exc)
             raise
 
+        # C2 — erase code_graph.db before main profile rows (fail-closed: a
+        # code_graph failure is logged but does NOT abort the erasure; the
+        # graph is installation-level personal data with no profile_id column,
+        # so it is wiped entirely on any Art.17 request).
+        if data_root is not None:
+            code_graph_result = self._erase_code_graph(data_root)
+            counts["code_graph"] = code_graph_result.get("rows_deleted", 0)
+            if code_graph_result.get("error"):
+                counts["code_graph_failed"] = 1
+
         # Purge the learning sidecar *before* removing memory/profile rows. A
         # learning failure is retryable and must leave the profile intact; the
         # former best-effort-after-delete ordering could orphan receipts.
@@ -517,6 +588,45 @@ class GDPRCompliance:
         counts["residue_rows"] = residue_rows
         if residue_recount_failed:
             counts["residue_recount_failed"] = 1
+
+        # I7 — post-erasure residue sweep: FTS shadow tables + WAL sanity.
+        # This makes I7 enforceable rather than aspirational.
+        self._scan_fts_residue(profile_id, tables, counts)
+        self._scan_wal_residue(counts)
+
+        # C1 — record outstanding obligations against backup snapshots.
+        # Done AFTER the main-DB residue scan so counts reflect live-store state
+        # before we tally the backups outstanding obligation count.
+        # Fail-closed: if the scan itself errors, set backup_scan_failed so
+        # completeness cannot be claimed.
+        backup_obligations_pending = 0
+        if data_root is not None:
+            try:
+                backup_obligations_pending = self._record_backup_obligations(
+                    data_root=data_root,
+                    profile_id=profile_id,
+                    erasure_id=_uuid.uuid4().hex,  # unique id for this obligation batch
+                    counts=counts,
+                )
+                counts["backup_obligations_pending"] = backup_obligations_pending
+            except Exception as exc:
+                logger.error(
+                    "GDPR erase: backup obligation recording FAILED: %s — "
+                    "setting backup_scan_failed to block completeness",
+                    exc,
+                )
+                counts["backup_scan_failed"] = 1
+        else:
+            # Cannot scan backups without data_root — treat as outstanding
+            # obligation so completeness is blocked.
+            counts["backup_obligations_pending"] = 0  # unknown but not confirmed clean
+            # We won't block completeness when data_root is unknown (legacy wrapper)
+            # but we do log the gap.
+            logger.warning(
+                "GDPR erase: backup obligation scan skipped — data_root unknown. "
+                "Backup snapshots may still contain the erased profile's data."
+            )
+
         counts["erasure_complete"] = (
             1
             if (
@@ -528,6 +638,9 @@ class GDPRCompliance:
                 and not counts.get("vector_store_failures")
                 and not counts.get("context_cache_failed")
                 and not counts.get("owner_erasure_incomplete")
+                and not counts.get("backup_obligations_pending")
+                and not counts.get("backup_scan_failed")
+                and not counts.get("fts_residue_rows")
             )
             else 0
         )
@@ -544,6 +657,7 @@ class GDPRCompliance:
                     "basis": "GDPR Art.17 right-to-erasure",
                     "tables_erased": len(tables),
                     "vector_store_failures": counts.get("vector_store_failures", 0),
+                    "backup_obligations_pending": backup_obligations_pending,
                 },
             )
         except Exception as exc:
@@ -677,6 +791,250 @@ class GDPRCompliance:
         logger.info("Entity erasure '%s' in '%s': %s", entity_name, profile_id, counts)
         return counts
 
+    # -- C2: code_graph helpers --------------------------------------------
+
+    def _erase_code_graph(self, data_root: Path) -> dict:
+        """Wipe all rows from the live code_graph.db (C2 — Art.17 scope).
+
+        code_graph.db carries repo paths, file names and symbol names —
+        identifying data in a work context with no profile_id column.  The
+        entire graph is wiped on any Art.17 erasure request.  Fail-open: an
+        error is recorded in the returned dict so the caller can surface it,
+        but it does NOT abort the rest of the erasure.
+        """
+        result: dict = {"rows_deleted": 0}
+        code_graph_path = data_root / "code_graph.db"
+        if not code_graph_path.exists():
+            return result
+        try:
+            conn = sqlite3.connect(str(code_graph_path))
+            conn.isolation_level = None  # autocommit so VACUUM can run
+            try:
+                conn.execute("PRAGMA foreign_keys=OFF")
+                tables = [
+                    row[0]
+                    for row in conn.execute(
+                        "SELECT name FROM sqlite_master WHERE type='table' "
+                        "AND name NOT LIKE 'sqlite_%'"
+                    ).fetchall()
+                ]
+                total = 0
+                conn.execute("BEGIN")
+                for tbl in tables:
+                    # Skip FTS virtual-table shadow files — deleting base rows handles them
+                    if tbl.endswith((
+                        "_fts", "_fts_data", "_fts_idx",
+                        "_fts_content", "_fts_docsize", "_fts_config",
+                    )):
+                        continue
+                    cur = conn.execute(f"DELETE FROM {tbl}")  # noqa: S608
+                    total += cur.rowcount
+                conn.execute("PRAGMA foreign_keys=ON")
+                conn.execute("COMMIT")
+                # VACUUM must run outside any transaction (autocommit mode required)
+                conn.execute("VACUUM")
+                result["rows_deleted"] = total
+            finally:
+                conn.close()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("GDPR erase: code_graph.db wipe failed: %s", exc)
+            result["error"] = str(exc)
+        return result
+
+    def _export_code_graph(self, data_root: Path) -> dict | None:
+        """Read code_graph.db for Art.15 export (C2).
+
+        Returns a dict keyed by table name whose values are lists of row dicts,
+        or None if the file does not exist or cannot be read.
+        """
+        code_graph_path = data_root / "code_graph.db"
+        if not code_graph_path.exists():
+            return None
+        export: dict = {}
+        try:
+            uri = f"file:{code_graph_path}?mode=ro"
+            conn = sqlite3.connect(uri, uri=True, timeout=5)
+            conn.row_factory = sqlite3.Row
+            try:
+                tables = [
+                    row[0]
+                    for row in conn.execute(
+                        "SELECT name FROM sqlite_master WHERE type='table' "
+                        "AND name NOT LIKE 'sqlite_%'"
+                    ).fetchall()
+                ]
+                for tbl in tables:
+                    if tbl.endswith((
+                        "_fts", "_fts_data", "_fts_idx",
+                        "_fts_content", "_fts_docsize", "_fts_config",
+                    )):
+                        continue
+                    try:
+                        rows = conn.execute(
+                            f"SELECT * FROM {tbl} LIMIT 10000"  # noqa: S608
+                        ).fetchall()
+                        export[tbl] = [dict(r) for r in rows]
+                    except Exception as exc:  # noqa: BLE001
+                        logger.warning("GDPR export: code_graph table %s failed: %s", tbl, exc)
+            finally:
+                conn.close()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("GDPR export: code_graph.db read failed: %s", exc)
+            return None
+        return export if export else None
+
+    # -- C1: backup obligation helpers -------------------------------------
+
+    def _record_backup_obligations(
+        self,
+        data_root: Path,
+        profile_id: str,
+        erasure_id: str,
+        counts: dict,
+    ) -> int:
+        """Scan backup snapshots and record any that contain *profile_id* data.
+
+        Returns the total count of pending obligations after recording
+        (including those created in prior erasure passes for the same profile).
+        Fail-closed: any unhandled exception propagates to the caller who sets
+        ``backup_scan_failed`` to block the completeness claim.
+        """
+        bom = _get_backup_obligations_module()
+        if bom is None:
+            logger.warning(
+                "GDPR erase: backup_obligations module unavailable — "
+                "backup residue will not be tracked for profile %r",
+                profile_id,
+            )
+            # Cannot track → treat as pending so completeness is blocked.
+            return 1
+
+        backup_dir = data_root / "backups"
+        retention_days = _retention_days_from_config()
+        store = bom.BackupObligationStore(data_root)
+
+        # Scan all backup snapshots for this profile's data.
+        try:
+            hits = bom.scan_backup_snapshots_for_profile(backup_dir, profile_id)
+        except Exception as exc:  # noqa: BLE001
+            logger.error(
+                "GDPR erase: backup snapshot scan raised: %s — "
+                "failing closed to block completeness",
+                exc,
+            )
+            counts["backup_scan_error"] = str(exc)
+            raise  # propagate so caller sets backup_scan_failed
+
+        snapshots_with_data = len(hits)
+        counts["backup_snapshots_scanned"] = snapshots_with_data
+        recorded = 0
+        for snap_path, snap_epoch in hits:
+            try:
+                store.record(
+                    profile_id=profile_id,
+                    erasure_id=erasure_id,
+                    snapshot_path=snap_path,
+                    snapshot_epoch=snap_epoch,
+                    retention_days=retention_days,
+                )
+                recorded += 1
+            except Exception as exc:  # noqa: BLE001
+                # Recording failure for a single snapshot must not silently
+                # skip the obligation — log and count so completeness is blocked.
+                logger.error(
+                    "GDPR erase: failed to record obligation for snapshot %r: %s",
+                    snap_path, exc,
+                )
+                counts["backup_record_errors"] = counts.get("backup_record_errors", 0) + 1
+                # Still include in pending count (fail-closed).
+                recorded += 1
+
+        counts["backup_obligations_recorded"] = recorded
+        # Return the authoritative pending count (includes obligations from prior
+        # erasure passes for the same profile that were not yet discharged).
+        return store.count_pending(profile_id)
+
+    # -- I7: post-erasure residue scanner ----------------------------------
+
+    def _scan_fts_residue(
+        self,
+        profile_id: str,
+        tables: list[str],
+        counts: dict,
+    ) -> None:
+        """Sweep FTS5 shadow tables for orphaned rowids after main-table erasure.
+
+        FTS5 tables maintain several shadow tables (``_data``, ``_idx``,
+        ``_content``, ``_docsize``, ``_config``).  A correct DELETE + VACUUM
+        cycle via FTS5's ``content=`` mechanism will purge shadow rows
+        automatically.  This sweep cross-checks: if any main memory/facts table
+        is empty for the profile yet the corresponding FTS ``_content`` shadow
+        still has rows, that is residue.  Updates ``counts["fts_residue_rows"]``.
+        """
+        fts_residue = 0
+        try:
+            all_tables = {
+                row[0]
+                for row in self._db.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table'"
+                )
+            }
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("GDPR I7: FTS shadow table listing failed: %s", exc)
+            return
+
+        for tbl in tables:
+            content_shadow = f"{tbl}_fts_content"
+            if content_shadow not in all_tables:
+                continue
+            try:
+                # _fts_content stores one row per indexed row.  After erasure
+                # the content rows should be zero for this profile.  We cannot
+                # filter by profile_id directly (FTS content is a rowid join),
+                # so we count ALL content rows and compare with the main table
+                # row count for this profile (should both be 0).
+                main_count_rows = self._db.execute(
+                    f"SELECT COUNT(*) AS c FROM {tbl} WHERE profile_id = ?",  # noqa: S608
+                    (profile_id,),
+                )
+                main_count = int(dict(main_count_rows[0])["c"]) if main_count_rows else 0
+                if main_count > 0:
+                    # Main table still has rows — not an FTS-shadow issue, already
+                    # caught by the main residue recount.
+                    continue
+                fts_rows = self._db.execute(
+                    f"SELECT COUNT(*) AS c FROM {content_shadow}"  # noqa: S608
+                )
+                fts_count = int(dict(fts_rows[0])["c"]) if fts_rows else 0
+                if fts_count > 0:
+                    logger.warning(
+                        "GDPR I7: FTS shadow %s has %d rows after profile %r erasure",
+                        content_shadow, fts_count, profile_id,
+                    )
+                    fts_residue += fts_count
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "GDPR I7: FTS shadow scan for %s failed: %s", content_shadow, exc
+                )
+        if fts_residue:
+            counts["fts_residue_rows"] = fts_residue
+
+    def _scan_wal_residue(self, counts: dict) -> None:
+        """Trigger a WAL checkpoint so the WAL does not re-introduce erased data.
+
+        After VACUUM the WAL should already be flushed, but an explicit
+        PRAGMA wal_checkpoint(TRUNCATE) ensures the WAL file is zeroed and
+        cannot carry deleted pages forward into a subsequent read.
+        """
+        try:
+            self._db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "GDPR I7: WAL checkpoint failed: %s — WAL may retain erased pages",
+                exc,
+            )
+            counts["wal_checkpoint_failed"] = 1
+
     # -- Audit Trail -------------------------------------------------------
 
     def get_audit_trail(self, profile_id: str, limit: int = 100) -> list[dict]:

package/src/superlocalmemory/core/config.py

@@ -93,7 +93,18 @@ class EmbeddingConfig:
 
 @dataclass(frozen=True)
 class LLMConfig:
-    """LLM provider configuration per mode."""
+    """LLM provider configuration per mode.
+
+    Frozen (restored in 4.0.6). ``frozen=True`` also generates ``__hash__``;
+    dropping it makes every LLMConfig unhashable, which breaks any set/dict-key
+    or cache use at runtime without necessarily failing a test. Updates build a
+    NEW instance via ``dataclasses.replace`` and assign it to the mutable
+    SLMConfig — see ``v3_api.apply_settings_update`` — so immutability here
+    costs nothing.
+
+    All production code creates new instances via LLMConfig(...) or
+    dataclasses.replace().
+    """
 
     provider: str = ""             # "" = no LLM, "ollama", "azure", "openai", "anthropic"
     model: str = ""                # Model name/deployment
@@ -292,6 +303,19 @@ class RetrievalConfig:
     # than holding the recall open.
     cross_encoder_timeout_seconds: float = 15.0
 
+    # v3.9.x (issue #112): plain-HTTP trust for private-LAN reranker endpoints.
+    # When True (the default), numeric RFC1918/ULA/link-local addresses may use
+    # plain HTTP — the same security model as the local reranker, where memory
+    # text only crosses the loopback. Set to False in hardened deployments
+    # (zero-trust networks, shared colocation) to require HTTPS for all
+    # non-loopback hosts, including private-LAN addresses.
+    #
+    # THREAT MODEL: setting this True does NOT prevent a MITM attack by an
+    # adversary on the same physical LAN (e.g. ARP spoofing). This flag means
+    # "my LAN is under my control and I accept that residual risk." It is not
+    # a claim that private-LAN traffic is cryptographically secure.
+    trust_plain_http_lan: bool = True
+
     @property
     def is_remote_cross_encoder(self) -> bool:
         """True when reranking is served by a remote HTTP endpoint."""
@@ -1132,6 +1156,17 @@ class SLMConfig:
     # enterprise deployment preset requests PII redaction.
     pii_redaction: bool = False
 
+    # GDPR / compliance: data-retention window in days.
+    # Default 90 days (owner decision: "configurable through the UI, and
+    # 90 days by default").  Units: days.  Value of 0 means no automatic
+    # expiry.  Consumed by the backup/erasure obligation tracker and any
+    # future retention scheduler.  Configurable via config.json (key
+    # "retention_window_days") or the UI settings panel.
+    # NOTE: this field is intentionally separate from
+    # DeploymentConfig.retention_enabled — the enabled flag gates the
+    # scheduler, while this window controls the duration.
+    retention_window_days: int = 90
+
     def __post_init__(self) -> None:
         if self.db_path is None:
             self.db_path = self.base_dir / DEFAULT_DB_NAME
@@ -1340,6 +1375,12 @@ class SLMConfig:
         )
         config.mesh_enabled = data.get("mesh_enabled", True)
 
+        # v4.0.6: GDPR retention window (additive — defaults to 90 if absent)
+        try:
+            config.retention_window_days = int(data.get("retention_window_days", 90))
+        except (TypeError, ValueError):
+            config.retention_window_days = 90
+
         # V3.4.10: Evolution config
         evo = data.get("evolution", {})
         if evo:
@@ -1566,6 +1607,8 @@ class SLMConfig:
         data["entity_compilation_enabled"] = self.entity_compilation_enabled
         data["entity_compilation_retrieval_boost"] = self.entity_compilation_retrieval_boost
         data["mesh_enabled"] = self.mesh_enabled
+        # v4.0.6: GDPR retention window — always written so load→save is lossless.
+        data["retention_window_days"] = self.retention_window_days
 
         # Typed in-memory config sections.  Preserve any on-disk subkeys this
         # version does not model (forward-compat or externally-tuned fields such

package/src/superlocalmemory/core/context_cache.py

@@ -385,6 +385,7 @@ def read_entry_fast(
     db_path: Path | None = None,
     home_dir: Path | None = None,
     profile_id: str | None = None,
+    require_current_admission: bool = False,
 ) -> CacheEntry | None:
     """Hot-path reader used by the UserPromptSubmit hook.
 
@@ -465,7 +466,7 @@ def read_entry_fast(
         except (ValueError, TypeError):
             fact_ids = []
 
-        return CacheEntry(
+        entry = CacheEntry(
             session_id=session_id,
             topic_sig=topic_sig,
             content=row[0],
@@ -474,10 +475,66 @@ def read_entry_fast(
             computed_at=int(row[3]),
             byte_size=int(row[4]),
         )
+        if require_current_admission and not _cache_fact_ids_are_current(home, entry.fact_ids):
+            return None
+        return entry
     except Exception:  # pragma: no cover — last-resort fail-open
         return None
 
 
+def _cache_fact_ids_are_current(home: Path, fact_ids: list[str]) -> bool:
+    """Prove cached source IDs remain current without loading the engine.
+
+    This is a cache-hit-only backstop for review-gated corrections.  It uses a
+    small read-only SQLite query and treats any unavailable or malformed memory
+    state as a cache miss.  Normal recall remains the authority after a miss.
+    """
+    if not fact_ids or not all(isinstance(fact_id, str) and fact_id for fact_id in fact_ids):
+        return False
+    memory_path = home / "memory.db"
+    if not memory_path.exists():
+        return False
+    try:
+        conn = sqlite3.connect(f"file:{memory_path}?mode=ro", uri=True, timeout=0.25)
+        try:
+            placeholders = ",".join("?" for _ in fact_ids)
+            tables = {
+                row[0]
+                for row in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table' "
+                    "AND name IN ('atomic_facts', 'fact_temporal_validity', 'correction_cases')"
+                )
+            }
+            if {"atomic_facts", "fact_temporal_validity"} - tables:
+                return False
+            correction_join = ""
+            correction_bad = "0"
+            if "correction_cases" in tables:
+                correction_join = (
+                    " LEFT JOIN correction_cases cc ON cc.successor_fact_id=f.fact_id "
+                    "AND cc.status IN ('proposed', 'rejected', 'rolled_back')"
+                )
+                correction_bad = "cc.successor_fact_id IS NOT NULL"
+            rows = conn.execute(
+                "SELECT f.fact_id, tv.system_expired_at, " + correction_bad + " AS correction_blocked "
+                "FROM atomic_facts f "
+                "LEFT JOIN fact_temporal_validity tv ON tv.fact_id=f.fact_id "
+                "AND tv.profile_id=f.profile_id "
+                + correction_join
+                + f" WHERE f.fact_id IN ({placeholders})",
+                tuple(fact_ids),
+            ).fetchall()
+        finally:
+            conn.close()
+    except sqlite3.Error:
+        return False
+    found = {str(row[0]) for row in rows}
+    return (
+        found == set(fact_ids)
+        and all(row[1] is None and not bool(row[2]) for row in rows)
+    )
+
+
 def purge_profile_from_cache_db(db_path: Path, profile_id: str) -> int:
     """Delete all ``context_entries`` rows for *profile_id* from a cache DB file.
 

package/src/superlocalmemory/core/engine_wiring.py

@@ -56,8 +56,11 @@ def init_reranker(retrieval_config: Any) -> Any:
         "cross-encoder/ms-marco-MiniLM-L-12-v2",
     )
     remote_requested = is_remote_cross_encoder_backend(backend)
+    trust_plain_http_lan = getattr(retrieval_config, "trust_plain_http_lan", True)
 
-    error = validate_remote_reranker_config(backend, endpoint)
+    error = validate_remote_reranker_config(
+        backend, endpoint, trust_plain_http_lan=trust_plain_http_lan,
+    )
     if error and remote_requested:
         logger.error(
             "Remote reranker not started — %s Reranking is DISABLED; recall "
@@ -79,6 +82,7 @@ def init_reranker(retrieval_config: Any) -> Any:
                 timeout_seconds=getattr(
                     retrieval_config, "cross_encoder_timeout_seconds", 15.0,
                 ),
+                trust_plain_http_lan=trust_plain_http_lan,
             )
         except RemoteRerankerConfigError as exc:
             logger.error(

package/src/superlocalmemory/core/maintenance.py

@@ -637,11 +637,53 @@ def run_maintenance(
     except Exception as exc:
         logger.warning("Entity summary consolidation failed: %s", exc)
 
+    # 4. Fact consolidation (v3.8.4 concurrency-safe path via DatabaseManager).
+    # Merges clusters of warm/cold atomic facts about the same entity into a
+    # single consolidated fact, archives the originals (NEVER deletes them),
+    # and records provenance in fact_consolidations.
+    #
+    # Uses the DatabaseManager path so LLM calls happen OUTSIDE the write lock:
+    #   - Discover clusters in a short memory_read() (no write lock held).
+    #   - Generate summary OUTSIDE any lock (Ollama/Cloud may take 30s).
+    #   - Write per-cluster inside a short memory_write() (lock held for SQL only).
+    #
+    # NOT on the recall/store hot path.  Runs as part of background maintenance.
+    counts["facts_consolidated"] = 0
+    try:
+        from superlocalmemory.core.fact_consolidator import consolidate_facts
+
+        fc_stats = consolidate_facts(
+            db,
+            profile_id=profile_id,
+            max_clusters=getattr(config, "max_consolidation_clusters", 20),
+            dry_run=False,
+            config=config,
+        )
+        counts["facts_consolidated"] = fc_stats.get("consolidated", 0)
+        if fc_stats.get("consolidated", 0) > 0:
+            logger.info(
+                "Fact consolidation: %d clusters merged, %d facts archived",
+                fc_stats.get("consolidated", 0),
+                fc_stats.get("facts_archived", 0),
+            )
+    except Exception as exc:
+        # WARNING, not debug, and a distinguishable count. Leaving this at debug
+        # with facts_consolidated=0 made a failing consolidation report exactly
+        # the same numbers as a healthy run with nothing to merge, so a step that
+        # never worked would look like a step with no work to do — and nobody
+        # would ever see it in normal logs.
+        counts["facts_consolidated"] = -1
+        logger.warning(
+            "Fact consolidation FAILED during maintenance (reported as -1, "
+            "which is distinct from 0 = nothing to merge): %s", exc,
+        )
+
     logger.info(
         "Maintenance complete: %d backfilled, %d Langevin, %d Fisher-coupled, "
-        "%d Sheaf, %d entity-summaries",
+        "%d Sheaf, %d entity-summaries, %d facts-consolidated",
         counts["langevin_backfilled"], counts["langevin_updated"],
         counts["fisher_coupled"], counts["sheaf_checked"],
         counts["entity_summaries_consolidated"],
+        counts["facts_consolidated"],
     )
     return counts