memuron 0.1.1__py3-none-any.whl

memuron/sync/folder.py

@@ -0,0 +1,828 @@
+"""CLI-first one-way folder sync.
+
+V0 intentionally imports local folders into Memuron collections and documents without
+watching files, deleting remote graph nodes, or attempting a bidirectional mount.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import json
+import mimetypes
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+from artha_engine import ArthaEngine
+
+from memuron.documents.parser import MAX_DOCUMENT_UPLOAD_BYTES
+from memuron.memory.recipes import (
+    create_collection,
+    ensure_memory_projections,
+    ingest_document_source,
+    place_node_in_collection,
+)
+
+MANIFEST_VERSION = 1
+DEFAULT_MANIFEST_RELATIVE_PATH = ".memuron/sync-manifest.json"
+IGNORE_FILE_NAME = ".memuronignore"
+
+DEFAULT_EXCLUDES = [
+    ".git/",
+    ".hg/",
+    ".svn/",
+    ".memuron/",
+    "node_modules/",
+    "__pycache__/",
+    ".pytest_cache/",
+    ".mypy_cache/",
+    ".ruff_cache/",
+    ".next/",
+    ".nuxt/",
+    ".turbo/",
+    ".venv/",
+    "venv/",
+    "dist/",
+    "build/",
+    "coverage/",
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    IGNORE_FILE_NAME,
+]
+
+SUPPORTED_EXTENSIONS = {
+    ".csv",
+    ".docx",
+    ".gif",
+    ".htm",
+    ".html",
+    ".jpeg",
+    ".jpg",
+    ".json",
+    ".jsonl",
+    ".md",
+    ".markdown",
+    ".pdf",
+    ".png",
+    ".ppt",
+    ".pptx",
+    ".rtf",
+    ".text",
+    ".tsv",
+    ".txt",
+    ".webp",
+    ".xls",
+    ".xlsm",
+    ".xlsx",
+    ".xml",
+    ".yaml",
+    ".yml",
+}
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _rel(path: Path, root: Path) -> str:
+    value = path.relative_to(root).as_posix()
+    return value or "."
+
+
+def _normalize_root(path: str | Path) -> Path:
+    root = Path(path).expanduser().resolve()
+    if not root.exists():
+        raise ValueError(f"Folder sync path does not exist: {root}")
+    if not root.is_dir():
+        raise ValueError(f"Folder sync path must be a directory: {root}")
+    return root
+
+
+def manifest_path_for_root(root: str | Path) -> Path:
+    return _normalize_root(root) / DEFAULT_MANIFEST_RELATIVE_PATH
+
+
+def _load_ignore_file(root: Path) -> list[str]:
+    ignore_file = root / IGNORE_FILE_NAME
+    if not ignore_file.exists():
+        return []
+    patterns: list[str] = []
+    for raw in ignore_file.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        patterns.append(line)
+    return patterns
+
+
+def _match_pattern(pattern: str, rel_path: str, *, is_dir: bool) -> bool:
+    negated = pattern.startswith("!")
+    if negated:
+        pattern = pattern[1:]
+    pattern = pattern.strip()
+    if not pattern:
+        return False
+    directory_only = pattern.endswith("/")
+    pattern = pattern.rstrip("/")
+    if directory_only and not is_dir:
+        return False
+
+    rel_path = rel_path.strip("/")
+    basename = rel_path.rsplit("/", 1)[-1]
+    parts = rel_path.split("/") if rel_path else []
+    if "/" in pattern:
+        return fnmatch.fnmatch(rel_path, pattern) or fnmatch.fnmatch(rel_path, f"{pattern}/*")
+    return (
+        fnmatch.fnmatch(basename, pattern)
+        or any(fnmatch.fnmatch(part, pattern) for part in parts)
+        or fnmatch.fnmatch(rel_path, pattern)
+        or fnmatch.fnmatch(rel_path, f"{pattern}/*")
+    )
+
+
+def _matches_any(patterns: list[str], rel_path: str, *, is_dir: bool) -> bool:
+    ignored = False
+    for pattern in patterns:
+        if pattern.startswith("!"):
+            if ignored and _match_pattern(pattern, rel_path, is_dir=is_dir):
+                ignored = False
+            continue
+        if _match_pattern(pattern, rel_path, is_dir=is_dir):
+            ignored = True
+    return ignored
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _supported(path: Path) -> bool:
+    return path.suffix.lower() in SUPPORTED_EXTENSIONS
+
+
+@dataclass(frozen=True)
+class ScannedDirectory:
+    path: Path
+    relative_path: str
+
+
+@dataclass(frozen=True)
+class ScannedFile:
+    path: Path
+    relative_path: str
+    sha256: str
+    mtime_ns: int
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class SkippedPath:
+    path: Path
+    relative_path: str
+    reason: str
+    size_bytes: int | None = None
+
+
+@dataclass(frozen=True)
+class FolderScan:
+    root_path: Path
+    directories: list[ScannedDirectory]
+    files: list[ScannedFile]
+    skipped: list[SkippedPath]
+
+
+@dataclass
+class SyncManifest:
+    root_path: str
+    space_ref: str
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    max_file_bytes: int = MAX_DOCUMENT_UPLOAD_BYTES
+    version: int = MANIFEST_VERSION
+    created_at: str = field(default_factory=_now_iso)
+    updated_at: str = field(default_factory=_now_iso)
+    space: dict[str, Any] = field(default_factory=dict)
+    directories: dict[str, dict[str, Any]] = field(default_factory=dict)
+    files: dict[str, dict[str, Any]] = field(default_factory=dict)
+    last_run: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "version": self.version,
+            "root_path": self.root_path,
+            "space_ref": self.space_ref,
+            "space": self.space,
+            "include": self.include,
+            "exclude": self.exclude,
+            "max_file_bytes": self.max_file_bytes,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "directories": self.directories,
+            "files": self.files,
+            "last_run": self.last_run,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SyncManifest":
+        version = int(data.get("version") or 0)
+        if version != MANIFEST_VERSION:
+            raise ValueError(f"Unsupported folder sync manifest version: {version}")
+        return cls(
+            version=version,
+            root_path=str(data["root_path"]),
+            space_ref=str(data["space_ref"]),
+            space=dict(data.get("space") or {}),
+            include=list(data.get("include") or []),
+            exclude=list(data.get("exclude") or []),
+            max_file_bytes=int(data.get("max_file_bytes") or MAX_DOCUMENT_UPLOAD_BYTES),
+            created_at=str(data.get("created_at") or _now_iso()),
+            updated_at=str(data.get("updated_at") or _now_iso()),
+            directories=dict(data.get("directories") or {}),
+            files=dict(data.get("files") or {}),
+            last_run=dict(data.get("last_run") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class FilePlanItem:
+    relative_path: str
+    action: str
+    reason: str
+    scanned: ScannedFile | None = None
+    skipped: SkippedPath | None = None
+    previous: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DirectoryPlanItem:
+    relative_path: str
+    action: str
+    scanned: ScannedDirectory | None = None
+    previous: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SyncPlan:
+    root_path: Path
+    manifest: SyncManifest
+    directories: list[DirectoryPlanItem]
+    files: list[FilePlanItem]
+    deleted_files: list[str]
+    deleted_directories: list[str]
+
+    def summary(self) -> dict[str, int]:
+        file_counts: dict[str, int] = {}
+        for item in self.files:
+            file_counts[item.action] = file_counts.get(item.action, 0) + 1
+        dir_counts: dict[str, int] = {}
+        for item in self.directories:
+            dir_counts[item.action] = dir_counts.get(item.action, 0) + 1
+        return {
+            "directories_create": dir_counts.get("create", 0),
+            "directories_unchanged": dir_counts.get("unchanged", 0),
+            "files_ingest": file_counts.get("ingest", 0),
+            "files_reingest": file_counts.get("reingest", 0),
+            "files_unchanged": file_counts.get("unchanged", 0),
+            "files_skipped": file_counts.get("skipped", 0),
+            "deleted_files_reported": len(self.deleted_files),
+            "deleted_directories_reported": len(self.deleted_directories),
+        }
+
+
+class FolderSyncBackend(Protocol):
+    def create_collection(
+        self,
+        *,
+        relative_path: str,
+        name: str,
+        summary: str,
+        metadata: dict[str, Any],
+    ) -> dict[str, Any]:
+        ...
+
+    def place_node(
+        self,
+        *,
+        parent_id: str,
+        child_id: str,
+        name: str,
+        metadata: dict[str, Any],
+    ) -> dict[str, Any]:
+        ...
+
+    def ingest_file(
+        self,
+        file: ScannedFile,
+        *,
+        metadata: dict[str, Any],
+    ) -> dict[str, Any]:
+        ...
+
+
+class EngineFolderSyncBackend:
+    def __init__(
+        self,
+        engine: ArthaEngine,
+        *,
+        scope: list[str],
+        event_metadata: dict[str, object] | None = None,
+    ) -> None:
+        self.engine = engine
+        self.scope = list(scope)
+        self.event_metadata = dict(event_metadata or {})
+
+    def create_collection(
+        self,
+        *,
+        relative_path: str,
+        name: str,
+        summary: str,
+        metadata: dict[str, Any],
+    ) -> dict[str, Any]:
+        return create_collection(
+            self.engine,
+            name=name,
+            summary=summary,
+            scope=self.scope,
+            metadata=metadata,
+            event_metadata=self.event_metadata,
+        )
+
+    def place_node(
+        self,
+        *,
+        parent_id: str,
+        child_id: str,
+        name: str,
+        metadata: dict[str, Any],
+    ) -> dict[str, Any]:
+        return place_node_in_collection(
+            self.engine,
+            parent_id=parent_id,
+            child_id=child_id,
+            name=name,
+            scope=self.scope,
+            metadata=metadata,
+            event_metadata=self.event_metadata,
+        )
+
+    def ingest_file(
+        self,
+        file: ScannedFile,
+        *,
+        metadata: dict[str, Any],
+    ) -> dict[str, Any]:
+        content_type = mimetypes.guess_type(file.path.name)[0]
+        return ingest_document_source(
+            self.engine,
+            file_name=file.path.name,
+            content_type=content_type,
+            file_bytes=file.path.read_bytes(),
+            scope=self.scope,
+            metadata=metadata,
+            event_metadata=self.event_metadata,
+        )
+
+
+def scan_folder(
+    root: str | Path,
+    *,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    max_file_bytes: int = MAX_DOCUMENT_UPLOAD_BYTES,
+) -> FolderScan:
+    root_path = _normalize_root(root)
+    includes = list(include or [])
+    excludes = [*DEFAULT_EXCLUDES, *_load_ignore_file(root_path), *(exclude or [])]
+    directories = [ScannedDirectory(root_path, ".")]
+    files: list[ScannedFile] = []
+    skipped: list[SkippedPath] = []
+
+    for current, dir_names, file_names in root_path.walk():
+        current_path = Path(current)
+        kept_dirs: list[str] = []
+        for dir_name in sorted(dir_names):
+            child = current_path / dir_name
+            rel_path = _rel(child, root_path)
+            if _matches_any(excludes, rel_path, is_dir=True):
+                skipped.append(SkippedPath(child, rel_path, "ignored directory"))
+                continue
+            if includes and not _matches_any(includes, rel_path, is_dir=True):
+                # Keep walking because an include may match a descendant.
+                kept_dirs.append(dir_name)
+                directories.append(ScannedDirectory(child, rel_path))
+                continue
+            kept_dirs.append(dir_name)
+            directories.append(ScannedDirectory(child, rel_path))
+        dir_names[:] = kept_dirs
+
+        for file_name in sorted(file_names):
+            path = current_path / file_name
+            rel_path = _rel(path, root_path)
+            try:
+                stat = path.stat()
+            except OSError as exc:
+                skipped.append(SkippedPath(path, rel_path, f"stat failed: {exc}"))
+                continue
+            if _matches_any(excludes, rel_path, is_dir=False):
+                skipped.append(SkippedPath(path, rel_path, "ignored file", stat.st_size))
+                continue
+            if includes and not _matches_any(includes, rel_path, is_dir=False):
+                skipped.append(SkippedPath(path, rel_path, "not included", stat.st_size))
+                continue
+            if stat.st_size > max_file_bytes:
+                skipped.append(
+                    SkippedPath(
+                        path,
+                        rel_path,
+                        f"file exceeds max upload size ({max_file_bytes} bytes)",
+                        stat.st_size,
+                    )
+                )
+                continue
+            if not _supported(path):
+                skipped.append(SkippedPath(path, rel_path, "unsupported file type", stat.st_size))
+                continue
+            files.append(
+                ScannedFile(
+                    path=path,
+                    relative_path=rel_path,
+                    sha256=_sha256(path),
+                    mtime_ns=stat.st_mtime_ns,
+                    size_bytes=stat.st_size,
+                )
+            )
+    directories.sort(key=lambda item: (item.relative_path.count("/"), item.relative_path))
+    files.sort(key=lambda item: item.relative_path)
+    skipped.sort(key=lambda item: item.relative_path)
+    return FolderScan(root_path=root_path, directories=directories, files=files, skipped=skipped)
+
+
+def init_manifest(
+    path: str | Path,
+    *,
+    space_ref: str,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    max_file_bytes: int = MAX_DOCUMENT_UPLOAD_BYTES,
+    manifest_path: str | Path | None = None,
+    overwrite: bool = False,
+) -> tuple[SyncManifest, Path]:
+    root = _normalize_root(path)
+    target = Path(manifest_path).expanduser().resolve() if manifest_path else manifest_path_for_root(root)
+    if target.exists() and not overwrite:
+        raise ValueError(f"Folder sync manifest already exists: {target}")
+    manifest = SyncManifest(
+        root_path=str(root),
+        space_ref=space_ref,
+        include=list(include or []),
+        exclude=list(exclude or []),
+        max_file_bytes=max_file_bytes,
+    )
+    save_manifest(manifest, target)
+    return manifest, target
+
+
+def load_manifest(path: str | Path) -> SyncManifest:
+    data = json.loads(Path(path).expanduser().read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("Folder sync manifest must contain a JSON object")
+    return SyncManifest.from_dict(data)
+
+
+def save_manifest(manifest: SyncManifest, path: str | Path) -> None:
+    manifest.updated_at = _now_iso()
+    target = Path(path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        json.dumps(manifest.to_dict(), indent=2, sort_keys=True, ensure_ascii=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def resolve_manifest_path(path: str | Path, manifest_path: str | Path | None = None) -> Path:
+    if manifest_path is not None:
+        return Path(manifest_path).expanduser().resolve()
+    candidate = Path(path).expanduser().resolve()
+    if candidate.is_file():
+        return candidate
+    return manifest_path_for_root(candidate)
+
+
+def plan_folder_sync(manifest: SyncManifest) -> SyncPlan:
+    root = _normalize_root(manifest.root_path)
+    scan = scan_folder(
+        root,
+        include=manifest.include,
+        exclude=manifest.exclude,
+        max_file_bytes=manifest.max_file_bytes,
+    )
+    existing_dirs = manifest.directories
+    existing_files = manifest.files
+    seen_dirs = {item.relative_path for item in scan.directories}
+    seen_files = {item.relative_path for item in scan.files}
+    skipped_files = {item.relative_path for item in scan.skipped if item.path.is_file()}
+
+    dir_items: list[DirectoryPlanItem] = []
+    for directory in scan.directories:
+        previous = dict(existing_dirs.get(directory.relative_path) or {})
+        action = "unchanged" if previous.get("node_id") else "create"
+        dir_items.append(
+            DirectoryPlanItem(
+                relative_path=directory.relative_path,
+                action=action,
+                scanned=directory,
+                previous=previous,
+            )
+        )
+
+    file_items: list[FilePlanItem] = []
+    for file in scan.files:
+        previous = dict(existing_files.get(file.relative_path) or {})
+        if (
+            previous.get("sha256") == file.sha256
+            and previous.get("mtime_ns") == file.mtime_ns
+            and previous.get("size_bytes") == file.size_bytes
+            and previous.get("last_sync_status") == "synced"
+        ):
+            action = "unchanged"
+            reason = "hash, mtime, and size unchanged"
+        elif previous.get("collection_id") or previous.get("document_id"):
+            action = "reingest"
+            reason = "file changed; V0 imports a new document graph and keeps old nodes"
+        else:
+            action = "ingest"
+            reason = "new supported file"
+        file_items.append(
+            FilePlanItem(
+                relative_path=file.relative_path,
+                action=action,
+                reason=reason,
+                scanned=file,
+                previous=previous,
+            )
+        )
+    for skipped in scan.skipped:
+        if skipped.relative_path in skipped_files:
+            file_items.append(
+                FilePlanItem(
+                    relative_path=skipped.relative_path,
+                    action="skipped",
+                    reason=skipped.reason,
+                    skipped=skipped,
+                    previous=dict(existing_files.get(skipped.relative_path) or {}),
+                )
+            )
+
+    deleted_files = sorted(
+        rel
+        for rel in existing_files
+        if rel not in seen_files and rel not in skipped_files and rel != "."
+    )
+    deleted_dirs = sorted(rel for rel in existing_dirs if rel not in seen_dirs and rel != ".")
+    file_items.sort(key=lambda item: item.relative_path)
+    return SyncPlan(
+        root_path=root,
+        manifest=manifest,
+        directories=dir_items,
+        files=file_items,
+        deleted_files=deleted_files,
+        deleted_directories=deleted_dirs,
+    )
+
+
+def _folder_metadata(root: Path, relative_path: str) -> dict[str, Any]:
+    return {
+        "system": {
+            "folder_sync": {
+                "version": MANIFEST_VERSION,
+                "kind": "directory",
+                "root_path": str(root),
+                "relative_path": relative_path,
+            }
+        }
+    }
+
+
+def _file_metadata(root: Path, file: ScannedFile) -> dict[str, Any]:
+    return {
+        "system": {
+            "folder_sync": {
+                "version": MANIFEST_VERSION,
+                "kind": "file",
+                "root_path": str(root),
+                "path": str(file.path),
+                "relative_path": file.relative_path,
+                "sha256": file.sha256,
+                "mtime_ns": file.mtime_ns,
+                "size_bytes": file.size_bytes,
+            }
+        }
+    }
+
+
+def _parent_relative_path(relative_path: str) -> str:
+    if relative_path == "." or "/" not in relative_path:
+        return "."
+    return relative_path.rsplit("/", 1)[0]
+
+
+def run_folder_sync(
+    manifest: SyncManifest,
+    *,
+    backend: FolderSyncBackend,
+    manifest_path: str | Path | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    plan = plan_folder_sync(manifest)
+    if dry_run:
+        return {"status": "planned", "summary": plan.summary(), "manifest": manifest.to_dict()}
+
+    for item in plan.directories:
+        previous = dict(manifest.directories.get(item.relative_path) or {})
+        scanned = item.scanned
+        if scanned is None:
+            continue
+        if item.action == "create":
+            name = plan.root_path.name if item.relative_path == "." else scanned.path.name
+            summary = (
+                f"Folder sync root: {plan.root_path}"
+                if item.relative_path == "."
+                else f"Folder synced from {item.relative_path}"
+            )
+            collection = backend.create_collection(
+                relative_path=item.relative_path,
+                name=name,
+                summary=summary,
+                metadata=_folder_metadata(plan.root_path, item.relative_path),
+            )
+            previous.update(
+                {
+                    "path": str(scanned.path),
+                    "relative_path": item.relative_path,
+                    "node_id": collection["id"],
+                    "last_sync_status": "synced",
+                    "last_synced_at": _now_iso(),
+                }
+            )
+            if item.relative_path != ".":
+                parent_rel = _parent_relative_path(item.relative_path)
+                parent = manifest.directories.get(parent_rel) or {}
+                parent_id = parent.get("node_id")
+                if parent_id:
+                    placement = backend.place_node(
+                        parent_id=str(parent_id),
+                        child_id=str(collection["id"]),
+                        name=scanned.path.name,
+                        metadata={
+                            "role": "folder_sync_directory",
+                            "relative_path": item.relative_path,
+                        },
+                    )
+                    previous["placement_id"] = placement["id"]
+        else:
+            previous.update(
+                {
+                    "path": str(scanned.path),
+                    "relative_path": item.relative_path,
+                    "last_sync_status": "synced",
+                }
+            )
+        manifest.directories[item.relative_path] = previous
+
+    for item in plan.files:
+        previous = dict(manifest.files.get(item.relative_path) or {})
+        if item.action == "unchanged" and item.scanned is not None:
+            previous.update(
+                {
+                    "path": str(item.scanned.path),
+                    "relative_path": item.relative_path,
+                    "sha256": item.scanned.sha256,
+                    "mtime_ns": item.scanned.mtime_ns,
+                    "size_bytes": item.scanned.size_bytes,
+                    "last_sync_status": "synced",
+                    "last_skip_reason": None,
+                }
+            )
+            manifest.files[item.relative_path] = previous
+            continue
+        if item.action == "skipped" and item.skipped is not None:
+            previous.update(
+                {
+                    "path": str(item.skipped.path),
+                    "relative_path": item.relative_path,
+                    "size_bytes": item.skipped.size_bytes,
+                    "last_sync_status": "skipped",
+                    "last_skip_reason": item.reason,
+                    "last_synced_at": _now_iso(),
+                }
+            )
+            manifest.files[item.relative_path] = previous
+            continue
+        if item.scanned is None:
+            continue
+        try:
+            payload = backend.ingest_file(
+                item.scanned,
+                metadata=_file_metadata(plan.root_path, item.scanned),
+            )
+            parent_rel = _parent_relative_path(item.relative_path)
+            parent = manifest.directories.get(parent_rel) or manifest.directories.get(".") or {}
+            parent_id = parent.get("node_id")
+            placement_id = None
+            collection_id = str(payload["collection"]["id"])
+            if parent_id:
+                placement = backend.place_node(
+                    parent_id=str(parent_id),
+                    child_id=collection_id,
+                    name=item.scanned.path.name,
+                    metadata={"role": "folder_sync_file", "relative_path": item.relative_path},
+                )
+                placement_id = placement["id"]
+            history = list(previous.get("history") or [])
+            if previous.get("collection_id") or previous.get("document_id"):
+                history.append(
+                    {
+                        "collection_id": previous.get("collection_id"),
+                        "document_id": previous.get("document_id"),
+                        "sha256": previous.get("sha256"),
+                        "replaced_at": _now_iso(),
+                    }
+                )
+            previous.update(
+                {
+                    "path": str(item.scanned.path),
+                    "relative_path": item.relative_path,
+                    "sha256": item.scanned.sha256,
+                    "mtime_ns": item.scanned.mtime_ns,
+                    "size_bytes": item.scanned.size_bytes,
+                    "collection_id": collection_id,
+                    "document_id": str(payload["document"]["id"]),
+                    "document_key": str(payload["document_key"]),
+                    "placement_id": placement_id,
+                    "last_sync_status": "synced",
+                    "last_sync_action": item.action,
+                    "last_error": None,
+                    "last_skip_reason": None,
+                    "last_synced_at": _now_iso(),
+                    "history": history,
+                }
+            )
+        except Exception as exc:
+            previous.update(
+                {
+                    "path": str(item.scanned.path),
+                    "relative_path": item.relative_path,
+                    "sha256": item.scanned.sha256,
+                    "mtime_ns": item.scanned.mtime_ns,
+                    "size_bytes": item.scanned.size_bytes,
+                    "last_sync_status": "error",
+                    "last_error": str(exc),
+                    "last_synced_at": _now_iso(),
+                }
+            )
+        manifest.files[item.relative_path] = previous
+
+    for relative_path in plan.deleted_files:
+        entry = dict(manifest.files.get(relative_path) or {})
+        entry["last_sync_status"] = "deleted_local"
+        entry["last_skip_reason"] = "local path missing; V0 does not delete remote nodes"
+        entry["last_synced_at"] = _now_iso()
+        manifest.files[relative_path] = entry
+    for relative_path in plan.deleted_directories:
+        entry = dict(manifest.directories.get(relative_path) or {})
+        entry["last_sync_status"] = "deleted_local"
+        entry["last_skip_reason"] = "local path missing; V0 does not delete remote nodes"
+        entry["last_synced_at"] = _now_iso()
+        manifest.directories[relative_path] = entry
+
+    manifest.last_run = {"ran_at": _now_iso(), "summary": plan.summary()}
+    if manifest_path is not None:
+        save_manifest(manifest, manifest_path)
+    return {"status": "success", "summary": plan.summary(), "manifest": manifest.to_dict()}
+
+
+def run_engine_folder_sync(
+    engine: ArthaEngine,
+    manifest: SyncManifest,
+    *,
+    scope: list[str],
+    event_metadata: dict[str, object] | None = None,
+    manifest_path: str | Path | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    ensure_memory_projections(engine)
+    backend = EngineFolderSyncBackend(engine, scope=scope, event_metadata=event_metadata)
+    return run_folder_sync(
+        manifest,
+        backend=backend,
+        manifest_path=manifest_path,
+        dry_run=dry_run,
+    )