ltcai 4.1.0 → 4.3.0

package/frontend/src/pages/System.tsx

@@ -275,10 +275,44 @@ function NetworkPanel() {
 }
 
 function SettingsPanel() {
+  const qc = useQueryClient();
   const { theme, setTheme, mode, setMode } = useAppStore();
   const health = useQuery({ queryKey: ["health"], queryFn: latticeApi.health });
   const sys = useQuery({ queryKey: ["sysinfo"], queryFn: latticeApi.sysinfo });
   const comp = useQuery({ queryKey: ["computerMemory"], queryFn: latticeApi.computerMemory });
+  const storage = useQuery({ queryKey: ["brainStorage"], queryFn: latticeApi.brainStorage });
+  const backupHealth = useQuery({ queryKey: ["backupHealth"], queryFn: latticeApi.backupHealth });
+  const [dsn, setDsn] = React.useState("");
+  const [schema, setSchema] = React.useState("lattice_brain");
+  const [dockerConsent, setDockerConsent] = React.useState(false);
+  const [archivePath, setArchivePath] = React.useState("");
+  const [restorePath, setRestorePath] = React.useState("");
+  const [archivePassphrase, setArchivePassphrase] = React.useState("");
+  const [restoreConfirm, setRestoreConfirm] = React.useState(false);
+  const docker = useMutation({ mutationFn: (consent: boolean) => latticeApi.dockerPostgres({ consent, dry_run: !consent, port: 5432 }) });
+  const migration = useMutation({
+    mutationFn: () => latticeApi.migratePostgres({ dsn, schema_name: schema || "lattice_brain", dry_run: true }),
+  });
+  const archiveCreate = useMutation({
+    mutationFn: () => latticeApi.brainArchive({ path: archivePath.trim() || null, passphrase: archivePassphrase }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["backupHealth"] }),
+  });
+  const archiveInspect = useMutation({
+    mutationFn: () => latticeApi.brainArchiveInspect({ path: restorePath, passphrase: archivePassphrase || null }),
+  });
+  const archiveVerify = useMutation({
+    mutationFn: () => latticeApi.brainArchiveVerify({ path: restorePath, passphrase: archivePassphrase }),
+  });
+  const archiveDryRun = useMutation({
+    mutationFn: () => latticeApi.brainArchiveRestore({ path: restorePath, passphrase: archivePassphrase, dry_run: true, confirm: false }),
+  });
+  const archiveRestore = useMutation({
+    mutationFn: () => latticeApi.brainArchiveRestore({ path: restorePath, passphrase: archivePassphrase, dry_run: false, confirm: restoreConfirm }),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ["brainStorage"] });
+      qc.invalidateQueries({ queryKey: ["backupHealth"] });
+    },
+  });
   return (
     <div className="grid gap-4 xl:grid-cols-3">
       <Card>
@@ -300,6 +334,62 @@ function SettingsPanel() {
       <DataPanel title="Host telemetry" result={sys.data}>
         {(data) => <JsonView value={data} />}
       </DataPanel>
+      <DataPanel title="Brain storage" result={storage.data} className="xl:col-span-3">
+        {(data) => <JsonView value={data} />}
+      </DataPanel>
+      <DataPanel title="Backup health" result={backupHealth.data} className="xl:col-span-3">
+        {(data) => <JsonView value={data} />}
+      </DataPanel>
+      <Card className="xl:col-span-3">
+        <CardHeader>
+          <CardTitle>.latticebrain portability</CardTitle>
+          <CardDescription>Encrypted export, inspect, verify, dry-run restore, and confirmed restore use the Brain portability API.</CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-3">
+          <div className="grid gap-2 sm:grid-cols-[1fr_1fr]">
+            <Input value={archivePath} onChange={(e) => setArchivePath(e.target.value)} placeholder="export path (optional)" />
+            <Input value={restorePath} onChange={(e) => setRestorePath(e.target.value)} placeholder="archive path for inspect/restore" />
+          </div>
+          <Input type="password" value={archivePassphrase} onChange={(e) => setArchivePassphrase(e.target.value)} placeholder="archive passphrase" />
+          <div className="flex flex-wrap gap-2">
+            <Button onClick={() => archiveCreate.mutate()} disabled={!archivePassphrase || archiveCreate.isPending}>Export archive</Button>
+            <Button variant="outline" onClick={() => archiveInspect.mutate()} disabled={!restorePath || archiveInspect.isPending}>Inspect</Button>
+            <Button variant="outline" onClick={() => archiveVerify.mutate()} disabled={!restorePath || !archivePassphrase || archiveVerify.isPending}>Verify</Button>
+            <Button variant="outline" onClick={() => archiveDryRun.mutate()} disabled={!restorePath || !archivePassphrase || archiveDryRun.isPending}>Restore dry run</Button>
+            <label className="flex items-center gap-2 rounded-md border border-border px-3 py-2 text-sm">
+              <input type="checkbox" checked={restoreConfirm} onChange={(e) => setRestoreConfirm(e.target.checked)} />
+              Confirm restore
+            </label>
+            <Button variant="destructive" onClick={() => archiveRestore.mutate()} disabled={!restorePath || !archivePassphrase || !restoreConfirm || archiveRestore.isPending}>Restore</Button>
+          </div>
+          {[archiveCreate.data, archiveInspect.data, archiveVerify.data, archiveDryRun.data, archiveRestore.data].filter(Boolean).map((item, i) => (
+            <JsonView key={i} value={item?.data || item?.error} />
+          ))}
+        </CardContent>
+      </Card>
+      <Card className="xl:col-span-3">
+        <CardHeader>
+          <CardTitle>Postgres scale mode</CardTitle>
+          <CardDescription>Opt-in migration and Docker setup; SQLite remains the default.</CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-3">
+          <div className="grid gap-2 sm:grid-cols-[1fr_220px]">
+            <Input value={dsn} onChange={(e) => setDsn(e.target.value)} placeholder="postgresql://user:pass@127.0.0.1:5432/lattice_brain" />
+            <Input value={schema} onChange={(e) => setSchema(e.target.value)} placeholder="schema" />
+          </div>
+          <div className="flex flex-wrap gap-2">
+            <Button variant="outline" onClick={() => docker.mutate(false)} disabled={docker.isPending}>Docker plan</Button>
+            <label className="flex items-center gap-2 rounded-md border border-border px-3 py-2 text-sm">
+              <input type="checkbox" checked={dockerConsent} onChange={(e) => setDockerConsent(e.target.checked)} />
+              Consent to start Docker
+            </label>
+            <Button onClick={() => docker.mutate(true)} disabled={!dockerConsent || docker.isPending}>Start Docker</Button>
+            <Button variant="outline" onClick={() => migration.mutate()} disabled={!dsn || migration.isPending}>Plan migration</Button>
+          </div>
+          {docker.data ? <JsonView value={docker.data.data || docker.data.error} /> : null}
+          {migration.data ? <JsonView value={migration.data.data || migration.data.error} /> : null}
+        </CardContent>
+      </Card>
       <DataPanel title="Computer memory" result={comp.data} className="xl:col-span-3">
         {(data) => (
           <div className="space-y-3">
@@ -321,6 +411,7 @@ function AdminPanel() {
   const audit = useQuery({ queryKey: ["adminAudit"], queryFn: latticeApi.adminAudit });
   const roles = useQuery({ queryKey: ["adminRoles"], queryFn: latticeApi.adminRoles });
   const policies = useQuery({ queryKey: ["adminPolicies"], queryFn: latticeApi.adminPolicies });
+  const hardening = useQuery({ queryKey: ["adminProductHardening"], queryFn: latticeApi.adminProductHardening });
   const security = useQuery({ queryKey: ["adminSecurity"], queryFn: latticeApi.adminSecurity });
   const vpc = useQuery({ queryKey: ["vpcStatus"], queryFn: latticeApi.vpcStatus });
   return (
@@ -330,6 +421,7 @@ function AdminPanel() {
       <DataPanel title="Audit" result={audit.data}>{(data) => <EntityList items={(data as Record<string, unknown>).recent_events || data} titleKey="act" metaKey="sev" />}</DataPanel>
       <DataPanel title="Roles" result={roles.data}>{(data) => <JsonView value={data} />}</DataPanel>
       <DataPanel title="Policies" result={policies.data}>{(data) => <JsonView value={data} />}</DataPanel>
+      <DataPanel title="Product hardening" result={hardening.data}>{(data) => <JsonView value={data} />}</DataPanel>
       <DataPanel title="Security overview" result={security.data}>{(data) => <JsonView value={data} />}</DataPanel>
       <DataPanel title="Private VPC" result={vpc.data} className="xl:col-span-2">
         {(data) => (

package/kg_schema.py

@@ -1,3 +1,3 @@
 """Compatibility shim for the v4 Knowledge Graph schema."""
 
-from latticeai.brain.schema import *  # noqa: F403,F401
+from lattice_brain.schema import *  # noqa: F403,F401

package/knowledge_graph.py

@@ -1,10 +1,10 @@
-"""Compatibility shim for the v4 brain store.
+"""Compatibility shim for the v4.2 lattice-brain store.
 
-The implementation now lives under :mod:`latticeai.brain`. Root imports are
+The implementation now lives under :mod:`lattice_brain`. Root imports are
 kept for older integrations and tests.
 """
 
-from latticeai.brain._kg_common import (  # noqa: F401
+from lattice_brain._kg_common import (  # noqa: F401
     EDGE_VERB,
     GRAPH_SCHEMA_VERSION,
     LOCAL_CODE_EXTENSIONS,
@@ -24,7 +24,7 @@ from latticeai.brain._kg_common import (  # noqa: F401
     _slug,
     set_llm_router,
 )
-from latticeai.brain.store import KnowledgeGraphStore
+from lattice_brain.store import KnowledgeGraphStore
 
 __all__ = [
     "KnowledgeGraphStore",

package/lattice_brain/__init__.py

@@ -0,0 +1,70 @@
+"""lattice-brain — independent Brain Core package for Lattice AI.
+
+Heavy graph modules are lazy-loaded so storage and archive utilities remain
+usable without importing the FastAPI application or creating runtime globals.
+"""
+
+from .archive import BrainArchivePaths, EncryptedBrainArchive
+from .core import BrainCore, BrainCoreConfig
+from .storage import (
+    DockerPostgresPlan,
+    DockerPostgresWizard,
+    PostgresConfig,
+    PostgresEngine,
+    SQLiteEngine,
+    SQLiteToPostgresMigrator,
+    StorageCapabilities,
+    StorageEngine,
+    StorageUnavailable,
+    storage_from_env,
+)
+
+__version__ = "4.3.0"
+
+__all__ = [
+    "AssembledContext",
+    "BrainArchivePaths",
+    "BrainCore",
+    "BrainCoreConfig",
+    "BrainMemory",
+    "ContextAssembler",
+    "ContextSection",
+    "ConversationStore",
+    "DockerPostgresPlan",
+    "DockerPostgresWizard",
+    "EncryptedBrainArchive",
+    "KnowledgeGraphStore",
+    "PostgresConfig",
+    "PostgresEngine",
+    "SQLiteEngine",
+    "SQLiteToPostgresMigrator",
+    "StorageCapabilities",
+    "StorageEngine",
+    "StorageUnavailable",
+    "storage_from_env",
+    "__version__",
+]
+
+
+def __getattr__(name: str):
+    if name in {"AssembledContext", "ContextAssembler", "ContextSection"}:
+        from .context import AssembledContext, ContextAssembler, ContextSection
+
+        return {
+            "AssembledContext": AssembledContext,
+            "ContextAssembler": ContextAssembler,
+            "ContextSection": ContextSection,
+        }[name]
+    if name == "ConversationStore":
+        from .conversations import ConversationStore
+
+        return ConversationStore
+    if name == "BrainMemory":
+        from .memory import BrainMemory
+
+        return BrainMemory
+    if name == "KnowledgeGraphStore":
+        from .store import KnowledgeGraphStore
+
+        return KnowledgeGraphStore
+    raise AttributeError(name)

package/lattice_brain/_kg_common.py

@@ -0,0 +1 @@
+from latticeai.brain._kg_common import *  # noqa: F401,F403

package/lattice_brain/archive.py

@@ -0,0 +1,446 @@
+"""Encrypted .latticebrain archive support.
+
+The archive is intentionally self-contained and local-only: the encrypted
+payload holds the SQLite brain, blob store, portable JSON state, signed export
+bundles, and public metadata needed to inspect/verify/restore on another
+machine without contacting a service.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import json
+import os
+import shutil
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Any, Dict, Iterable, List, Optional
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+
+ARCHIVE_FORMAT = "latticebrain.encrypted"
+ARCHIVE_VERSION = 2
+KDF_ITERATIONS = 390_000
+PORTABLE_DATA_FILES = (
+    "users.json",
+    "chat_history.json",
+    "workspace_os.json",
+    "vpc_config.json",
+    "mcp_installs.json",
+    "audit_log.json",
+    "sso_config.json",
+    "hooks.json",
+    "invitations.json",
+    "agent_registry.json",
+    "brain_peers.json",
+)
+PORTABLE_EXPORT_SUFFIXES = (".json", ".zip")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _derive_key(passphrase: str, salt: bytes) -> bytes:
+    if not passphrase:
+        raise ValueError("A passphrase is required for encrypted .latticebrain archives.")
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=KDF_ITERATIONS,
+    )
+    return kdf.derive(passphrase.encode("utf-8"))
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+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()
+
+
+def _safe_json(value: Any) -> Any:
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        if isinstance(value, dict):
+            return {str(k): _safe_json(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [_safe_json(v) for v in value]
+        return str(value)
+
+
+def _assert_safe_member(name: str) -> PurePosixPath:
+    path = PurePosixPath(name)
+    if path.is_absolute() or ".." in path.parts:
+        raise ValueError(f"Archive payload contains unsafe path: {name}")
+    return path
+
+
+@dataclass(frozen=True)
+class BrainArchivePaths:
+    db_path: Path
+    blob_dir: Optional[Path] = None
+    data_dir: Optional[Path] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class EncryptedBrainArchive:
+    """Create and restore encrypted local Brain Core archives."""
+
+    def __init__(self, paths: BrainArchivePaths) -> None:
+        self.paths = paths
+
+    def _iter_payload_files(self) -> Iterable[tuple[Path, str]]:
+        yield Path(self.paths.db_path), "knowledge_graph.sqlite"
+        if self.paths.blob_dir and self.paths.blob_dir.exists():
+            blob_root = Path(self.paths.blob_dir)
+            for file in sorted(blob_root.rglob("*")):
+                if file.is_file():
+                    yield file, f"blobs/{file.relative_to(blob_root).as_posix()}"
+        if self.paths.data_dir and Path(self.paths.data_dir).exists():
+            data_root = Path(self.paths.data_dir)
+            for name in PORTABLE_DATA_FILES:
+                file = data_root / name
+                if file.is_file():
+                    yield file, f"data/{name}"
+            exports = data_root / "workspace_exports"
+            if exports.exists():
+                for file in sorted(exports.rglob("*")):
+                    if not file.is_file():
+                        continue
+                    if file.suffix == ".latticebrain":
+                        continue
+                    if file.suffix not in PORTABLE_EXPORT_SUFFIXES:
+                        continue
+                    yield file, f"workspace_exports/{file.relative_to(exports).as_posix()}"
+
+    def _build_manifest(self, entries: List[Dict[str, Any]]) -> Dict[str, Any]:
+        metadata = _safe_json(self.paths.metadata or {})
+        return {
+            "format": "latticebrain.payload",
+            "format_version": ARCHIVE_VERSION,
+            "created_at": _now(),
+            "sections": {
+                "graph": any(item["path"] == "knowledge_graph.sqlite" for item in entries),
+                "blobs": any(item["path"].startswith("blobs/") for item in entries),
+                "workspace_state": any(item["path"].startswith("data/") for item in entries),
+                "signed_bundles": any(item["path"].startswith("workspace_exports/") for item in entries),
+            },
+            "metadata": metadata,
+            "storage": metadata.get("storage") or {},
+            "device_identity": metadata.get("device_identity") or {},
+            "provenance": metadata.get("provenance") or {},
+            "entries": entries,
+        }
+
+    def _payload_zip_bytes(self) -> tuple[bytes, Dict[str, Any]]:
+        entries: List[Dict[str, Any]] = []
+        with tempfile.TemporaryDirectory() as tmp_s:
+            payload = Path(tmp_s) / "payload.zip"
+            with zipfile.ZipFile(payload, "w", zipfile.ZIP_DEFLATED) as zf:
+                for src, arcname in self._iter_payload_files():
+                    _assert_safe_member(arcname)
+                    zf.write(src, arcname)
+                    entries.append({
+                        "path": arcname,
+                        "bytes": src.stat().st_size,
+                        "sha256": _sha256_file(src),
+                    })
+                manifest = self._build_manifest(entries)
+                manifest_bytes = json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True).encode("utf-8")
+                zf.writestr("manifest.json", manifest_bytes)
+            return payload.read_bytes(), manifest
+
+    def create(self, destination: Path, *, passphrase: str) -> Dict[str, object]:
+        dest = Path(destination)
+        if dest.suffix != ".latticebrain":
+            dest = dest.with_suffix(".latticebrain")
+        if not self.paths.db_path.exists():
+            raise FileNotFoundError(f"Brain database not found: {self.paths.db_path}")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        payload_bytes, manifest = self._payload_zip_bytes()
+        salt = os.urandom(16)
+        nonce = os.urandom(12)
+        key = _derive_key(passphrase, salt)
+        ciphertext = AESGCM(key).encrypt(nonce, payload_bytes, None)
+        envelope = {
+            "format": ARCHIVE_FORMAT,
+            "format_version": ARCHIVE_VERSION,
+            "created_at": _now(),
+            "kdf": {
+                "name": "PBKDF2HMAC-SHA256",
+                "iterations": KDF_ITERATIONS,
+                "salt": base64.b64encode(salt).decode("ascii"),
+            },
+            "cipher": {
+                "name": "AES-256-GCM",
+                "nonce": base64.b64encode(nonce).decode("ascii"),
+            },
+            "payload_sha256": _sha256_bytes(payload_bytes),
+            "manifest_summary": {
+                "format_version": manifest["format_version"],
+                "created_at": manifest["created_at"],
+                "sections": manifest["sections"],
+                "storage": manifest.get("storage") or {},
+                "device_identity": manifest.get("device_identity") or {},
+            },
+            "payload": base64.b64encode(ciphertext).decode("ascii"),
+        }
+        dest.write_text(json.dumps(envelope, indent=2), encoding="utf-8")
+        return {
+            "path": str(dest),
+            "bytes": dest.stat().st_size,
+            "encrypted": True,
+            "format_version": ARCHIVE_VERSION,
+            "manifest": {
+                "sections": manifest["sections"],
+                "storage": manifest.get("storage") or {},
+                "entries": len(manifest["entries"]),
+            },
+        }
+
+    def _load_envelope(self, source: Path) -> Dict[str, Any]:
+        src = Path(source)
+        if not src.exists():
+            raise FileNotFoundError(f"Brain archive not found: {src}")
+        try:
+            envelope = json.loads(src.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ValueError("Archive envelope is not valid JSON.") from exc
+        if envelope.get("format") != ARCHIVE_FORMAT:
+            raise ValueError("Not a .latticebrain encrypted archive.")
+        version = int(envelope.get("format_version") or 0)
+        if version < 1:
+            raise ValueError("Archive format version is missing or invalid.")
+        if version > ARCHIVE_VERSION:
+            raise ValueError(
+                f"Archive format version {version} is newer than supported version {ARCHIVE_VERSION}."
+            )
+        return envelope
+
+    def inspect(self, source: Path, *, passphrase: Optional[str] = None) -> Dict[str, Any]:
+        envelope = self._load_envelope(source)
+        summary = {
+            "valid_envelope": True,
+            "encrypted": True,
+            "format": envelope.get("format"),
+            "format_version": envelope.get("format_version"),
+            "created_at": envelope.get("created_at"),
+            "cipher": (envelope.get("cipher") or {}).get("name"),
+            "kdf": {
+                "name": (envelope.get("kdf") or {}).get("name"),
+                "iterations": (envelope.get("kdf") or {}).get("iterations"),
+            },
+            "manifest_summary": envelope.get("manifest_summary") or {},
+        }
+        if passphrase:
+            verified = self.verify(source, passphrase=passphrase)
+            summary["verified"] = verified["ok"]
+            summary["manifest"] = verified.get("manifest")
+            summary["errors"] = verified.get("errors", [])
+        return summary
+
+    def _decrypt_payload(self, envelope: Dict[str, Any], passphrase: str) -> bytes:
+        try:
+            salt = base64.b64decode(envelope["kdf"]["salt"])
+            nonce = base64.b64decode(envelope["cipher"]["nonce"])
+            ciphertext = base64.b64decode(envelope["payload"])
+        except Exception as exc:
+            raise ValueError("Archive envelope is missing encryption metadata.") from exc
+        key = _derive_key(passphrase, salt)
+        try:
+            payload = AESGCM(key).decrypt(nonce, ciphertext, None)
+        except InvalidTag as exc:
+            raise ValueError("Archive decryption failed; passphrase or archive data is invalid.") from exc
+        expected = envelope.get("payload_sha256")
+        if expected and _sha256_bytes(payload) != expected:
+            raise ValueError("Archive payload integrity check failed (sha256 mismatch).")
+        return payload
+
+    def _read_payload(self, payload: bytes) -> tuple[Dict[str, Any], Dict[str, bytes]]:
+        try:
+            with zipfile.ZipFile(io.BytesIO(payload)) as zf:
+                bad_member = zf.testzip()
+                if bad_member:
+                    raise ValueError(f"Archive payload member is corrupt: {bad_member}")
+                names = zf.namelist()
+                for name in names:
+                    _assert_safe_member(name)
+                raw = {name: zf.read(name) for name in names if not name.endswith("/")}
+        except zipfile.BadZipFile as exc:
+            raise ValueError("Archive payload is not a valid ZIP file.") from exc
+        if "manifest.json" in raw:
+            manifest = json.loads(raw["manifest.json"].decode("utf-8"))
+        else:
+            manifest = {
+                "format": "latticebrain.payload",
+                "format_version": 1,
+                "created_at": None,
+                "sections": {
+                    "graph": "knowledge_graph.sqlite" in raw,
+                    "blobs": any(name.startswith("blobs/") for name in raw),
+                    "workspace_state": False,
+                    "signed_bundles": False,
+                },
+                "metadata": {},
+                "storage": {},
+                "device_identity": {},
+                "provenance": {},
+                "entries": [
+                    {"path": name, "bytes": len(data), "sha256": _sha256_bytes(data)}
+                    for name, data in raw.items()
+                    if name != "manifest.json"
+                ],
+            }
+        version = int(manifest.get("format_version") or 0)
+        if version < 1:
+            raise ValueError("Archive manifest format version is missing or invalid.")
+        if version > ARCHIVE_VERSION:
+            raise ValueError(
+                f"Archive manifest version {version} is newer than supported version {ARCHIVE_VERSION}."
+            )
+        return manifest, raw
+
+    def verify(self, source: Path, *, passphrase: str) -> Dict[str, Any]:
+        try:
+            envelope = self._load_envelope(source)
+            payload = self._decrypt_payload(envelope, passphrase)
+            manifest, raw = self._read_payload(payload)
+            if "knowledge_graph.sqlite" not in raw:
+                raise ValueError("Archive payload is missing knowledge_graph.sqlite.")
+            missing: List[str] = []
+            mismatched: List[str] = []
+            for entry in manifest.get("entries") or []:
+                name = str(entry.get("path") or "")
+                if not name or name == "manifest.json":
+                    continue
+                data = raw.get(name)
+                if data is None:
+                    missing.append(name)
+                    continue
+                if entry.get("sha256") and _sha256_bytes(data) != entry["sha256"]:
+                    mismatched.append(name)
+            if missing or mismatched:
+                raise ValueError(
+                    "Archive manifest integrity check failed "
+                    f"(missing={missing}, mismatched={mismatched})."
+                )
+            return {
+                "ok": True,
+                "encrypted": True,
+                "format_version": envelope.get("format_version"),
+                "manifest": manifest,
+                "entries": len([name for name in raw if name != "manifest.json"]),
+                "errors": [],
+            }
+        except (ValueError, FileNotFoundError) as exc:
+            return {"ok": False, "encrypted": True, "errors": [str(exc)]}
+
+    def restore(
+        self,
+        source: Path,
+        *,
+        passphrase: str,
+        target: BrainArchivePaths,
+        dry_run: bool = False,
+        confirm: bool = False,
+    ) -> Dict[str, object]:
+        if not dry_run and not confirm:
+            raise ValueError("Explicit confirmation is required before restoring a .latticebrain archive.")
+        envelope = self._load_envelope(source)
+        payload = self._decrypt_payload(envelope, passphrase)
+        manifest, raw = self._read_payload(payload)
+        verified = self.verify(source, passphrase=passphrase)
+        if not verified["ok"]:
+            raise ValueError("; ".join(verified.get("errors") or ["Archive verification failed."]))
+        planned = {
+            "database": str(target.db_path),
+            "blobs": str(target.blob_dir) if target.blob_dir else None,
+            "data_dir": str(target.data_dir) if target.data_dir else None,
+            "entries": len([name for name in raw if name != "manifest.json"]),
+            "sections": manifest.get("sections") or {},
+        }
+        if dry_run:
+            return {
+                "restored": False,
+                "dry_run": True,
+                "verified": True,
+                "planned": planned,
+                "manifest": manifest,
+            }
+        with tempfile.TemporaryDirectory() as tmp_s:
+            tmp = Path(tmp_s)
+            out = tmp / "out"
+            out.mkdir()
+            for name, data in raw.items():
+                _assert_safe_member(name)
+                dest = out / name
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_bytes(data)
+            db_src = out / "knowledge_graph.sqlite"
+            if not db_src.exists():
+                raise ValueError("Archive payload is missing knowledge_graph.sqlite.")
+            target.db_path.parent.mkdir(parents=True, exist_ok=True)
+            for sibling in (target.db_path, Path(str(target.db_path) + "-wal"), Path(str(target.db_path) + "-shm")):
+                if sibling.exists():
+                    sibling.unlink()
+            shutil.copyfile(db_src, target.db_path)
+            blobs_src = out / "blobs"
+            if target.blob_dir:
+                if target.blob_dir.exists():
+                    shutil.rmtree(target.blob_dir)
+                if blobs_src.exists():
+                    shutil.copytree(blobs_src, target.blob_dir)
+                else:
+                    target.blob_dir.mkdir(parents=True, exist_ok=True)
+            if target.data_dir:
+                data_src = out / "data"
+                exports_src = out / "workspace_exports"
+                target_data = Path(target.data_dir)
+                target_data.mkdir(parents=True, exist_ok=True)
+                if data_src.exists():
+                    for file in sorted(data_src.rglob("*")):
+                        if file.is_file():
+                            rel = file.relative_to(data_src)
+                            if rel.as_posix() not in PORTABLE_DATA_FILES:
+                                continue
+                            dest = target_data / rel
+                            dest.parent.mkdir(parents=True, exist_ok=True)
+                            shutil.copyfile(file, dest)
+                if exports_src.exists():
+                    exports_dest = target_data / "workspace_exports"
+                    exports_dest.mkdir(parents=True, exist_ok=True)
+                    for file in sorted(exports_src.rglob("*")):
+                        if file.is_file():
+                            rel = file.relative_to(exports_src)
+                            dest = exports_dest / rel
+                            dest.parent.mkdir(parents=True, exist_ok=True)
+                            shutil.copyfile(file, dest)
+        return {
+            "restored": True,
+            "dry_run": False,
+            "path": str(target.db_path),
+            "encrypted": True,
+            "verified": True,
+            "manifest": manifest,
+        }
+
+
+__all__ = ["BrainArchivePaths", "EncryptedBrainArchive"]

package/lattice_brain/context.py

@@ -0,0 +1,3 @@
+from latticeai.brain.context import AssembledContext, ContextAssembler, ContextSection, approx_tokens
+
+__all__ = ["AssembledContext", "ContextAssembler", "ContextSection", "approx_tokens"]