ltcai 10.9.0 → 11.0.1

package/lattice_brain/portability.py

@@ -16,6 +16,8 @@ any cloud service. Two complementary mechanisms, both fully local:
 
 from __future__ import annotations
 
+import base64
+import hashlib
 import json
 import logging
 import os
@@ -25,9 +27,17 @@ import tempfile
 import zipfile
 from contextlib import closing
 from pathlib import Path, PurePosixPath
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Iterable, List, Optional, Set
 
-from .archive import BrainArchivePaths, EncryptedBrainArchive
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .archive import (
+    KDF_ITERATIONS,
+    BrainArchivePaths,
+    EncryptedBrainArchive,
+    _derive_key,
+)
 from .quiet import quiet
 from .storage import (
     DockerPostgresWizard,
@@ -41,6 +51,53 @@ FORMAT = "latticeai.kg.export"
 FORMAT_VERSION = 1
 BACKUP_FORMAT = "latticeai.kg.backup"
 
+# ── selective subgraph share (v11.1.0 prototype, off by default) ─────────────
+#: Logical format of a *partial* bundle: a chosen slice of the graph plus its
+#: provenance, signed by this device. Deliberately distinct from ``FORMAT`` so
+#: the whole-graph importer can never be handed a subgraph by accident.
+SUBGRAPH_FORMAT = "latticeai.kg.subgraph"
+SUBGRAPH_FORMAT_VERSION = 1
+#: Encrypted on-disk envelope for the same bundle, reusing the ``.latticebrain``
+#: passphrase mechanism (PBKDF2-SHA256 + AES-256-GCM) from ``archive.py``.
+SUBGRAPH_ARCHIVE_FORMAT = "latticebrain.subgraph"
+#: Opt-in gate. Off unless the operator sets it: sharing knowledge with another
+#: Brain is a network act, and local-first means those are never on by default.
+BRAIN_NETWORK_ENV = "LATTICEAI_BRAIN_NETWORK"
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+#: A received bundle becomes review items, never a merge. The cap keeps one
+#: peer from flooding the inbox; what it dropped is reported, not hidden.
+SUBGRAPH_PROPOSAL_CAP = 200
+#: Review-queue vocabulary. ``kg_change_digest`` is the existing source for
+#: "the graph would change"; the kind distinguishes shared-subgraph items.
+SUBGRAPH_REVIEW_SOURCE = "kg_change_digest"
+SUBGRAPH_REVIEW_KIND = "shared_subgraph_node"
+#: Mirrors ``services.review_queue.OPEN_STATUSES``. Duplicated as a literal
+#: rather than imported because ``lattice_brain`` must not depend on the
+#: ``latticeai`` service layer; the review sink is injected, not imported.
+_OPEN_REVIEW_STATUSES = frozenset({"pending", "snoozed"})
+
+BRAIN_NETWORK_DISABLED_DETAIL = (
+    "Brain Network sharing is off. It is opt-in by design: set "
+    f"{BRAIN_NETWORK_ENV}=1 to enable selective subgraph export and receipt."
+)
+
+
+class BrainNetworkDisabled(PermissionError):
+    """Raised when a share surface is used while the opt-in flag is off."""
+
+    def __init__(self, detail: str = BRAIN_NETWORK_DISABLED_DETAIL) -> None:
+        super().__init__(detail)
+
+
+def brain_network_enabled() -> bool:
+    """True only when the operator explicitly opted in (default: off)."""
+    return os.getenv(BRAIN_NETWORK_ENV, "").strip().lower() in _TRUTHY
+
+
+def require_brain_network() -> None:
+    if not brain_network_enabled():
+        raise BrainNetworkDisabled()
+
 
 def _stamp() -> str:
     return utc_now_iso().replace(":", "").replace("-", "").replace(".", "")[:15]
@@ -163,6 +220,140 @@ def _replace_tree_with_backup(src: Optional[Path], dest: Path, backup_dir: Path)
         raise
 
 
+#: Sender-identifying fields stripped from a shared bundle by default. The
+#: knowledge travels; "which account, on which machine, at which path" does not.
+_REDACTED_FIELDS = frozenset({"owner", "user_email", "source_uri", "permissions"})
+#: The signed payload's key set. One tuple so export and verify can never
+#: disagree about what the digest covers.
+_PAYLOAD_KEYS = (
+    "nodes", "chunk_nodes", "edges", "chunks", "knowledge_sources", "provenance",
+)
+#: Node types a one-hop expansion never admits — they describe the sender
+#: (identity, local paths), not the knowledge being shared.
+_NEIGHBOR_EXCLUDED_TYPES = frozenset({"Person", "Source"})
+
+
+def _canonical_digest(payload: Dict[str, Any]) -> str:
+    """sha256 over the canonical JSON of a bundle payload.
+
+    Pinned in the signed header so the Ed25519 signature covers the contents,
+    not just the manifest describing them.
+    """
+    canonical = json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _node_source_type(node: Dict[str, Any]) -> str:
+    try:
+        metadata = json.loads(node.get("metadata_json") or "{}")
+    except (TypeError, ValueError):
+        return ""
+    if not isinstance(metadata, dict):
+        return ""
+    return str(metadata.get("source_type") or "").strip().lower()
+
+
+def _select_node_ids(nodes: List[Dict[str, Any]], selection: Dict[str, Any]) -> Set[str]:
+    wanted_ids = set(selection["node_ids"])
+    wanted_types = set(selection["node_types"])
+    wanted_sources = set(selection["source_types"])
+    keep: Set[str] = set()
+    for node in nodes:
+        node_id = str(node.get("id"))
+        if node_id in wanted_ids:
+            keep.add(node_id)
+            continue
+        if wanted_types and str(node.get("type") or "").strip().lower() in wanted_types:
+            keep.add(node_id)
+            continue
+        if wanted_sources and _node_source_type(node) in wanted_sources:
+            keep.add(node_id)
+    return keep
+
+
+def _expand_neighbors(
+    keep: Set[str], edges: List[Dict[str, Any]], known: Dict[str, str]
+) -> Set[str]:
+    """One hop out from the selection, in both directions, within the scope.
+
+    ``Person`` and ``Source`` neighbours are never pulled in implicitly: a
+    Person node's label *is* an email address and a Source node's summary *is*
+    a local file path, so "share this decision and what it touches" would
+    quietly ship the sender's identity and directory layout. Naming one of
+    those node ids explicitly still exports it — that is a decision, not a
+    side effect.
+    """
+    expanded = set(keep)
+
+    def _admit(candidate: str) -> None:
+        if candidate in known and known[candidate] not in _NEIGHBOR_EXCLUDED_TYPES:
+            expanded.add(candidate)
+
+    for edge in edges:
+        source = str(edge.get("from_node"))
+        target = str(edge.get("to_node"))
+        if source in keep:
+            _admit(target)
+        if target in keep:
+            _admit(source)
+    return expanded
+
+
+def _strip_fields(raw_json: Optional[str]) -> Optional[str]:
+    if not raw_json:
+        return raw_json
+    try:
+        parsed = json.loads(raw_json)
+    except (TypeError, ValueError):
+        return raw_json
+    if not isinstance(parsed, dict):
+        return raw_json
+    cleaned = {k: v for k, v in parsed.items() if k not in _REDACTED_FIELDS}
+    return json.dumps(cleaned, ensure_ascii=False, sort_keys=True)
+
+
+def _redact_node(node: Dict[str, Any]) -> Dict[str, Any]:
+    redacted = dict(node)
+    redacted["metadata_json"] = _strip_fields(node.get("metadata_json"))
+    redacted["raw_json"] = _strip_fields(node.get("raw_json"))
+    return redacted
+
+
+def _redact_provenance_row(row: Dict[str, Any]) -> Dict[str, Any]:
+    redacted = dict(row)
+    redacted["owner"] = None
+    redacted["source_uri"] = None
+    redacted["permissions_json"] = "{}"
+    redacted["metadata_json"] = _strip_fields(row.get("metadata_json"))
+    return redacted
+
+
+def _scope_node(node: Dict[str, Any], workspace_id: str) -> Dict[str, Any]:
+    """Stamp the accepting workspace onto an incoming node.
+
+    Received knowledge belongs to the workspace that accepted it. Without this
+    the projection would file it as legacy-global — machine-shared — which is a
+    wider scope than the reviewer chose.
+    """
+    scoped = dict(node)
+    try:
+        metadata = json.loads(scoped.get("metadata_json") or "{}")
+    except (TypeError, ValueError):
+        metadata = {}
+    if not isinstance(metadata, dict):
+        metadata = {}
+    metadata["workspace_id"] = workspace_id
+    scoped["metadata_json"] = json.dumps(metadata, ensure_ascii=False, sort_keys=True)
+    return scoped
+
+
+def _shared_node_summary(node: Dict[str, Any], verdict: Dict[str, Any]) -> str:
+    body = str(node.get("summary") or "").strip()
+    origin = verdict.get("origin") or "unknown device"
+    prefix = f"[{origin}] "
+    return (prefix + body)[:500] if body else prefix.strip()
+
+
 class KGPortabilityService:
     def __init__(self, *, knowledge_graph: Any, data_dir, enable_graph: bool = True, device_identity: Any = None) -> None:
         self._kg = knowledge_graph
@@ -260,6 +451,467 @@ class KGPortabilityService:
         artifact = json.loads(Path(path).read_text(encoding="utf-8"))
         return self.import_data(artifact, mode=mode, dry_run=dry_run)
 
+    # ── selective subgraph share (opt-in prototype, off by default) ──────────
+    def share_status(self) -> Dict[str, Any]:
+        """Honest read of the share surface. Safe to call while it is off.
+
+        A status route that refuses while disabled cannot tell a UI *why* the
+        feature is missing, so this one always answers — with ``enabled:
+        false`` and the flag that turns it on.
+        """
+        enabled = brain_network_enabled()
+        return {
+            "enabled": enabled,
+            "flag": BRAIN_NETWORK_ENV,
+            "format": SUBGRAPH_FORMAT,
+            "format_version": SUBGRAPH_FORMAT_VERSION,
+            "graph_available": self.available(),
+            "signing": self._identity is not None,
+            "device": self._share_device(),
+            "proposal_cap": SUBGRAPH_PROPOSAL_CAP,
+            # Stated rather than implied: the bundle is signed by this device
+            # and encrypted with a shared passphrase. Encrypting *to a
+            # recipient's public key* is not implemented in this release.
+            "encryption": "passphrase",
+            "recipient_public_key_encryption": False,
+            "detail": None if enabled else BRAIN_NETWORK_DISABLED_DETAIL,
+        }
+
+    def _share_device(self) -> Dict[str, Any]:
+        """Signer identity for a bundle — key material only, no storage hints."""
+        if self._identity is None:
+            return {}
+        described = self._identity.describe()
+        return {
+            "fingerprint": described.get("fingerprint"),
+            "public_key": described.get("public_key"),
+            "algorithm": described.get("algorithm"),
+        }
+
+    def export_subgraph(
+        self,
+        *,
+        node_ids: Optional[Iterable[str]] = None,
+        node_types: Optional[Iterable[str]] = None,
+        source_types: Optional[Iterable[str]] = None,
+        workspace_id: Optional[str] = None,
+        include_legacy_global: bool = False,
+        include_neighbors: bool = False,
+        redact_provenance: bool = True,
+    ) -> Dict[str, Any]:
+        """A chosen slice of the graph, with provenance, signed by this device.
+
+        At least one selector is required. "Share everything" already exists as
+        :meth:`export`; a *selective* door that silently defaults to the whole
+        Brain is how an accident becomes a leak.
+
+        ``include_neighbors`` widens the selection by one hop (both directions)
+        so "share this decision" can carry the decision's immediate relations.
+        ``redact_provenance`` (default on) strips the sender's local identity —
+        owner, source URI, permissions — from both node metadata and the
+        provenance rows, and records that it did so in the header.
+
+        Knowledge-source rows (connected folder registrations, with their local
+        paths) are never included; they describe the sender's machine, not the
+        knowledge.
+        """
+        require_brain_network()
+        self._require()
+        if self._identity is None:
+            raise RuntimeError(
+                "A device identity is required to share a subgraph; "
+                "an unsigned bundle cannot be attributed and would be refused."
+            )
+        wanted_ids = sorted({str(v) for v in (node_ids or []) if str(v).strip()})
+        wanted_types = sorted({str(v).strip().lower() for v in (node_types or []) if str(v).strip()})
+        wanted_sources = sorted({str(v).strip().lower() for v in (source_types or []) if str(v).strip()})
+        selection: Dict[str, Any] = {
+            "node_ids": wanted_ids,
+            "node_types": wanted_types,
+            "source_types": wanted_sources,
+            "include_neighbors": bool(include_neighbors),
+            "workspace_id": workspace_id,
+        }
+        if not (wanted_ids or wanted_types or wanted_sources):
+            raise ValueError(
+                "A subgraph share must name what to share "
+                "(node_ids, node_types, or source_types)."
+            )
+        data = self._kg.export_graph_data(
+            workspace_id=workspace_id, include_legacy_global=include_legacy_global,
+        )
+        all_nodes = data.get("nodes") or []
+        # Chunks are derived retrieval units, not shareable subjects: they are
+        # never selectable, but they travel with the node they belong to so the
+        # receiver can actually search the shared content rather than a summary.
+        nodes = [n for n in all_nodes if str(n.get("type")) != "Chunk"]
+        chunk_nodes_by_id = {
+            str(n.get("id")): n for n in all_nodes if str(n.get("type")) == "Chunk"
+        }
+        edges = list(data.get("edges") or [])
+        keep = _select_node_ids(nodes, selection)
+        present = {str(n.get("id")): str(n.get("type") or "") for n in nodes}
+        missing = [nid for nid in wanted_ids if nid not in present]
+        if include_neighbors:
+            keep = _expand_neighbors(keep, edges, present)
+        if not keep:
+            raise ValueError("The selection matched no nodes; nothing was exported.")
+        kept_nodes = [n for n in nodes if str(n.get("id")) in keep]
+        kept_chunks = [c for c in data.get("chunks") or [] if str(c.get("source_node")) in keep]
+        kept_chunk_nodes = [
+            chunk_nodes_by_id[str(c.get("id"))]
+            for c in kept_chunks
+            if str(c.get("id")) in chunk_nodes_by_id
+        ]
+        carried = keep | {str(n.get("id")) for n in kept_chunk_nodes}
+        kept_edges = [
+            e for e in edges
+            if str(e.get("from_node")) in carried and str(e.get("to_node")) in carried
+        ]
+        kept_prov = [p for p in data.get("provenance") or [] if str(p.get("node_id")) in keep]
+        if redact_provenance:
+            kept_nodes = [_redact_node(n) for n in kept_nodes]
+            kept_chunk_nodes = [_redact_node(n) for n in kept_chunk_nodes]
+            kept_prov = [_redact_provenance_row(p) for p in kept_prov]
+        payload = {
+            "nodes": kept_nodes,
+            "chunk_nodes": kept_chunk_nodes,
+            "edges": kept_edges,
+            "chunks": kept_chunks,
+            "knowledge_sources": [],
+            "provenance": kept_prov,
+        }
+        counts = {key: len(value) for key, value in payload.items()}
+        header = {
+            "format": SUBGRAPH_FORMAT,
+            "format_version": SUBGRAPH_FORMAT_VERSION,
+            **self._kg.schema_versions(),
+            "exported_at": utc_now_iso(),
+            "workspace_id": workspace_id,
+            "selection": selection,
+            "counts": counts,
+            "unmatched_node_ids": missing,
+            "redacted": sorted(_REDACTED_FIELDS) if redact_provenance else [],
+            "includes_knowledge_sources": False,
+            "device": self._share_device(),
+            # The signature covers the header; the header pins the payload.
+            "payload_sha256": _canonical_digest(payload),
+        }
+        return {
+            "header": header,
+            **payload,
+            "signature": self._identity.sign_manifest(header),
+        }
+
+    def export_subgraph_archive(
+        self,
+        dest_path=None,
+        *,
+        passphrase: str,
+        **selection: Any,
+    ) -> Dict[str, Any]:
+        """Write the signed subgraph as an encrypted ``.latticebrain`` file.
+
+        Same passphrase mechanism as the whole-Brain archive (PBKDF2-SHA256 →
+        AES-256-GCM), a different ``format`` so the two can never be confused.
+        The header and signature stay outside the ciphertext on purpose: a
+        recipient can see *who* sent a bundle, and how big it is, before typing
+        a passphrase into it.
+        """
+        artifact = self.export_subgraph(**selection)
+        self._exports_dir.mkdir(parents=True, exist_ok=True)
+        dest = Path(dest_path) if dest_path else self._exports_dir / f"subgraph-{_stamp()}.latticebrain"
+        if dest.suffix != ".latticebrain":
+            dest = dest.with_suffix(".latticebrain")
+        body = {key: value for key, value in artifact.items() if key not in {"header", "signature"}}
+        plaintext = json.dumps(body, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        salt = os.urandom(16)
+        nonce = os.urandom(12)
+        ciphertext = AESGCM(_derive_key(passphrase, salt)).encrypt(nonce, plaintext, None)
+        envelope = {
+            "format": SUBGRAPH_ARCHIVE_FORMAT,
+            "format_version": SUBGRAPH_FORMAT_VERSION,
+            "created_at": utc_now_iso(),
+            "kdf": {
+                "name": "PBKDF2HMAC-SHA256",
+                "iterations": KDF_ITERATIONS,
+                "salt": base64.b64encode(salt).decode("ascii"),
+            },
+            "cipher": {"name": "AES-256-GCM", "nonce": base64.b64encode(nonce).decode("ascii")},
+            "header": artifact["header"],
+            "signature": artifact["signature"],
+            "payload": base64.b64encode(ciphertext).decode("ascii"),
+        }
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(json.dumps(envelope, ensure_ascii=False, indent=2), encoding="utf-8")
+        return {
+            "path": str(dest),
+            "bytes": dest.stat().st_size,
+            "encrypted": True,
+            "format": SUBGRAPH_ARCHIVE_FORMAT,
+            "header": artifact["header"],
+            "counts": artifact["header"]["counts"],
+        }
+
+    def read_subgraph_archive(self, path, *, passphrase: str) -> Dict[str, Any]:
+        """Decrypt an encrypted subgraph bundle back into a signed artifact."""
+        require_brain_network()
+        source = Path(path)
+        if not source.exists():
+            raise FileNotFoundError(f"Subgraph bundle not found: {source}")
+        try:
+            envelope = json.loads(source.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ValueError("Subgraph bundle is not valid JSON.") from exc
+        if envelope.get("format") != SUBGRAPH_ARCHIVE_FORMAT:
+            raise ValueError("Not a .latticebrain subgraph bundle.")
+        try:
+            salt = base64.b64decode(envelope["kdf"]["salt"])
+            nonce = base64.b64decode(envelope["cipher"]["nonce"])
+            ciphertext = base64.b64decode(envelope["payload"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValueError("Subgraph bundle is missing encryption metadata.") from exc
+        try:
+            plaintext = AESGCM(_derive_key(passphrase, salt)).decrypt(nonce, ciphertext, None)
+        except InvalidTag as exc:
+            raise ValueError(
+                "Subgraph decryption failed; the passphrase or the bundle is invalid."
+            ) from exc
+        body = json.loads(plaintext.decode("utf-8"))
+        return {
+            "header": envelope.get("header") or {},
+            **body,
+            "signature": envelope.get("signature") or {},
+        }
+
+    def verify_subgraph(self, artifact: Dict[str, Any]) -> Dict[str, Any]:
+        """Signature + payload-digest verdict for a received bundle.
+
+        Fail-closed and specific: the caller learns *which* check failed, and
+        an unsigned bundle is a failure here (unlike a local file import, where
+        pre-v4 unsigned artifacts stay importable).
+        """
+        errors: List[str] = []
+        header = artifact.get("header") if isinstance(artifact, dict) else None
+        header = header if isinstance(header, dict) else {}
+        signature = artifact.get("signature") if isinstance(artifact, dict) else None
+        signature = signature if isinstance(signature, dict) else {}
+        if header.get("format") != SUBGRAPH_FORMAT:
+            errors.append("not a Lattice subgraph bundle")
+        incoming_version = int(header.get("format_version") or 0)
+        if incoming_version > SUBGRAPH_FORMAT_VERSION:
+            errors.append(
+                f"bundle format version {incoming_version} is newer than this build "
+                f"({SUBGRAPH_FORMAT_VERSION})"
+            )
+        if not signature.get("signature"):
+            errors.append("bundle is unsigned")
+        else:
+            from .graph.identity import verify_manifest
+
+            if not verify_manifest(header, signature):
+                errors.append("signature does not match the bundle header")
+        expected = header.get("payload_sha256")
+        if expected:
+            payload = {key: artifact.get(key) or [] for key in _PAYLOAD_KEYS}
+            if _canonical_digest(payload) != expected:
+                errors.append("bundle contents do not match the signed digest")
+        else:
+            errors.append("bundle header does not pin its payload digest")
+        fingerprint = str(signature.get("fingerprint") or "") or None
+        return {
+            "ok": not errors,
+            "errors": errors,
+            "fingerprint": fingerprint,
+            "origin": f"device:{fingerprint}" if fingerprint and not errors else None,
+            "exported_at": header.get("exported_at"),
+            "counts": header.get("counts") or {},
+        }
+
+    def import_subgraph_proposals(
+        self,
+        artifact: Dict[str, Any],
+        *,
+        review_sink: Any,
+        workspace_id: Optional[str] = None,
+        user_email: Optional[str] = None,
+        dry_run: bool = False,
+        cap: int = SUBGRAPH_PROPOSAL_CAP,
+    ) -> Dict[str, Any]:
+        """Receive a subgraph as *proposals*, never as a merge.
+
+        Every node becomes one review item carrying its edges, chunks, and
+        provenance, stamped with the sending device's fingerprint and the
+        signature verdict. Nothing reaches the graph until a human accepts an
+        item through :meth:`accept_subgraph_proposal`.
+        """
+        require_brain_network()
+        self._require()
+        verdict = self.verify_subgraph(artifact)
+        if not verdict["ok"]:
+            raise ValueError(
+                "Refusing the bundle: " + "; ".join(verdict["errors"])
+            )
+        header = dict(artifact.get("header") or {})
+        nodes = [n for n in artifact.get("nodes") or [] if n.get("id")]
+        edges = list(artifact.get("edges") or [])
+        chunks = list(artifact.get("chunks") or [])
+        chunk_nodes = {str(n.get("id")): n for n in artifact.get("chunk_nodes") or []}
+        provenance = list(artifact.get("provenance") or [])
+        cap = max(1, int(cap))
+        selected = nodes[:cap]
+        summary: Dict[str, Any] = {
+            "status": "dry_run" if dry_run else "proposed",
+            "origin": verdict["origin"],
+            "fingerprint": verdict["fingerprint"],
+            "signed": True,
+            "signature_verified": True,
+            "nodes": len(nodes),
+            "edges": len(edges),
+            "chunks": len(chunks),
+            "proposed": len(selected),
+            "skipped": len(nodes) - len(selected),
+            "capped": len(nodes) > len(selected),
+            "exported_at": header.get("exported_at"),
+            "items": [],
+        }
+        if dry_run:
+            return summary
+        for node in selected:
+            node_id = str(node.get("id"))
+            node_chunks = [c for c in chunks if str(c.get("source_node")) == node_id]
+            carried = {node_id} | {str(c.get("id")) for c in node_chunks}
+            item = review_sink.create(
+                title=str(node.get("title") or node_id)[:200],
+                summary=_shared_node_summary(node, verdict),
+                source=SUBGRAPH_REVIEW_SOURCE,
+                kind=SUBGRAPH_REVIEW_KIND,
+                payload={
+                    "kind": SUBGRAPH_REVIEW_KIND,
+                    "node": node,
+                    "chunk_nodes": [
+                        chunk_nodes[str(c.get("id"))]
+                        for c in node_chunks
+                        if str(c.get("id")) in chunk_nodes
+                    ],
+                    "edges": [
+                        e for e in edges
+                        if str(e.get("from_node")) in carried or str(e.get("to_node")) in carried
+                    ],
+                    "chunks": node_chunks,
+                    "provenance": [p for p in provenance if str(p.get("node_id")) == node_id],
+                    "graph_schema_version": header.get("graph_schema_version"),
+                },
+                provenance={
+                    "origin": verdict["origin"],
+                    "fingerprint": verdict["fingerprint"],
+                    "public_key": (artifact.get("signature") or {}).get("public_key"),
+                    "signature_verified": True,
+                    "exported_at": header.get("exported_at"),
+                    "source_detail": "brain_network_subgraph",
+                    "redacted": header.get("redacted") or [],
+                },
+                user_email=user_email,
+                workspace_id=workspace_id,
+            )
+            summary["items"].append(item.get("id"))
+        try:
+            self._kg.record_provenance(
+                node_id="subgraph-proposal:" + str(header.get("exported_at") or utc_now_iso()),
+                source_type="subgraph_share",
+                pipeline="kg-portability",
+                owner=user_email,
+                workspace_id=workspace_id,
+                metadata={
+                    "origin": verdict["origin"],
+                    "proposed": len(selected),
+                    "counts": header.get("counts"),
+                },
+            )
+        except Exception:  # noqa: BLE001 — the proposals already landed
+            quiet()
+        return summary
+
+    def accept_subgraph_proposal(
+        self,
+        item_id: str,
+        *,
+        review_sink: Any,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Merge one accepted proposal into this Brain and approve the item.
+
+        Only the node the reviewer looked at is written. An edge whose other
+        endpoint is not (yet) in this Brain is *deferred* and reported, because
+        writing a dangling relation would invent a connection the receiver
+        cannot see.
+        """
+        require_brain_network()
+        self._require()
+        item = review_sink.get(item_id, workspace_id=workspace_id)
+        payload = dict((item or {}).get("payload") or {})
+        if payload.get("kind") != SUBGRAPH_REVIEW_KIND:
+            raise ValueError("That review item is not a shared-subgraph proposal.")
+        node = dict(payload.get("node") or {})
+        node_id = str(node.get("id") or "")
+        if not node_id:
+            raise ValueError("The proposal carries no node id.")
+        status = str((item or {}).get("status") or "pending")
+        if status not in _OPEN_REVIEW_STATUSES:
+            # Import first, approve second would re-write an already-decided
+            # item; refuse before touching the graph instead.
+            raise ValueError(f"That proposal is already {status}; nothing was imported.")
+        chunk_nodes = [dict(n) for n in payload.get("chunk_nodes") or []]
+        if workspace_id:
+            node = _scope_node(node, workspace_id)
+            chunk_nodes = [_scope_node(n, workspace_id) for n in chunk_nodes]
+        # The chunk rows land in the same write, so their nodes count as
+        # present even though this Brain has not seen them yet.
+        writing = {node_id} | {str(n.get("id")) for n in chunk_nodes}
+        kept: List[Dict[str, Any]] = []
+        deferred: List[Dict[str, Any]] = []
+        for edge in payload.get("edges") or []:
+            endpoints = {str(edge.get("from_node")), str(edge.get("to_node"))}
+            outside = endpoints - writing
+            if all(self._node_present(other) for other in outside):
+                kept.append(edge)
+            else:
+                deferred.append({
+                    "from": edge.get("from_node"),
+                    "to": edge.get("to_node"),
+                    "type": edge.get("type"),
+                    "reason": "the other node is not in this Brain yet",
+                })
+        result = self._kg.import_graph_data(
+            {
+                "header": {"graph_schema_version": payload.get("graph_schema_version")},
+                "nodes": [node, *chunk_nodes],
+                "edges": kept,
+                "chunks": list(payload.get("chunks") or []),
+                "knowledge_sources": [],
+                "provenance": list(payload.get("provenance") or []),
+            },
+            mode="merge",
+        )
+        approved = review_sink.approve(item_id, workspace_id=workspace_id)
+        return {
+            "status": "accepted",
+            "item_id": item_id,
+            "node_id": node_id,
+            "imported": result,
+            "edges_written": len(kept),
+            "edges_deferred": deferred,
+            "origin": (item.get("provenance") or {}).get("origin"),
+            "review_status": approved.get("status"),
+        }
+
+    def _node_present(self, node_id: str) -> bool:
+        try:
+            self._kg.get_node(node_id)
+        except Exception:  # noqa: BLE001 — "not found" is the answer, not a failure
+            return False
+        return True
+
     # ── binary backup / restore ──────────────────────────────────────────────
     def backup(self, dest_path=None) -> Dict[str, Any]:
         self._require()