ltcai 11.5.2 → 11.6.0

package/lattice_brain/memory.py

@@ -1,75 +0,0 @@
-"""Memory System — typed, durable memory records on the brain substrate.
-
-Decision and Experience records become first-class graph nodes through the
-unified ingestion pipeline (provenance + hooks), instead of markdown dumps
-with swallowed errors. Episodic memory is the conversation store; semantic
-memory is the workspace MEMORY_KINDS records — this module adds the typed
-record kinds the schema always had but never populated.
-
-Only REAL events become memories: simulation runs are rejected at this
-boundary (the run record's own mode field is checked — fabricated artifacts
-must never enter the brain as experience).
-"""
-
-from __future__ import annotations
-
-from typing import Any, Dict, Optional
-
-from .ingestion import IngestionItem
-
-
-class BrainMemory:
-    """Writes Decision / Experience records through the ingestion pipeline."""
-
-    def __init__(self, ingestion_pipeline: Any):
-        self._pipeline = ingestion_pipeline
-
-    def available(self) -> bool:
-        return self._pipeline is not None and self._pipeline.available()
-
-    def record_experience(
-        self,
-        title: str,
-        detail: str = "",
-        *,
-        run: Optional[Dict[str, Any]] = None,
-        user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Persist a completed run/action as an Experience node.
-
-        ``run`` is the persisted run record; simulated runs are refused —
-        a simulation is replay scaffolding, not something that happened.
-        """
-        if run is not None and run.get("mode", "simulation") == "simulation":
-            return {
-                "status": "rejected",
-                "detail": "simulation runs are not experiences and never enter the brain",
-            }
-        if not str(title or "").strip():
-            raise ValueError("an experience needs a title")
-        run_meta = {}
-        if run is not None:
-            run_meta = {
-                "run_id": run.get("id"),
-                "agent_id": run.get("agent_id"),
-                "run_status": run.get("status"),
-                "mode": run.get("mode"),
-                "retries": run.get("retries"),
-            }
-        result = self._pipeline.ingest(
-            IngestionItem(
-                source_type="experience",
-                title=title.strip(),
-                text=detail,
-                owner=user_email,
-                workspace_id=workspace_id,
-                metadata={**run_meta, **(metadata or {})},
-            ),
-            user_email=user_email,
-        )
-        return result.as_dict()
-
-
-__all__ = ["BrainMemory"]

package/lattice_brain/portability/__init__.py

@@ -1,90 +0,0 @@
-"""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). Vectors are not in the
-  artifact; the importer re-embeds with its own embedder and reports the
-  resulting index state under ``result["index"]`` (``degraded: true`` means the
-  content landed but recall is lexical-only until a rebuild succeeds). That is
-  what makes it 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.
-
-Split into cohesive submodules in v11.3.0 (no behaviour change): ``constants``
-(formats + gates), ``fsops`` (atomic swaps), ``bundles`` (subgraph shaping),
-``sharing`` and ``backups`` (the two halves of the service), ``service`` (the
-composed class). This module re-exports every name the single file exposed, so
-``lattice_brain.portability.X`` keeps working.
-"""
-
-from __future__ import annotations
-
-# The single file had no ``__all__``, so its public surface was "every module
-# global". The redundant-alias form reproduces exactly that surface and marks
-# each name as a deliberate re-export rather than a leftover import.
-#
-# Stubbing note: rebinding one of these *here* changes only this module's name.
-# The submodule that calls it holds its own reference, so a test standing in for
-# ``_stamp`` patches ``lattice_brain.portability.fsops``, for ``_sha256_file``
-# or ``SQLiteToPostgresMigrator`` ``…portability.backups``, and for
-# ``load_recipient_identity`` ``…portability.sharing``.
-from ..archive import KDF_ITERATIONS as KDF_ITERATIONS
-from ..archive import BrainArchivePaths as BrainArchivePaths
-from ..archive import EncryptedBrainArchive as EncryptedBrainArchive
-from ..archive import _derive_key as _derive_key
-from ..gates import FeatureGate as FeatureGate
-from ..quiet import quiet as quiet
-from ..sealed_box import SEALED_BOX_ALGORITHM as SEALED_BOX_ALGORITHM
-from ..sealed_box import public_key_fingerprint as public_key_fingerprint
-from ..sealed_box import seal as seal
-from ..storage import DockerPostgresWizard as DockerPostgresWizard
-from ..storage import PostgresEngine as PostgresEngine
-from ..storage import SQLiteToPostgresMigrator as SQLiteToPostgresMigrator
-from ..utils import utc_now_iso as utc_now_iso
-from .backups import KGPortabilityBackupMixin as KGPortabilityBackupMixin
-from .backups import _sha256_file as _sha256_file
-from .bundles import _canonical_digest as _canonical_digest
-from .bundles import _expand_neighbors as _expand_neighbors
-from .bundles import _node_source_type as _node_source_type
-from .bundles import _redact_node as _redact_node
-from .bundles import _redact_provenance_row as _redact_provenance_row
-from .bundles import _scope_node as _scope_node
-from .bundles import _select_node_ids as _select_node_ids
-from .bundles import _shared_node_summary as _shared_node_summary
-from .bundles import _strip_fields as _strip_fields
-from .constants import _NEIGHBOR_EXCLUDED_TYPES as _NEIGHBOR_EXCLUDED_TYPES
-from .constants import _OPEN_REVIEW_STATUSES as _OPEN_REVIEW_STATUSES
-from .constants import _PAYLOAD_KEYS as _PAYLOAD_KEYS
-from .constants import _REDACTED_FIELDS as _REDACTED_FIELDS
-from .constants import _TRUTHY as _TRUTHY
-from .constants import BACKUP_FORMAT as BACKUP_FORMAT
-from .constants import BRAIN_NETWORK_DISABLED_DETAIL as BRAIN_NETWORK_DISABLED_DETAIL
-from .constants import BRAIN_NETWORK_ENV as BRAIN_NETWORK_ENV
-from .constants import BRAIN_NETWORK_GATE as BRAIN_NETWORK_GATE
-from .constants import ENCRYPTION_MODES as ENCRYPTION_MODES
-from .constants import FORMAT as FORMAT
-from .constants import FORMAT_VERSION as FORMAT_VERSION
-from .constants import SUBGRAPH_ARCHIVE_FORMAT as SUBGRAPH_ARCHIVE_FORMAT
-from .constants import SUBGRAPH_FORMAT as SUBGRAPH_FORMAT
-from .constants import SUBGRAPH_FORMAT_VERSION as SUBGRAPH_FORMAT_VERSION
-from .constants import SUBGRAPH_PROPOSAL_CAP as SUBGRAPH_PROPOSAL_CAP
-from .constants import SUBGRAPH_REVIEW_KIND as SUBGRAPH_REVIEW_KIND
-from .constants import SUBGRAPH_REVIEW_SOURCE as SUBGRAPH_REVIEW_SOURCE
-from .constants import BrainNetworkDisabled as BrainNetworkDisabled
-from .constants import _stamp as _stamp
-from .constants import brain_network_enabled as brain_network_enabled
-from .constants import require_brain_network as require_brain_network
-from .fsops import _checkpoint_sqlite as _checkpoint_sqlite
-from .fsops import _pre_restore_backup_dir as _pre_restore_backup_dir
-from .fsops import _replace_sqlite_atomically as _replace_sqlite_atomically
-from .fsops import _replace_tree_with_backup as _replace_tree_with_backup
-from .fsops import _restore_sibling as _restore_sibling
-from .fsops import _rollback_sqlite_from_backup as _rollback_sqlite_from_backup
-from .fsops import _safe_zip_names as _safe_zip_names
-from .fsops import _sqlite_siblings as _sqlite_siblings
-from .service import KGPortabilityService as KGPortabilityService
-from .sharing import KGPortabilitySharingMixin as KGPortabilitySharingMixin
-from .sharing import load_recipient_identity as load_recipient_identity

package/lattice_brain/portability/_contract.py

@@ -1,42 +0,0 @@
-"""The seam the two portability mixins share.
-
-``KGPortabilityService`` is assembled from :class:`KGPortabilitySharingMixin`
-and :class:`KGPortabilityBackupMixin`. Both read constructor state they do not
-own and both call the availability guard the service defines. That contract
-existed as an unwritten convention; this module writes it down.
-
-Typing-only, exactly like :mod:`lattice_brain.graph._kg_contract`: at runtime
-the mixins alias it to ``object``, so the MRO and every method resolution stay
-byte-for-byte what the single-file class had. Adding a cross-mixin call without
-declaring it here is a type error.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-
-class PortabilityCore:
-    """What either portability mixin may assume about ``self``.
-
-    Never instantiated and never inherited at runtime — see the module
-    docstring. Members are declared, not implemented: the implementation lives
-    in ``service.py`` (state and availability) or in whichever mixin owns it.
-    """
-
-    # ── State owned by KGPortabilityService.__init__ ─────────────────────────
-    _kg: Any
-    _data_dir: Path
-    _enable: bool
-    _exports_dir: Path
-    _identity: Any
-    _recipient: Any
-    _recipient_loaded: bool
-
-    # ── service.py: the availability guard every write door calls ────────────
-    def available(self) -> bool:
-        raise NotImplementedError
-
-    def _require(self) -> None:
-        raise NotImplementedError

package/lattice_brain/portability/backups.py

@@ -1,338 +0,0 @@
-"""Binary backup/restore, the encrypted archive, and the storage status reads.
-
-The half of :class:`~lattice_brain.portability.KGPortabilityService` that moves
-*files*: a ZIP snapshot of the database plus blobs, the passphrase-encrypted
-``.latticebrain`` archive, and the status/migration surfaces that sit on top of
-them (a Postgres migration refuses to start without a verified backup).
-
-Integrity hashing (``_sha256_file``) and the Postgres migrator are looked up as
-this module's globals, so a test standing in for either patches *this* module.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import tempfile
-import zipfile
-from pathlib import Path
-from typing import Any, Dict, Optional
-
-from ..archive import BrainArchivePaths, EncryptedBrainArchive
-from ..storage import (
-    DockerPostgresWizard,
-    PostgresEngine,
-    SQLiteToPostgresMigrator,
-)
-from ..utils import sha256_file as _sha256_file
-from ..utils import utc_now_iso
-from ._contract import PortabilityCore as _Core
-from .constants import BACKUP_FORMAT, FORMAT_VERSION, _stamp
-from .fsops import (
-    _pre_restore_backup_dir,
-    _replace_sqlite_atomically,
-    _replace_tree_with_backup,
-    _rollback_sqlite_from_backup,
-    _safe_zip_names,
-)
-
-
-class KGPortabilityBackupMixin(_Core):
-    """Backup / restore / storage status. Mixed into ``KGPortabilityService``."""
-
-    # ── 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": utc_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,
-        dry_run: bool = False,
-        confirm: bool = False,
-    ) -> Dict[str, Any]:
-        self._require()
-        archive = Path(archive_path)
-        if not archive.exists():
-            raise FileNotFoundError(f"Backup archive not found: {archive}")
-        if not dry_run and not confirm:
-            raise ValueError("Explicit confirmation is required before restoring a Knowledge Graph backup.")
-        with zipfile.ZipFile(archive) as zf:
-            names = zf.namelist()
-            _safe_zip_names(names)
-            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).")
-                if dry_run:
-                    return {
-                        "restored": False,
-                        "dry_run": True,
-                        "verified": True,
-                        "manifest": manifest,
-                        "planned": {
-                            "database": str(self._kg.db_path),
-                            "blobs": str(self._kg.blob_dir),
-                            "archive": str(archive),
-                        },
-                    }
-                db_dest = Path(self._kg.db_path)
-                blob_dest = Path(self._kg.blob_dir)
-                backup_dir = _pre_restore_backup_dir(db_dest)
-                try:
-                    _replace_sqlite_atomically(db_src, db_dest, backup_dir)
-                    blob_src = tmp / "blobs"
-                    _replace_tree_with_backup(blob_src if blob_src.exists() else None, blob_dest, backup_dir)
-                except Exception:
-                    # The rollback is best-effort recovery; an I/O slip inside
-                    # it must never mask the restore failure being reported.
-                    try:
-                        _rollback_sqlite_from_backup(db_dest, backup_dir)
-                    except OSError as rollback_exc:
-                        logging.warning(
-                            "pre-restore rollback incomplete (backup kept at %s): %s",
-                            backup_dir, rollback_exc,
-                        )
-                    raise
-        stats = self._kg.stats()
-        return {
-            "restored": True,
-            "manifest": manifest,
-            "pre_restore_backup": str(backup_dir),
-            "nodes": sum(stats.get("nodes", {}).values()),
-        }
-
-    def verify_backup(self, archive_path) -> Dict[str, Any]:
-        archive = Path(archive_path)
-        if not archive.exists():
-            return {"ok": False, "path": str(archive), "errors": [f"Backup archive not found: {archive}"]}
-        try:
-            with zipfile.ZipFile(archive) as zf:
-                names = zf.namelist()
-                _safe_zip_names(names)
-                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.extract("knowledge_graph.sqlite", tmp)
-                    db_src = tmp / "knowledge_graph.sqlite"
-                    if manifest.get("db_sha256") and _sha256_file(db_src) != manifest["db_sha256"]:
-                        raise ValueError("Backup integrity check failed (db sha256 mismatch).")
-            return {"ok": True, "path": str(archive), "manifest": manifest, "errors": []}
-        except (ValueError, zipfile.BadZipFile, OSError, json.JSONDecodeError) as exc:
-            return {"ok": False, "path": str(archive), "errors": [str(exc)]}
-
-    # ── encrypted .latticebrain archive ───────────────────────────────────
-    def encrypted_archive(self, dest_path=None, *, passphrase: str) -> 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"brain-{_stamp()}.latticebrain"
-        metadata = {
-            "storage": self.storage_status().get("active", {}),
-            "snapshot": self.snapshot_metadata(),
-            "device_identity": self._identity.describe() if self._identity is not None else {},
-            "provenance": {"exported_at": utc_now_iso(), "source": "kg-portability"},
-        }
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-                metadata=metadata,
-            )
-        )
-        return archive.create(dest, passphrase=passphrase)
-
-    def inspect_encrypted_archive(self, archive_path, *, passphrase: Optional[str] = None) -> Dict[str, Any]:
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            )
-        )
-        return archive.inspect(Path(archive_path), passphrase=passphrase)
-
-    def verify_encrypted_archive(self, archive_path, *, passphrase: str) -> Dict[str, Any]:
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            )
-        )
-        return archive.verify(Path(archive_path), passphrase=passphrase)
-
-    def restore_encrypted_archive(
-        self,
-        archive_path,
-        *,
-        passphrase: str,
-        dry_run: bool = False,
-        confirm: bool = False,
-    ) -> Dict[str, Any]:
-        self._require()
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            )
-        )
-        return archive.restore(
-            Path(archive_path),
-            passphrase=passphrase,
-            target=BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            ),
-            dry_run=dry_run,
-            confirm=confirm,
-        )
-
-    def import_encrypted_archive(
-        self,
-        archive_path,
-        *,
-        passphrase: str,
-        dry_run: bool = False,
-        confirm: bool = False,
-    ) -> Dict[str, Any]:
-        result = self.restore_encrypted_archive(
-            archive_path,
-            passphrase=passphrase,
-            dry_run=dry_run,
-            confirm=confirm,
-        )
-        result["operation"] = "import"
-        return result
-
-    # ── 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(),
-            "storage": (
-                self._kg.storage_engine.capabilities().as_dict()
-                if getattr(self._kg, "storage_engine", None) is not None
-                else {"engine": "sqlite", "available": True}
-            ),
-        }
-
-    def storage_status(self) -> Dict[str, Any]:
-        if not self.available():
-            return {"available": False}
-        return {
-            "available": True,
-            "active": (
-                self._kg.storage_engine.capabilities().as_dict()
-                if getattr(self._kg, "storage_engine", None) is not None
-                else {"engine": "sqlite", "available": True}
-            ),
-            "postgres": PostgresEngine("", schema="lattice_brain").capabilities().as_dict(),
-            "backup_health": self.backup_health(),
-        }
-
-    def backup_health(self) -> Dict[str, Any]:
-        self._exports_dir.mkdir(parents=True, exist_ok=True)
-        backups = sorted(
-            [
-                p for p in self._exports_dir.glob("*")
-                if p.is_file() and (p.suffix == ".zip" or p.suffix == ".latticebrain")
-            ],
-            key=lambda p: p.stat().st_mtime,
-            reverse=True,
-        )
-        latest = backups[0] if backups else None
-        return {
-            "available": True,
-            "directory": str(self._exports_dir),
-            "count": len(backups),
-            "latest": str(latest) if latest else None,
-            "latest_bytes": latest.stat().st_size if latest else 0,
-            "encrypted_archives": sum(1 for p in backups if p.suffix == ".latticebrain"),
-            "zip_backups": sum(1 for p in backups if p.suffix == ".zip"),
-        }
-
-    def postgres_docker_setup(
-        self,
-        *,
-        consent: bool,
-        dry_run: bool = False,
-        port: int = 5432,
-    ) -> Dict[str, Any]:
-        wizard = DockerPostgresWizard(self._data_dir / "postgres", port=port)
-        return wizard.start(consent=consent, dry_run=dry_run)
-
-    def migrate_sqlite_to_postgres(
-        self,
-        *,
-        dsn: str,
-        schema: str = "lattice_brain",
-        dry_run: bool = True,
-    ) -> Dict[str, Any]:
-        self._require()
-        if not dsn:
-            raise ValueError("Postgres DSN is required for SQLite to Postgres migration.")
-        migrator = SQLiteToPostgresMigrator(
-            Path(self._kg.db_path),
-            PostgresEngine(dsn, schema=schema),
-        )
-        if dry_run:
-            return migrator.migrate(dry_run=True)
-        backup = self.backup()
-        verification = self.verify_backup(backup["path"])
-        if not verification.get("ok"):
-            raise RuntimeError(
-                "Pre-migration backup verification failed; Postgres migration was not started: "
-                + "; ".join(verification.get("errors") or [])
-            )
-        result = migrator.migrate(dry_run=False)
-        result["pre_migration_backup"] = {
-            "path": backup["path"],
-            "verified": True,
-            "manifest": backup.get("manifest"),
-        }
-        return result
-
-    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)

package/lattice_brain/portability/bundles.py

@@ -1,136 +0,0 @@
-"""Pure shaping of a shared subgraph bundle: select, expand, redact, digest.
-
-None of these touch a store or a file. They decide *what* travels — which
-nodes the selection names, which neighbours a one-hop expansion may admit, and
-which sender-identifying fields are stripped on the way out — and they pin the
-result with the digest the signature covers.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from typing import Any, Dict, List, Optional, Set
-
-from .constants import _NEIGHBOR_EXCLUDED_TYPES, _REDACTED_FIELDS
-
-
-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()