ltcai 3.5.0 → 4.0.0

package/latticeai/services/agent_runtime.py

@@ -242,6 +242,7 @@ class AgentRuntime:
             user_email=user_email or None,
             graph=self._workspace_graph(),
             workspace_id=scope,
+            mode=getattr(result, "mode", "simulation"),
         )
         self._append_audit_event(
             "multi_agent_run",

package/latticeai/services/app_context.py

@@ -1,27 +1,88 @@
 """Application dependency context for router assembly.
 
-The concrete FastAPI app is still assembled in ``server_app``. This dataclass
-documents the shared dependency boundary for routers and services so future
-extractions can receive a typed context instead of importing the app module.
+``latticeai.app_factory.create_app`` builds one ``AppContext`` per app and
+hands it to router factories, replacing the historical 25-30-kwarg closure
+wiring. Every field defaults to ``None``-ish so tests can construct a context
+carrying only the dependencies a router actually touches.
+
+Fields are grouped by the consumer that motivated them; routers must treat the
+context as read-only.
 """
 
 from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, Optional
 
 
 @dataclass(frozen=True)
 class AppContext:
-    config: Any
-    data_dir: Path
-    static_dir: Path
-    model_router: Any
-    workspace_store: Any
-    workspace_service: Any
-    knowledge_graph: Any
-    local_kg_watcher: Any
-    require_user: Callable[..., str]
-    require_admin: Callable[..., tuple]
+    # ── core configuration / paths ────────────────────────────────────────
+    config: Any = None
+    data_dir: Optional[Path] = None
+    static_dir: Optional[Path] = None
+    base_dir: Optional[Path] = None
+    skills_dir: Optional[Path] = None
+
+    # ── singletons ────────────────────────────────────────────────────────
+    model_router: Any = None
+    workspace_store: Any = None
+    workspace_service: Any = None
+    knowledge_graph: Any = None
+    local_kg_watcher: Any = None
+    chat_service: Any = None
+    context_assembler: Any = None
+    brain_memory: Any = None
+    gardener: Any = None
+    hooks: Any = None
+    realtime_bus: Any = None
+    capability_registry: Any = None
+
+    # ── auth / session callables ──────────────────────────────────────────
+    require_user: Optional[Callable[..., str]] = None
+    require_admin: Optional[Callable[..., tuple]] = None
+    get_current_user: Optional[Callable[..., Optional[str]]] = None
+    load_users: Optional[Callable[[], dict]] = None
+    get_user_role: Optional[Callable[..., str]] = None
+    enforce_rate_limit: Optional[Callable[..., None]] = None
+
+    # ── audit / history callables ─────────────────────────────────────────
+    append_audit_event: Optional[Callable[..., None]] = None
+    get_audit_log: Optional[Callable[[], list]] = None
+    get_history: Optional[Callable[[], list]] = None
+    get_history_user: Optional[Callable[..., dict]] = None
+    save_to_history: Optional[Callable[..., None]] = None
+    clear_history: Optional[Callable[..., dict]] = None
+    clear_conversation: Optional[Callable[..., dict]] = None
+    group_history_conversations: Optional[Callable[..., list]] = None
+    get_conversation_messages: Optional[Callable[..., list]] = None
+    conversation_title: Optional[Callable[..., str]] = None
+
+    # ── knowledge graph access ────────────────────────────────────────────
+    enable_graph: bool = False
+    require_graph: Optional[Callable[[], None]] = None
+    workspace_graph: Optional[Callable[[], Any]] = None
+    graph_stats: Optional[Callable[[], dict]] = None
+
+    # ── workspace payload providers / skills ──────────────────────────────
+    workspace_models: Optional[Callable[[], dict]] = None
+    workspace_settings: Optional[Callable[[], dict]] = None
+    scan_environment: Optional[Callable[[], Any]] = None
+    local_sysinfo: Optional[Callable[..., Any]] = None
+    get_recommendations: Optional[Callable[..., Any]] = None
+    fetch_skills_marketplace: Optional[Callable[..., Any]] = None
+    install_skill: Optional[Callable[..., Any]] = None
+    remove_skill_directory: Optional[Callable[..., dict]] = None
+    redact_secret_text: Optional[Callable[[str], str]] = None
+    ui_file_response: Optional[Callable[..., Any]] = None
+
+    # ── models ────────────────────────────────────────────────────────────
+    public_model: str = ""
+    local_model: str = ""
 
+    # ── integrations ──────────────────────────────────────────────────────
+    # Fired as on_chat_message(role, text, source) after a chat exchange is
+    # persisted; ``None`` means no external chat mirror is registered. The
+    # telegram bridge subscribes here only when ENABLE_TELEGRAM is truthy.
+    on_chat_message: Optional[Callable[..., None]] = None

package/latticeai/services/ingestion.py

@@ -0,0 +1,318 @@
+"""Unified ingestion pipeline — the single write-side seam into the Knowledge Graph.
+
+v3.6.0 Knowledge Graph First principle: *no data source bypasses the Knowledge
+Graph and no source creates an isolated silo*. Every source — local files,
+connected folders, PDFs/Markdown/text/code, web URLs, browser tabs — is
+normalized into one :class:`IngestionItem` and pushed through one
+:meth:`IngestionPipeline.ingest` entrypoint:
+
+    Source → normalize → content hash → (file | text) ingest → provenance
+
+The pipeline is deliberately thin. It owns normalization, idempotency reporting,
+provenance capture, and — crucially — routing every ingest through the shared
+``dispatch_tool`` lifecycle so ``pre_tool``/``post_tool`` hooks fire on data
+ingestion exactly as they do on tool calls. The heavy graph construction lives in
+:class:`knowledge_graph.KnowledgeGraphStore` (``ingest_document`` for files,
+``ingest_source`` for text/web), which this module composes rather than
+re-implements.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.hooks import dispatch_tool
+
+# Source types that arrive as a file on disk (read via ingest_document).
+FILE_SOURCE_TYPES = frozenset({"file", "local_file", "upload", "pdf"})
+# Source types that arrive as extracted text (read via ingest_source).
+TEXT_SOURCE_TYPES = frozenset(
+    {"web_url", "browser_tab", "text", "markdown", "note", "code", "clipboard"}
+)
+# Conversational exchanges (read via ingest_message — role/content semantics,
+# conversation chaining). v4: chat and MCP messages stop bypassing the
+# pipeline, so they carry provenance and fire the hook lifecycle like every
+# other source.
+CHAT_SOURCE_TYPES = frozenset({"chat_message", "mcp_message"})
+# Typed memory records (read via ingest_event → Decision/Experience/Event
+# nodes). The Memory System writes through the same door as everything else.
+MEMORY_SOURCE_TYPES = frozenset({"decision", "experience", "workspace_event"})
+_MEMORY_NODE_TYPES = {"decision": "Decision", "experience": "Experience", "workspace_event": "Event"}
+
+DEFAULT_MAX_TEXT_BYTES = 5 * 1024 * 1024  # 5 MB of extracted text per item
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class IngestionItem:
+    """A single thing to ingest, normalized across every source type."""
+
+    source_type: str
+    title: Optional[str] = None
+    text: Optional[str] = None          # text/web sources
+    path: Optional[str] = None          # file sources
+    source_uri: Optional[str] = None
+    mime_type: Optional[str] = None
+    owner: Optional[str] = None
+    workspace_id: Optional[str] = None
+    permissions: Optional[Dict[str, Any]] = None
+    captured_at: Optional[str] = None
+    modified_at: Optional[str] = None
+    conversation_id: Optional[str] = None
+    agent_used: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IngestionResult:
+    """The outcome of one ingestion, including provenance and idempotency."""
+
+    status: str                         # ok | unavailable | blocked | failed
+    source_type: str
+    node_id: Optional[str] = None
+    source_node_id: Optional[str] = None
+    content_hash: Optional[str] = None
+    title: Optional[str] = None
+    chunk_ids: List[str] = field(default_factory=list)
+    chunk_count: int = 0
+    duplicate: bool = False
+    embedded: bool = False
+    indexing_status: str = "pending"    # indexed | skipped | failed | pending
+    provenance_id: Optional[str] = None
+    detail: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "source_type": self.source_type,
+            "node_id": self.node_id,
+            "source_node_id": self.source_node_id,
+            "content_hash": self.content_hash,
+            "title": self.title,
+            "chunk_ids": self.chunk_ids,
+            "chunk_count": self.chunk_count,
+            "duplicate": self.duplicate,
+            "embedded": self.embedded,
+            "indexing_status": self.indexing_status,
+            "provenance_id": self.provenance_id,
+            "detail": self.detail,
+        }
+
+
+class IngestionPipeline:
+    """Single normalized entrypoint that feeds every source into the graph."""
+
+    def __init__(
+        self,
+        knowledge_graph: Any,
+        *,
+        hooks: Any = None,
+        enable_graph: bool = True,
+        audit: Optional[Any] = None,
+        max_text_bytes: int = DEFAULT_MAX_TEXT_BYTES,
+        pipeline_name: str = "unified-ingestion",
+    ) -> None:
+        self._kg = knowledge_graph
+        self._hooks = hooks
+        self._enable = bool(enable_graph)
+        self._audit = audit
+        self._max_text_bytes = int(max_text_bytes)
+        self._pipeline_name = pipeline_name
+
+    def available(self) -> bool:
+        return self._enable and self._kg is not None
+
+    # ── public API ───────────────────────────────────────────────────────────
+    def ingest(self, item: IngestionItem, *, user_email: Optional[str] = None) -> IngestionResult:
+        """Normalize, hash, route through dispatch_tool, and record provenance."""
+        source_type = str(item.source_type or "text").strip()
+        if not self.available():
+            return IngestionResult(
+                status="unavailable", source_type=source_type,
+                indexing_status="skipped",
+                detail="Knowledge Graph is disabled (LATTICEAI_ENABLE_GRAPH).",
+            )
+
+        captured_at = item.captured_at or _now_iso()
+        owner = item.owner or user_email
+        tool_name = f"kg_ingest.{source_type}"
+        # Only the keys are read by the hook payload, so this dict is safe/cheap.
+        args = {
+            "source_type": source_type,
+            "source_uri": item.source_uri,
+            "owner": owner,
+            "workspace_id": item.workspace_id,
+        }
+
+        def _run() -> Dict[str, Any]:
+            if source_type in CHAT_SOURCE_TYPES:
+                return self._ingest_chat(item, source_type=source_type, owner=owner)
+            if source_type in MEMORY_SOURCE_TYPES:
+                return self._ingest_memory_record(item, source_type=source_type, owner=owner)
+            if source_type in FILE_SOURCE_TYPES or (item.path and not item.text):
+                return self._ingest_file(item, source_type=source_type, owner=owner, captured_at=captured_at)
+            return self._ingest_text(item, source_type=source_type, owner=owner, captured_at=captured_at)
+
+        try:
+            raw = dispatch_tool(
+                self._hooks, tool_name, args, _run,
+                user_email=user_email, workspace_id=item.workspace_id, source="ingestion",
+            )
+        except PermissionError as exc:
+            return IngestionResult(
+                status="blocked", source_type=source_type,
+                indexing_status="skipped", detail=str(exc),
+            )
+        except FileNotFoundError as exc:
+            return IngestionResult(
+                status="failed", source_type=source_type,
+                indexing_status="failed", detail=str(exc),
+            )
+        except Exception as exc:  # noqa: BLE001 — surface as a failed result, never crash the caller
+            return IngestionResult(
+                status="failed", source_type=source_type,
+                indexing_status="failed", detail=str(exc),
+            )
+
+        node_id = raw.get("node_id")
+        content_hash = raw.get("content_hash") or raw.get("sha256")
+        chunk_ids = list(raw.get("chunk_ids") or [])
+        embedded = bool(self._kg.node_is_embedded(node_id)) if node_id else False
+        title = raw.get("title") or item.title
+
+        prov = self._kg.record_provenance(
+            node_id=node_id,
+            source_type=source_type,
+            pipeline=self._pipeline_name,
+            source_uri=item.source_uri,
+            content_hash=content_hash,
+            title=title,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            embedded=embedded,
+            linked=bool(raw.get("source_node_id")),
+            duplicate=bool(raw.get("duplicate")),
+            agent_used=item.agent_used,
+            chunk_count=len(chunk_ids),
+            permissions=item.permissions,
+            metadata=item.metadata,
+        )
+        if self._audit is not None:
+            try:
+                self._audit(
+                    "kg_ingest",
+                    {
+                        "source_type": source_type, "node_id": node_id,
+                        "content_hash": content_hash, "duplicate": bool(raw.get("duplicate")),
+                    },
+                    user_email,
+                )
+            except Exception:  # noqa: BLE001 — audit must never break ingestion
+                pass
+
+        return IngestionResult(
+            status="ok",
+            source_type=source_type,
+            node_id=node_id,
+            source_node_id=raw.get("source_node_id"),
+            content_hash=content_hash,
+            title=title,
+            chunk_ids=chunk_ids,
+            chunk_count=len(chunk_ids),
+            duplicate=bool(raw.get("duplicate")),
+            embedded=embedded,
+            indexing_status="indexed",
+            provenance_id=prov.get("id"),
+        )
+
+    # ── routing helpers ──────────────────────────────────────────────────────
+    def _ingest_text(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        text = item.text or ""
+        if len(text.encode("utf-8", "ignore")) > self._max_text_bytes:
+            raise ValueError(
+                f"Text payload exceeds the {self._max_text_bytes // (1024 * 1024)}MB ingestion limit."
+            )
+        title = item.title or item.source_uri or source_type
+        return self._kg.ingest_source(
+            source_type=source_type,
+            title=title,
+            text=text,
+            source_uri=item.source_uri,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            conversation_id=item.conversation_id,
+            metadata={"mime_type": item.mime_type, **(item.metadata or {})},
+        )
+
+    def _ingest_chat(self, item, *, source_type, owner) -> Dict[str, Any]:
+        text = item.text or ""
+        meta = item.metadata or {}
+        role = str(meta.get("role") or "user")
+        result = self._kg.ingest_message(
+            role,
+            text,
+            user_email=owner,
+            user_nickname=meta.get("user_nickname"),
+            source=meta.get("source") or source_type,
+            conversation_id=item.conversation_id,
+            raw=meta.get("raw"),
+        )
+        # ingest_message reports message/response node ids; normalize the keys
+        # the provenance step expects.
+        result.setdefault("node_id", result.get("node_id") or result.get("message_node_id") or result.get("id"))
+        result.setdefault("title", item.title or text[:80])
+        return result
+
+    def _ingest_memory_record(self, item, *, source_type, owner) -> Dict[str, Any]:
+        node_type = _MEMORY_NODE_TYPES[source_type]
+        meta = item.metadata or {}
+        result = self._kg.ingest_event(
+            node_type,
+            item.title or (item.text or node_type)[:120],
+            user_email=owner,
+            source=meta.get("source") or source_type,
+            conversation_id=item.conversation_id,
+            metadata={**meta, "detail": (item.text or "")[:2000]},
+        )
+        result.setdefault("node_id", result.get("node_id") or result.get("id"))
+        result.setdefault("title", item.title)
+        return result
+
+    def _ingest_file(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        if not item.path:
+            raise ValueError("File ingestion requires a path.")
+        path = Path(item.path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        return self._kg.ingest_document(
+            path,
+            original_filename=item.title or path.name,
+            mime_type=item.mime_type,
+            uploader=owner,
+            conversation_id=item.conversation_id,
+            extracted=item.metadata.get("extracted") if item.metadata else None,
+            source_type=source_type,
+            source_uri=item.source_uri or str(path),
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+        )
+
+
+def content_hash_text(text: str) -> str:
+    """Canonical content hash for a text payload (matches store hashing scheme)."""
+    return hashlib.sha256((text or "").encode("utf-8", "ignore")).hexdigest()

package/latticeai/services/kg_portability.py

@@ -0,0 +1,207 @@
+"""Knowledge Graph portability — local export / import / backup / restore.
+
+The Knowledge Graph is the user's durable asset, so it must be portable without
+any cloud service. Two complementary mechanisms, both fully local:
+
+* **Logical export/import** (JSON): nodes/edges/chunks/sources/provenance with a
+  versioned header (schema + projection + embed-dim). Re-embeds on import, so it
+  is portable across machines.
+* **Binary backup/restore** (ZIP): a faithful snapshot of the SQLite DB (incl.
+  vector embeddings) plus the blob directory, integrity-checked, for
+  same-machine recovery.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import tempfile
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+FORMAT = "latticeai.kg.export"
+FORMAT_VERSION = 1
+BACKUP_FORMAT = "latticeai.kg.backup"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _stamp() -> str:
+    return _now_iso().replace(":", "").replace("-", "").replace(".", "")[:15]
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for block in iter(lambda: fh.read(65536), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+class KGPortabilityService:
+    def __init__(self, *, knowledge_graph: Any, data_dir, enable_graph: bool = True, device_identity: Any = None) -> None:
+        self._kg = knowledge_graph
+        self._data_dir = Path(data_dir)
+        self._enable = bool(enable_graph)
+        self._exports_dir = self._data_dir / "workspace_exports"
+        # v4 sovereignty: when a DeviceIdentity is wired, exports are signed
+        # and imports record origin provenance. Pre-v4 unsigned bundles stay
+        # importable locally (origin='unsigned-legacy') — signatures are
+        # mandatory only on the Brain Network peer path.
+        self._identity = device_identity
+
+    def available(self) -> bool:
+        return self._enable and self._kg is not None
+
+    def _require(self) -> None:
+        if not self.available():
+            raise RuntimeError("Knowledge Graph is disabled (LATTICEAI_ENABLE_GRAPH).")
+
+    # ── logical export / import ──────────────────────────────────────────────
+    def export(self, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
+        self._require()
+        data = self._kg.export_graph_data(workspace_id=workspace_id)
+        header = {
+            "format": FORMAT,
+            "format_version": FORMAT_VERSION,
+            **self._kg.schema_versions(),
+            "exported_at": _now_iso(),
+            "workspace_id": workspace_id,
+            "counts": data.get("counts"),
+        }
+        artifact = {"header": header, **data}
+        if self._identity is not None:
+            artifact["signature"] = self._identity.sign_manifest(header)
+        return artifact
+
+    def export_to_file(self, path=None, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
+        artifact = self.export(workspace_id=workspace_id)
+        self._exports_dir.mkdir(parents=True, exist_ok=True)
+        path = Path(path) if path else self._exports_dir / f"kg-export-{_stamp()}.json"
+        path.write_text(json.dumps(artifact, ensure_ascii=False, indent=2), encoding="utf-8")
+        return {"path": str(path), "header": artifact["header"], "bytes": path.stat().st_size}
+
+    def import_data(self, artifact: Dict[str, Any], *, mode: str = "merge", dry_run: bool = False) -> Dict[str, Any]:
+        self._require()
+        if not isinstance(artifact, dict) or "nodes" not in artifact:
+            raise ValueError("Invalid Knowledge Graph export artifact.")
+        if mode not in ("merge", "replace"):
+            raise ValueError("mode must be 'merge' or 'replace'.")
+        origin = "unsigned-legacy"
+        signature = artifact.get("signature")
+        if signature:
+            from latticeai.brain.identity import verify_manifest
+
+            if not verify_manifest(artifact.get("header") or {}, signature):
+                raise ValueError("Bundle signature verification failed — refusing to import.")
+            origin = f"device:{signature.get('fingerprint') or 'unknown'}"
+        result = self._kg.import_graph_data(artifact, mode=mode, dry_run=dry_run)
+        result["header"] = artifact.get("header")
+        result["origin"] = origin
+        result["signed"] = bool(signature)
+        if not dry_run:
+            try:
+                self._kg.record_provenance(
+                    node_id="import:" + str((artifact.get("header") or {}).get("exported_at") or _now_iso()),
+                    source_type="bundle_import",
+                    pipeline="kg-portability",
+                    owner=None,
+                    metadata={"origin": origin, "mode": mode,
+                              "counts": (artifact.get("header") or {}).get("counts")},
+                )
+            except Exception:
+                pass
+        return result
+
+    def import_from_file(self, path, *, mode: str = "merge", dry_run: bool = False) -> Dict[str, Any]:
+        artifact = json.loads(Path(path).read_text(encoding="utf-8"))
+        return self.import_data(artifact, mode=mode, dry_run=dry_run)
+
+    # ── binary backup / restore ──────────────────────────────────────────────
+    def backup(self, dest_path=None) -> Dict[str, Any]:
+        self._require()
+        self._exports_dir.mkdir(parents=True, exist_ok=True)
+        dest = Path(dest_path) if dest_path else self._exports_dir / f"kg-backup-{_stamp()}.zip"
+        with tempfile.TemporaryDirectory() as tmp_s:
+            tmp = Path(tmp_s)
+            db_copy = tmp / "knowledge_graph.sqlite"
+            self._kg.backup_database(db_copy)
+            manifest = {
+                "format": BACKUP_FORMAT,
+                "format_version": FORMAT_VERSION,
+                **self._kg.schema_versions(),
+                "created_at": _now_iso(),
+                "db_sha256": _sha256_file(db_copy),
+                "has_blobs": Path(self._kg.blob_dir).exists(),
+            }
+            with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.write(db_copy, "knowledge_graph.sqlite")
+                zf.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2))
+                blob_dir = Path(self._kg.blob_dir)
+                if blob_dir.exists():
+                    for f in blob_dir.rglob("*"):
+                        if f.is_file():
+                            zf.write(f, f"blobs/{f.relative_to(blob_dir)}")
+        return {"path": str(dest), "bytes": dest.stat().st_size, "manifest": manifest}
+
+    def restore(self, archive_path, *, verify: bool = True) -> Dict[str, Any]:
+        self._require()
+        archive = Path(archive_path)
+        if not archive.exists():
+            raise FileNotFoundError(f"Backup archive not found: {archive}")
+        with zipfile.ZipFile(archive) as zf:
+            names = zf.namelist()
+            if "knowledge_graph.sqlite" not in names:
+                raise ValueError("Archive is missing knowledge_graph.sqlite.")
+            manifest = json.loads(zf.read("manifest.json")) if "manifest.json" in names else {}
+            with tempfile.TemporaryDirectory() as tmp_s:
+                tmp = Path(tmp_s)
+                zf.extractall(tmp)
+                db_src = tmp / "knowledge_graph.sqlite"
+                if verify and manifest.get("db_sha256"):
+                    if _sha256_file(db_src) != manifest["db_sha256"]:
+                        raise ValueError("Backup integrity check failed (db sha256 mismatch).")
+                db_dest = Path(self._kg.db_path)
+                blob_dest = Path(self._kg.blob_dir)
+                db_dest.parent.mkdir(parents=True, exist_ok=True)
+                # Drop the live DB + stale WAL/SHM siblings so the restored copy
+                # is authoritative (no stale journal overlaying old pages).
+                for sib in (db_dest, Path(str(db_dest) + "-wal"), Path(str(db_dest) + "-shm")):
+                    if sib.exists():
+                        sib.unlink()
+                shutil.copyfile(db_src, db_dest)
+                blob_src = tmp / "blobs"
+                if blob_src.exists():
+                    if blob_dest.exists():
+                        shutil.rmtree(blob_dest)
+                    shutil.copytree(blob_src, blob_dest)
+                else:
+                    blob_dest.mkdir(parents=True, exist_ok=True)
+        stats = self._kg.stats()
+        return {
+            "restored": True,
+            "manifest": manifest,
+            "nodes": sum(stats.get("nodes", {}).values()),
+        }
+
+    # ── status surface ───────────────────────────────────────────────────────
+    def snapshot_metadata(self) -> Dict[str, Any]:
+        if not self.available():
+            return {"available": False}
+        return {
+            "available": True,
+            **self._kg.schema_versions(),
+            "stats": self._kg.stats(),
+            "provenance": self._kg.provenance_stats(),
+        }
+
+    def recent_ingestions(self, *, limit: int = 50, source_type: Optional[str] = None) -> Dict[str, Any]:
+        """Recent provenance records (newest first) for the ingestion-sources UI."""
+        if not self.available():
+            return {"items": [], "count": 0}
+        return self._kg.list_provenance(limit=limit, source_type=source_type)