@wipcomputer/wip-ldm-os 0.4.86 → 0.4.87-alpha.2

package/scripts/ldm-backup-engine.py

@@ -0,0 +1,1176 @@
+#!/usr/bin/env python3
+"""LDM OS backup engine.
+
+All capture, estimation, manifest, and exclusion decisions come from one JSON
+policy. The test suite injects every path beneath a disposable fixture root.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import errno
+import fnmatch
+import hashlib
+import json
+import os
+import shutil
+import sqlite3
+import stat
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+TOOL_VERSION = "2.0.0"
+SCHEDULE_ID = "ai.openclaw.ldm-backup"
+VALID_EVIDENCE_STATUS = {"complete", "deferred-after-write-failure"}
+JSON_SEPARATORS = (",", ":")
+
+
+class BackupError(RuntimeError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+class SimulatedDiskFull(BackupError):
+    def __init__(self) -> None:
+        super().__init__("disk-full-during-capture", "simulated disk full during capture")
+
+
+@dataclass(frozen=True)
+class Roots:
+    home: Path
+    ldm: Path
+    openclaw: Path
+    claude: Path
+    codex: Path
+    workspace: Path
+    backup: Path
+    state: Path
+    icloud: Path
+    lock: Path
+
+    def mapping(self) -> dict[str, Path]:
+        return {
+            "HOME": self.home,
+            "LDM_HOME": self.ldm,
+            "OPENCLAW_HOME": self.openclaw,
+            "CLAUDE_HOME": self.claude,
+            "CODEX_HOME": self.codex,
+            "WORKSPACE": self.workspace,
+        }
+
+
+def utc_now() -> str:
+    return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def snapshot_id() -> str:
+    return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%d--%H-%M-%SZ")
+
+
+def json_bytes(value: Any) -> bytes:
+    return (json.dumps(value, sort_keys=True, separators=JSON_SEPARATORS) + "\n").encode("utf-8")
+
+
+def sha256_file(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 sha256_text(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def write_atomic(path: Path, value: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(json_bytes(value))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+        directory_fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        try:
+            os.unlink(temp_name)
+        except FileNotFoundError:
+            pass
+
+
+def nearest_existing(path: Path) -> Path:
+    current = path.resolve(strict=False)
+    while not current.exists() and current != current.parent:
+        current = current.parent
+    return current
+
+
+def path_within(path: Path, root: Path) -> bool:
+    try:
+        path.resolve(strict=False).relative_to(root.resolve(strict=True))
+        return True
+    except (ValueError, FileNotFoundError):
+        return False
+
+
+def load_config(ldm_home: Path) -> dict[str, Any]:
+    config_path = ldm_home / "config.json"
+    try:
+        value = json.loads(config_path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (json.JSONDecodeError, OSError) as exc:
+        raise BackupError("config-invalid", f"cannot load {config_path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise BackupError("config-invalid", "config.json must contain a JSON object")
+    for key in ("paths", "backup"):
+        if key in value and not isinstance(value[key], dict):
+            raise BackupError("config-invalid", f"config.json field {key} must be an object")
+    return value
+
+
+def resolve_roots() -> Roots:
+    home = Path(os.environ.get("LDM_BACKUP_HOME", os.environ.get("HOME", "~"))).expanduser()
+    ldm = Path(os.environ.get("LDM_BACKUP_LDM_HOME", home / ".ldm")).expanduser()
+    config = load_config(ldm)
+    config_workspace = config.get("workspace") or config.get("paths", {}).get("workspace") or home / "wipcomputerinc"
+    config_icloud = config.get("paths", {}).get("icloudBackup") or home / "Library/Mobile Documents/com~apple~CloudDocs/ldm-backups"
+    openclaw = Path(os.environ.get("LDM_BACKUP_OPENCLAW_HOME", home / ".openclaw")).expanduser()
+    claude = Path(os.environ.get("LDM_BACKUP_CLAUDE_HOME", home / ".claude")).expanduser()
+    codex = Path(os.environ.get("LDM_BACKUP_CODEX_HOME", home / ".codex")).expanduser()
+    workspace = Path(os.environ.get("LDM_BACKUP_WORKSPACE", config_workspace)).expanduser()
+    backup = Path(os.environ.get("LDM_BACKUP_DESTINATION", ldm / "backups/v1/internal")).expanduser()
+    state = Path(os.environ.get("LDM_BACKUP_STATE_DIR", ldm / "state/backup/v1")).expanduser()
+    icloud = Path(os.environ.get("LDM_BACKUP_ICLOUD_SUBSTITUTE", config_icloud)).expanduser()
+    lock = Path(os.environ.get("LDM_BACKUP_LOCK_PATH", state / "backup.lock")).expanduser()
+    return Roots(home, ldm, openclaw, claude, codex, workspace, backup, state, icloud, lock)
+
+
+def prove_fixture_isolation(roots: Roots) -> Path | None:
+    required = os.environ.get("LDM_BACKUP_REQUIRE_FIXTURE") == "1"
+    fixture_text = os.environ.get("LDM_BACKUP_FIXTURE_ROOT", "")
+    if not required and not fixture_text:
+        return None
+    if not fixture_text:
+        raise BackupError("fixture-root-missing", "fixture mode requires LDM_BACKUP_FIXTURE_ROOT")
+    fixture = Path(fixture_text).resolve(strict=True)
+    if not fixture.name.startswith("ldm-backup-fixture-"):
+        raise BackupError("fixture-root-unsafe", "fixture root must use the ldm-backup-fixture- prefix")
+    checked = {
+        "home": roots.home,
+        "ldm": roots.ldm,
+        "openclaw": roots.openclaw,
+        "claude": roots.claude,
+        "codex": roots.codex,
+        "workspace": roots.workspace,
+        "backup": roots.backup,
+        "state": roots.state,
+        "icloud": roots.icloud,
+        "lock": roots.lock,
+    }
+    unsafe = [name for name, value in checked.items() if not path_within(value, fixture)]
+    if unsafe:
+        raise BackupError("fixture-path-escape", f"fixture paths escape root: {', '.join(sorted(unsafe))}")
+    return fixture
+
+
+def load_policy(path: Path) -> dict[str, Any]:
+    try:
+        policy = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError) as exc:
+        raise BackupError("policy-invalid", f"cannot load policy: {exc}") from exc
+    if policy.get("schema_version") != 1 or not isinstance(policy.get("sources"), list):
+        raise BackupError("policy-invalid", "policy schema_version must be 1 and sources must be a list")
+    evidence_values = set(policy.get("evidence_status_values", []))
+    if evidence_values != VALID_EVIDENCE_STATUS:
+        raise BackupError("policy-enum-invalid", "evidence_status enum must contain only complete and deferred-after-write-failure")
+    if "complete-or-deferred-after-write-failure" in evidence_values:
+        raise BackupError("policy-enum-invalid", "placeholder evidence_status is forbidden")
+    ids: set[str] = set()
+    for source in policy["sources"]:
+        source_id = source.get("id")
+        if not source_id or source_id in ids:
+            raise BackupError("policy-invalid", "every source requires a unique id")
+        ids.add(source_id)
+        if source.get("action") not in {"capture", "blocked", "manifest", "exclude"}:
+            raise BackupError("policy-invalid", f"invalid action for {source_id}")
+        if source.get("type") not in {"file", "tree", "sqlite"}:
+            raise BackupError("policy-invalid", f"invalid type for {source_id}")
+        destination = source.get("destination")
+        if destination is not None:
+            destination_path = Path(destination)
+            if destination_path.is_absolute() or ".." in destination_path.parts:
+                raise BackupError("policy-invalid", f"destination must stay relative for {source_id}")
+    return policy
+
+
+def prove_policy_fixture_isolation(policy: dict[str, Any], roots: Roots, fixture: Path | None) -> None:
+    if fixture is None:
+        return
+    for source in policy["sources"]:
+        resolved = source_path(source, roots)
+        if not path_within(resolved, fixture):
+            raise BackupError("fixture-source-escape", f"source path escapes fixture root: {source['id']}")
+        destination = source.get("destination")
+        if destination and not path_within(roots.backup / destination, fixture):
+            raise BackupError("fixture-destination-escape", f"destination path escapes fixture root: {source['id']}")
+
+
+def is_excluded(relative: str, rules: list[dict[str, Any]]) -> dict[str, Any] | None:
+    value = relative.replace(os.sep, "/")
+    for rule in rules:
+        pattern = rule["pattern"]
+        if fnmatch.fnmatch(value, pattern) or (pattern.startswith("**/") and fnmatch.fnmatch(value, pattern[3:])):
+            return rule
+    return None
+
+
+def tree_members(
+    root: Path,
+    rules: list[dict[str, Any]],
+    *,
+    hash_content: bool = True,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    root_info = root.lstat()
+    members: list[dict[str, Any]] = [{"relative": "", "kind": "directory", "size": 0, "mtime_ns": root_info.st_mtime_ns, "checksum": sha256_text("")}]
+    exclusions: dict[str, dict[str, Any]] = {}
+    for base, dirs, files in os.walk(root, topdown=True, followlinks=False):
+        base_path = Path(base)
+        kept_dirs: list[str] = []
+        for name in sorted(dirs):
+            directory_path = base_path / name
+            relative = str(directory_path.relative_to(root))
+            rule = is_excluded(relative + "/", rules)
+            if rule:
+                exclusions.setdefault(rule["pattern"], {**rule, "matched_count": 0})["matched_count"] += 1
+            elif directory_path.is_symlink():
+                target = os.readlink(directory_path)
+                info = directory_path.lstat()
+                members.append({"relative": relative, "kind": "symlink", "size": len(target.encode()), "mtime_ns": info.st_mtime_ns, "checksum": sha256_text(target)})
+            else:
+                kept_dirs.append(name)
+                info = directory_path.lstat()
+                members.append({"relative": relative, "kind": "directory", "size": 0, "mtime_ns": info.st_mtime_ns, "checksum": sha256_text("")})
+        dirs[:] = kept_dirs
+        for name in sorted(files):
+            source = base_path / name
+            relative = str(source.relative_to(root))
+            rule = is_excluded(relative, rules)
+            if rule:
+                exclusions.setdefault(rule["pattern"], {**rule, "matched_count": 0})["matched_count"] += 1
+                continue
+            info = source.lstat()
+            if stat.S_ISLNK(info.st_mode):
+                target = os.readlink(source)
+                members.append({"relative": relative, "kind": "symlink", "size": len(target.encode()), "mtime_ns": info.st_mtime_ns, "checksum": sha256_text(target)})
+            elif stat.S_ISREG(info.st_mode):
+                checksum = sha256_file(source) if hash_content else "0" * 64
+                members.append({"relative": relative, "kind": "file", "size": info.st_size, "mtime_ns": info.st_mtime_ns, "checksum": checksum})
+            else:
+                raise BackupError("unsupported-source-type", f"unsupported file type in source {root.name}")
+    for rule in rules:
+        exclusions.setdefault(rule["pattern"], {**rule, "matched_count": 0})
+    return members, list(exclusions.values())
+
+
+def sqlite_planned_size(path: Path) -> int:
+    try:
+        connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        try:
+            page_count = int(connection.execute("PRAGMA page_count").fetchone()[0])
+            page_size = int(connection.execute("PRAGMA page_size").fetchone()[0])
+            return page_count * page_size
+        finally:
+            connection.close()
+    except sqlite3.Error as exc:
+        raise BackupError("sqlite-source-invalid", f"SQLite preflight failed for source id: {path.name}") from exc
+
+
+def source_path(source: dict[str, Any], roots: Roots) -> Path:
+    root_name = source.get("root")
+    if root_name not in roots.mapping():
+        raise BackupError("policy-invalid", f"unknown root {root_name}")
+    return (roots.mapping()[root_name] / source.get("path", ".")).resolve(strict=False)
+
+
+def make_source_plan(
+    source: dict[str, Any],
+    roots: Roots,
+    *,
+    hash_content: bool = True,
+) -> dict[str, Any]:
+    path = source_path(source, roots)
+    classification = list(source.get("classification", []))
+    base = {
+        "id": source["id"],
+        "display_path": source.get("display_path", f"${source['root']}/{source.get('path', '')}"),
+        "classification": classification,
+        "required": bool(source.get("required")),
+        "action": source["action"],
+        "type": source["type"],
+        "destination": source.get("destination"),
+        "estimated_bytes": 0,
+        "status": "planned",
+        "members": [],
+        "exclusions": [],
+        "source_path": str(path),
+        "source_definition": source,
+    }
+    if source["action"] == "blocked":
+        base["status"] = "blocked"
+        base["block_reason"] = source.get("block_reason", "policy gate is unresolved")
+        return base
+    if source["action"] == "manifest" and source.get("manifest_generator") != "path-inventory":
+        base["status"] = "blocked"
+        base["block_reason"] = "manifest generator is not implemented"
+        return base
+    if source["action"] == "exclude":
+        base["status"] = "exclude"
+        base["exclusions"] = source.get("exclusions", [])
+        return base
+    if not path.exists():
+        base["status"] = "missing"
+        return base
+    info = path.lstat()
+    if source["type"] == "tree":
+        if not path.is_dir():
+            base["status"] = "type-mismatch"
+            return base
+        members, exclusions = tree_members(
+            path,
+            source.get("exclusions", []),
+            hash_content=hash_content,
+        )
+        base["members"] = members
+        base["exclusions"] = exclusions
+        base["estimated_bytes"] = sum(item["size"] for item in members)
+    elif source["type"] == "sqlite":
+        if not path.is_file():
+            base["status"] = "type-mismatch"
+            return base
+        size = sqlite_planned_size(path)
+        base["members"] = [{"relative": "", "kind": "sqlite", "size": size, "mtime_ns": info.st_mtime_ns, "checksum": None}]
+        base["estimated_bytes"] = size
+    else:
+        if not path.is_file():
+            base["status"] = "type-mismatch"
+            return base
+        if stat.S_ISLNK(info.st_mode):
+            target = os.readlink(path)
+            member = {"relative": "", "kind": "symlink", "size": len(target.encode()), "mtime_ns": info.st_mtime_ns, "checksum": sha256_text(target)}
+        else:
+            checksum = sha256_file(path) if hash_content else "0" * 64
+            member = {"relative": "", "kind": "file", "size": info.st_size, "mtime_ns": info.st_mtime_ns, "checksum": checksum}
+        base["members"] = [member]
+        base["estimated_bytes"] = member["size"]
+    if source["action"] == "manifest":
+        base["estimated_bytes"] = 0
+    return base
+
+
+def disk_values(path: Path) -> tuple[int, int]:
+    test_total = os.environ.get("LDM_BACKUP_TEST_TOTAL_BYTES")
+    test_available = os.environ.get("LDM_BACKUP_TEST_AVAILABLE_BYTES")
+    if test_total is not None or test_available is not None:
+        if test_total is None or test_available is None:
+            raise BackupError("test-disk-values-incomplete", "both test disk values are required")
+        return int(test_total), int(test_available)
+    usage = shutil.disk_usage(nearest_existing(path))
+    return usage.total, usage.free
+
+
+def planned_manifest(run_id: str, started_at: str, policy: dict[str, Any], sources: list[dict[str, Any]]) -> dict[str, Any]:
+    records = []
+    observations = []
+    evidence = []
+    exclusions = []
+    for item in sources:
+        if item["action"] == "capture" and item["status"] == "planned":
+            observations.append({
+                "source_id": item["id"],
+                "consistency_contract": (
+                    "sqlite-backup-api-transaction-snapshot"
+                    if item["type"] == "sqlite"
+                    else "capture-time-stable"
+                ),
+                "planned_member_count": len(item["members"]),
+                "planned_payload_bytes": sum(member["size"] for member in item["members"]),
+                "planned_inventory_sha256": members_fingerprint(item["members"]),
+                "capture_member_count": len(item["members"]),
+                "capture_payload_bytes": sum(member["size"] for member in item["members"]),
+                "capture_inventory_sha256": members_fingerprint(item["members"]),
+                "changed_since_plan": None if item["type"] == "sqlite" else False,
+                "metadata_changed_since_plan": False,
+            })
+            for member in item["members"]:
+                relative_destination = item["destination"]
+                if member["relative"]:
+                    relative_destination = f"{relative_destination}/{member['relative']}"
+                records.append({
+                    "source_id": item["id"],
+                    "source_path": item["source_path"],
+                    "destination": relative_destination,
+                    "type": member["kind"],
+                    "size": member["size"],
+                    "mtime_ns": member["mtime_ns"],
+                    "checksum_sha256": "0" * 64 if member["kind"] == "sqlite" else member["checksum"],
+                    "planned_size": member["size"],
+                    "planned_mtime_ns": member["mtime_ns"],
+                    "planned_checksum_sha256": member["checksum"],
+                    "changed_since_plan": None if member["kind"] == "sqlite" else False,
+                    "consistency_contract": (
+                        "sqlite-backup-api-transaction-snapshot"
+                        if member["kind"] == "sqlite"
+                        else "capture-time-stable"
+                    ),
+                })
+        if item["action"] == "manifest" and item["status"] == "planned":
+            evidence.append(manifest_evidence(item))
+        for exclusion in item.get("exclusions", []):
+            exclusions.append({
+                "source_id": item["id"],
+                "path": exclusion.get("pattern", item["display_path"]),
+                "reason": exclusion.get("reason", item.get("block_reason", item["status"])),
+                "reconstruction_source": exclusion.get("reconstruction_source", "policy gate required"),
+                "rule_version": exclusion.get("rule_version", policy["rule_version"]),
+                "matched_count": exclusion.get("matched_count", 0),
+            })
+        if item["status"] in {"blocked", "missing", "type-mismatch"}:
+            exclusions.append({
+                "source_id": item["id"],
+                "path": item["display_path"],
+                "reason": item.get("block_reason", item["status"]),
+                "reconstruction_source": "unresolved required-source gate",
+                "rule_version": policy["rule_version"],
+                "matched_count": 1,
+            })
+    return {
+        "schema_version": 1,
+        "snapshot_id": run_id,
+        "tool_version": TOOL_VERSION,
+        "policy_rule_version": policy["rule_version"],
+        "started_at": started_at,
+        "completed_at": "0000-00-00T00:00:00Z",
+        "terminal_result": "success",
+        "sources": records,
+        "source_observations": observations,
+        "manifest_evidence": evidence,
+        "exclusions": exclusions,
+    }
+
+
+def completion_value(run_id: str) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "snapshot_id": run_id,
+        "status": "complete",
+        "manifest_sha256": "0" * 64,
+        "completed_at": "0000-00-00T00:00:00Z",
+    }
+
+
+def build_plan(policy: dict[str, Any], roots: Roots, run_id: str, started_at: str) -> dict[str, Any]:
+    sources = [make_source_plan(source, roots) for source in policy["sources"]]
+    blockers = [item for item in sources if item["required"] and item["status"] != "planned" and item["action"] == "capture"]
+    blockers.extend(item for item in sources if item["required"] and item["status"] != "planned" and item["action"] == "manifest")
+    blockers.extend(item for item in sources if item["required"] and item["status"] == "blocked")
+    payload_bytes = sum(item["estimated_bytes"] for item in sources if item["status"] == "planned")
+    manifest = planned_manifest(run_id, started_at, policy, sources)
+    manifest["planned_payload_bytes"] = payload_bytes
+    manifest["captured_payload_bytes"] = payload_bytes
+    metadata_bytes = len(json_bytes(manifest)) + len(json_bytes(completion_value(run_id)))
+    total, available = disk_values(roots.backup)
+    reserve_percent = int(policy["disk_floors"]["start_reserve_percent"])
+    required_reserve = (total * reserve_percent + 99) // 100
+    estimated_new = payload_bytes + metadata_bytes
+    reserve_after = available - estimated_new
+    destination_parent = nearest_existing(roots.backup)
+    destination_ok = destination_parent.is_dir() and os.access(destination_parent, os.W_OK)
+    allowed = not blockers and destination_ok and reserve_after >= required_reserve
+    reasons = []
+    if blockers:
+        reasons.append("required-source-gate")
+    if not destination_ok:
+        reasons.append("destination-unavailable")
+    if reserve_after < required_reserve:
+        reasons.append("reserve-gate")
+    return {
+        "schema_version": 1,
+        "dry_run": False,
+        "snapshot_id": run_id,
+        "tool_version": TOOL_VERSION,
+        "policy_rule_version": policy["rule_version"],
+        "planned_staging_path": str(roots.backup / f".in-progress-{run_id}"),
+        "planned_destination_path": str(roots.backup / run_id),
+        "icloud_tier": {"path": str(roots.icloud), "status": "not-in-slice-4", "write": False},
+        "vault_tier": {"path": None, "status": "not-in-slice-3", "write": False},
+        "sources": sources,
+        "initial_estimated_payload_bytes": payload_bytes,
+        "estimated_payload_bytes": payload_bytes,
+        "initial_estimated_metadata_bytes": metadata_bytes,
+        "estimated_metadata_bytes": metadata_bytes,
+        "estimated_new_bytes": estimated_new,
+        "disk_total_bytes": total,
+        "disk_available_bytes": available,
+        "required_reserve_bytes": required_reserve,
+        "reserve_after_bytes": reserve_after,
+        "preflight_allowed": allowed,
+        "blocking_reasons": reasons,
+        "manifest_template": manifest,
+        "policy": policy,
+    }
+
+
+def public_plan(plan: dict[str, Any]) -> dict[str, Any]:
+    safe_sources = []
+    for item in plan["sources"]:
+        safe_sources.append({key: item[key] for key in (
+            "id", "display_path", "classification", "required", "action", "type",
+            "destination", "estimated_bytes", "status",
+        )} | ({"block_reason": item["block_reason"]} if "block_reason" in item else {}) | {
+            "exclusions": [
+                {key: value for key, value in exclusion.items() if key in {"pattern", "reason", "reconstruction_source", "rule_version", "matched_count"}}
+                for exclusion in item.get("exclusions", [])
+            ]
+        })
+    return {key: value for key, value in plan.items() if key not in {"sources", "manifest_template", "policy"}} | {"sources": safe_sources}
+
+
+def print_plan(plan: dict[str, Any], as_json: bool) -> None:
+    safe = public_plan(plan)
+    if as_json:
+        print(json.dumps(safe, indent=2, sort_keys=True))
+        return
+    print("=== LDM Backup dry run ===")
+    print(f"Policy: {safe['policy_rule_version']}")
+    for item in safe["sources"]:
+        classes = ", ".join(item["classification"])
+        print(f"- {item['id']}: {item['display_path']}")
+        print(f"  class={classes} action={item['action']} status={item['status']} estimated_bytes={item['estimated_bytes']}")
+        if item.get("block_reason"):
+            print(f"  blocked: {item['block_reason']}")
+        for exclusion in item.get("exclusions", []):
+            print(f"  exclude {exclusion.get('pattern', 'policy')}: {exclusion.get('reason', 'policy rule')}")
+    print(f"Total estimated new bytes: {safe['estimated_new_bytes']}")
+    print(f"Disk capacity bytes: {safe['disk_total_bytes']}")
+    print(f"Disk available bytes: {safe['disk_available_bytes']}")
+    print(f"Required reserve bytes: {safe['required_reserve_bytes']}")
+    print(f"Reserve after proposed backup: {safe['reserve_after_bytes']}")
+    print(f"Planned staging path: {safe['planned_staging_path']}")
+    print(f"Planned destination path: {safe['planned_destination_path']}")
+    print(f"Preflight: {'PASS' if safe['preflight_allowed'] else 'FAIL'}")
+    if safe["blocking_reasons"]:
+        print(f"Blocking reasons: {', '.join(safe['blocking_reasons'])}")
+    print("[DRY RUN] No files modified.")
+
+
+def pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def acquire_lock(path: Path, run_id: str) -> int:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError as exc:
+        try:
+            lock = json.loads(path.read_text(encoding="utf-8"))
+            pid = int(lock.get("pid", 0))
+        except (OSError, ValueError, json.JSONDecodeError):
+            raise BackupError("lock-invalid", "existing lock is unreadable and was not replaced") from exc
+        if pid and pid_alive(pid):
+            raise BackupError("concurrent-run", f"backup already running with pid {pid}") from exc
+        raise BackupError("stale-lock", f"stale lock detected for dead pid {pid}; lock was not stolen") from exc
+    payload = json_bytes({"schema_version": 1, "pid": os.getpid(), "snapshot_id": run_id, "created_at": utc_now()})
+    if os.write(fd, payload) != len(payload):
+        os.close(fd)
+        raise BackupError("lock-write-failed", "lock payload write was incomplete")
+    os.fsync(fd)
+    return fd
+
+
+def release_lock(path: Path, fd: int | None) -> None:
+    if fd is None:
+        return
+    owned = os.fstat(fd)
+    try:
+        current = path.lstat()
+        if current.st_dev == owned.st_dev and current.st_ino == owned.st_ino:
+            path.unlink()
+    except FileNotFoundError:
+        pass
+    finally:
+        os.close(fd)
+
+
+def copy_member(source_root: Path, destination_root: Path, member: dict[str, Any]) -> int:
+    relative = Path(member["relative"]) if member["relative"] else Path()
+    source = source_root / relative
+    destination = destination_root / relative
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if member["kind"] == "directory":
+        destination.mkdir(parents=True, exist_ok=True)
+        shutil.copystat(source, destination, follow_symlinks=False)
+        return 0
+    if member["kind"] == "symlink":
+        os.symlink(os.readlink(source), destination)
+        return member["size"]
+    shutil.copy2(source, destination, follow_symlinks=False)
+    return destination.stat().st_size
+
+
+def member_key(member: dict[str, Any]) -> tuple[str, str]:
+    return member["relative"], member["kind"]
+
+
+def member_map(members: list[dict[str, Any]]) -> dict[tuple[str, str], dict[str, Any]]:
+    return {member_key(member): member for member in members}
+
+
+def members_changed(before: list[dict[str, Any]], after: list[dict[str, Any]]) -> bool:
+    return member_map(before) != member_map(after)
+
+
+def members_fingerprint(members: list[dict[str, Any]]) -> str:
+    return hashlib.sha256(json_bytes(members)).hexdigest()
+
+
+def manifest_evidence(item: dict[str, Any]) -> dict[str, Any]:
+    members = item["members"]
+    return {
+        "source_id": item["id"],
+        "generator": item["source_definition"].get("manifest_generator"),
+        "source_path": item["source_path"],
+        "source_type": item["type"],
+        "member_count": len(members),
+        "logical_bytes": sum(member["size"] for member in members),
+        "inventory_sha256": members_fingerprint(members),
+        "members": members,
+        "generated_at": "0000-00-00T00:00:00Z",
+        "status": "valid",
+    }
+
+
+def apply_test_source_mutation(item: dict[str, Any], phase: str) -> None:
+    if os.environ.get("LDM_BACKUP_TEST_MUTATE_SOURCE_ID") != item["id"]:
+        return
+    if os.environ.get("LDM_BACKUP_TEST_MUTATE_PHASE", "before-capture") != phase:
+        return
+    mode = os.environ.get("LDM_BACKUP_TEST_MUTATE_MODE", "same-size")
+    source_root = Path(item["source_path"])
+    member = next((value for value in item["members"] if value["kind"] == "file"), None)
+    if member is None:
+        raise BackupError("test-mutation-invalid", "test mutation requires a regular file member")
+    target = source_root / member["relative"] if member["relative"] else source_root
+    original = target.read_bytes()
+    if mode == "same-size":
+        replacement = (b"X" if original[:1] != b"X" else b"Y") + original[1:]
+    elif mode == "size":
+        replacement = original + b"-changed"
+    else:
+        raise BackupError("test-mutation-invalid", f"unknown mutation mode: {mode}")
+    target.write_bytes(replacement)
+
+
+def capture_sqlite(source: Path, destination: Path, source_id: str) -> tuple[int, str]:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    source_db = sqlite3.connect(f"file:{source}?mode=ro", uri=True)
+    destination_db = sqlite3.connect(destination)
+    try:
+        source_db.backup(destination_db)
+    finally:
+        destination_db.close()
+        source_db.close()
+    if os.environ.get("LDM_BACKUP_TEST_SQLITE_FAIL_ID") == source_id:
+        destination.write_bytes(b"not-a-database")
+    try:
+        check_db = sqlite3.connect(f"file:{destination}?mode=ro", uri=True)
+        try:
+            result = check_db.execute("PRAGMA quick_check").fetchone()[0]
+        finally:
+            check_db.close()
+    except sqlite3.Error as exc:
+        raise BackupError("sqlite-validation-failed", f"quick_check failed for source id {source_id}") from exc
+    if result != "ok":
+        raise BackupError("sqlite-validation-failed", f"quick_check failed for source id {source_id}")
+    return destination.stat().st_size, sha256_file(destination)
+
+
+def source_metadata_projection_bytes(item: dict[str, Any], plan: dict[str, Any]) -> int:
+    fragment = planned_manifest(
+        plan["snapshot_id"],
+        plan["manifest_template"]["started_at"],
+        plan["policy"],
+        [item],
+    )
+    empty = planned_manifest(
+        plan["snapshot_id"],
+        plan["manifest_template"]["started_at"],
+        plan["policy"],
+        [],
+    )
+    return len(json_bytes(fragment)) - len(json_bytes(empty))
+
+
+def projected_metadata_bytes(
+    plan: dict[str, Any],
+    refreshed: dict[str, dict[str, Any]],
+    generated_evidence: list[dict[str, Any]],
+) -> int:
+    metadata_bytes = plan["initial_estimated_metadata_bytes"]
+    original = {item["id"]: item for item in plan["sources"]}
+    for source_id, observation in refreshed.items():
+        before = source_metadata_projection_bytes(original[source_id], plan)
+        after = source_metadata_projection_bytes(observation, plan)
+        metadata_bytes += max(0, after - before)
+    planned_evidence = {
+        item["source_id"]: item
+        for item in plan["manifest_template"]["manifest_evidence"]
+    }
+    for item in generated_evidence:
+        before = planned_evidence.get(item["source_id"])
+        before_bytes = len(json_bytes(before)) if before is not None else 0
+        metadata_bytes += max(0, len(json_bytes(item)) - before_bytes)
+    return metadata_bytes
+
+
+def refresh_remaining_capture_sources(
+    plan: dict[str, Any],
+    start_index: int,
+    roots: Roots,
+) -> dict[str, dict[str, Any]]:
+    refreshed: dict[str, dict[str, Any]] = {}
+    for item in plan["sources"][start_index:]:
+        if item["action"] != "capture" or item["status"] != "planned":
+            continue
+        observation = make_source_plan(
+            item["source_definition"],
+            roots,
+            hash_content=False,
+        )
+        if observation["status"] != "planned":
+            raise BackupError("source-changed-during-run", f"source became unavailable before capture: {item['id']}")
+        refreshed[item["id"]] = observation
+    return refreshed
+
+
+def revalidate_capture_reserve(
+    plan: dict[str, Any],
+    roots: Roots,
+    written: int,
+    refreshed: dict[str, dict[str, Any]],
+    generated_evidence: list[dict[str, Any]],
+) -> None:
+    remaining_payload = sum(item["estimated_bytes"] for item in refreshed.values())
+    metadata_bytes = projected_metadata_bytes(plan, refreshed, generated_evidence)
+    _, current_available = disk_values(roots.backup)
+    available_after_staged = min(current_available, plan["disk_available_bytes"] - written)
+    reserve_after = available_after_staged - remaining_payload - metadata_bytes
+    updated_payload = written + remaining_payload
+    plan["estimated_payload_bytes"] = updated_payload
+    plan["estimated_metadata_bytes"] = metadata_bytes
+    plan["estimated_new_bytes"] = updated_payload + metadata_bytes
+    plan["reserve_after_bytes"] = reserve_after
+    plan["capture_time_available_bytes"] = available_after_staged
+    if reserve_after < plan["required_reserve_bytes"]:
+        plan["preflight_allowed"] = False
+        if "capture-reserve-gate" not in plan["blocking_reasons"]:
+            plan["blocking_reasons"].append("capture-reserve-gate")
+        raise BackupError(
+            "capture-reserve-gate",
+            "updated capture estimate would cross the required disk reserve",
+        )
+
+
+def revalidate_final_metadata_reserve(
+    plan: dict[str, Any],
+    roots: Roots,
+    payload_written: int,
+    manifest: dict[str, Any],
+) -> None:
+    metadata_bytes = len(json_bytes(manifest)) + len(json_bytes(completion_value(plan["snapshot_id"])))
+    _, current_available = disk_values(roots.backup)
+    available_after_staged = min(current_available, plan["disk_available_bytes"] - payload_written)
+    reserve_after = available_after_staged - metadata_bytes
+    plan["estimated_payload_bytes"] = payload_written
+    plan["estimated_metadata_bytes"] = metadata_bytes
+    plan["estimated_new_bytes"] = payload_written + metadata_bytes
+    plan["reserve_after_bytes"] = reserve_after
+    plan["capture_time_available_bytes"] = available_after_staged
+    if reserve_after < plan["required_reserve_bytes"]:
+        plan["preflight_allowed"] = False
+        if "capture-reserve-gate" not in plan["blocking_reasons"]:
+            plan["blocking_reasons"].append("capture-reserve-gate")
+        raise BackupError(
+            "capture-reserve-gate",
+            "final manifest metadata would cross the required disk reserve",
+        )
+
+
+def capture(
+    plan: dict[str, Any],
+    staging: Path,
+    roots: Roots,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]], int]:
+    records: list[dict[str, Any]] = []
+    observations: list[dict[str, Any]] = []
+    evidence: list[dict[str, Any]] = []
+    written = 0
+    fail_after = int(os.environ.get("LDM_BACKUP_TEST_FAIL_AFTER_BYTES", "-1"))
+    crash_after = int(os.environ.get("LDM_BACKUP_TEST_CRASH_AFTER_FILES", "-1"))
+    captured_files = 0
+    for index, item in enumerate(plan["sources"]):
+        if item["action"] == "manifest" and item["status"] == "planned":
+            if os.environ.get("LDM_BACKUP_TEST_MANIFEST_FAIL_ID") == item["id"]:
+                raise BackupError("manifest-evidence-failed", f"manifest generator failed: {item['id']}")
+            observation = make_source_plan(item["source_definition"], roots)
+            if observation["status"] != "planned":
+                raise BackupError("manifest-evidence-failed", f"manifest evidence unavailable: {item['id']}")
+            record = manifest_evidence(observation)
+            record["generated_at"] = utc_now()
+            evidence.append(record)
+            refreshed = refresh_remaining_capture_sources(plan, index + 1, roots)
+            revalidate_capture_reserve(plan, roots, written, refreshed, evidence)
+            continue
+        if item["action"] != "capture" or item["status"] != "planned":
+            continue
+        apply_test_source_mutation(item, "before-capture")
+        refreshed = refresh_remaining_capture_sources(plan, index, roots)
+        capture_observation = make_source_plan(item["source_definition"], roots)
+        if capture_observation["status"] != "planned":
+            raise BackupError("source-changed-during-run", f"source became unavailable before capture: {item['id']}")
+        refreshed[item["id"]] = capture_observation
+        revalidate_capture_reserve(plan, roots, written, refreshed, evidence)
+        plan_changed = members_changed(item["members"], capture_observation["members"])
+        observations.append({
+            "source_id": item["id"],
+            "consistency_contract": (
+                "sqlite-backup-api-transaction-snapshot"
+                if item["type"] == "sqlite"
+                else "capture-time-stable"
+            ),
+            "planned_member_count": len(item["members"]),
+            "planned_payload_bytes": sum(member["size"] for member in item["members"]),
+            "planned_inventory_sha256": members_fingerprint(item["members"]),
+            "capture_member_count": len(capture_observation["members"]),
+            "capture_payload_bytes": sum(member["size"] for member in capture_observation["members"]),
+            "capture_inventory_sha256": members_fingerprint(capture_observation["members"]),
+            "changed_since_plan": None if item["type"] == "sqlite" else plan_changed,
+            "metadata_changed_since_plan": plan_changed,
+        })
+        source_root = Path(item["source_path"])
+        destination_root = staging / item["destination"]
+        if item["type"] == "sqlite":
+            capture_info = source_root.lstat()
+            size, checksum = capture_sqlite(source_root, destination_root, item["id"])
+            member = item["members"][0]
+            records.append({
+                "source_id": item["id"], "source_path": item["source_path"],
+                "destination": item["destination"], "type": "sqlite", "size": size,
+                "mtime_ns": capture_info.st_mtime_ns, "checksum_sha256": checksum,
+                "planned_size": member["size"], "planned_mtime_ns": member["mtime_ns"],
+                "planned_checksum_sha256": None, "changed_since_plan": None,
+                "consistency_contract": "sqlite-backup-api-transaction-snapshot",
+            })
+            written += size
+            captured_files += 1
+        else:
+            for member in capture_observation["members"]:
+                destination = destination_root
+                if member["relative"]:
+                    destination = destination_root / member["relative"]
+                size = copy_member(source_root, destination_root, member)
+                if member["kind"] == "directory":
+                    checksum = sha256_text("")
+                elif member["kind"] == "symlink":
+                    checksum = sha256_text(os.readlink(destination))
+                else:
+                    checksum = sha256_file(destination)
+                if size != member["size"] or checksum != member["checksum"]:
+                    raise BackupError("source-capture-mismatch", f"captured bytes do not match source observation: {item['id']}")
+                relative_destination = item["destination"]
+                if member["relative"]:
+                    relative_destination = f"{relative_destination}/{member['relative']}"
+                records.append({
+                    "source_id": item["id"], "source_path": item["source_path"],
+                    "destination": relative_destination, "type": member["kind"], "size": size,
+                    "mtime_ns": member["mtime_ns"], "checksum_sha256": checksum,
+                    "planned_size": member_map(item["members"]).get(member_key(member), {}).get("size"),
+                    "planned_mtime_ns": member_map(item["members"]).get(member_key(member), {}).get("mtime_ns"),
+                    "planned_checksum_sha256": member_map(item["members"]).get(member_key(member), {}).get("checksum"),
+                    "changed_since_plan": plan_changed,
+                    "consistency_contract": "capture-time-stable",
+                })
+                written += size
+                captured_files += 1
+                if fail_after >= 0 and written >= fail_after:
+                    raise SimulatedDiskFull()
+                if crash_after >= 0 and captured_files >= crash_after:
+                    os._exit(88)
+            apply_test_source_mutation(capture_observation, "during-capture")
+            final_observation = make_source_plan(item["source_definition"], roots)
+            if final_observation["status"] != "planned" or members_changed(capture_observation["members"], final_observation["members"]):
+                raise BackupError("source-changed-during-capture", f"source changed during capture: {item['id']}")
+    return records, observations, evidence, written
+
+
+def read_evidence_status(state_dir: Path) -> str:
+    marker = state_dir / "containment.json"
+    try:
+        value = json.loads(marker.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return "unknown"
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BackupError("containment-marker-invalid", f"cannot read containment marker: {exc}") from exc
+    evidence_status = value.get("evidence_status")
+    if evidence_status not in VALID_EVIDENCE_STATUS:
+        raise BackupError("state-enum-invalid", "containment marker has invalid evidence_status")
+    return evidence_status
+
+
+def validate_manifest(manifest: dict[str, Any], staging: Path, plan: dict[str, Any]) -> None:
+    if manifest.get("terminal_result") != "success":
+        raise BackupError("manifest-invalid", "manifest result is not success")
+    expected_ids = {item["id"] for item in plan["sources"] if item["required"] and item["action"] == "capture"}
+    actual_ids = {item["source_id"] for item in manifest["sources"]}
+    if expected_ids - actual_ids:
+        raise BackupError("manifest-required-source-missing", "manifest is missing a required source")
+    expected_evidence_ids = {
+        item["id"]
+        for item in plan["sources"]
+        if item["required"] and item["action"] == "manifest"
+    }
+    evidence = manifest.get("manifest_evidence")
+    if not isinstance(evidence, list):
+        raise BackupError("manifest-evidence-invalid", "manifest evidence must be a list")
+    actual_evidence_ids = {item.get("source_id") for item in evidence}
+    if expected_evidence_ids - actual_evidence_ids:
+        raise BackupError("manifest-required-evidence-missing", "manifest is missing required evidence")
+    for item in evidence:
+        members = item.get("members")
+        if (
+            item.get("status") != "valid"
+            or item.get("generator") != "path-inventory"
+            or not isinstance(members, list)
+            or item.get("member_count") != len(members)
+            or item.get("logical_bytes") != sum(member.get("size", -1) for member in members)
+            or item.get("inventory_sha256") != members_fingerprint(members)
+        ):
+            raise BackupError("manifest-evidence-invalid", f"invalid manifest evidence: {item.get('source_id')}")
+    for record in manifest["sources"]:
+        destination = staging / record["destination"]
+        if not destination.exists() and not destination.is_symlink():
+            raise BackupError("manifest-file-missing", "manifest destination is missing")
+        if record["type"] == "directory":
+            if not destination.is_dir():
+                raise BackupError("manifest-file-missing", "manifest directory is missing")
+            checksum = sha256_text("")
+        elif destination.is_symlink():
+            checksum = sha256_text(os.readlink(destination))
+        else:
+            checksum = sha256_file(destination)
+        if checksum != record["checksum_sha256"]:
+            raise BackupError("manifest-checksum-mismatch", "manifest checksum mismatch")
+
+
+def verified_snapshot(path: Path) -> bool:
+    marker = path / "completion.json"
+    manifest = path / "manifest.json"
+    if not path.is_dir() or not marker.is_file() or not manifest.is_file():
+        return False
+    try:
+        marker_value = json.loads(marker.read_text(encoding="utf-8"))
+        manifest_value = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return marker_value.get("status") == "complete" and manifest_value.get("terminal_result") == "success" and marker_value.get("manifest_sha256") == sha256_file(manifest)
+
+
+def rotate(root: Path, keep: int) -> list[str]:
+    eligible = sorted(
+        path for path in root.iterdir()
+        if path.is_dir() and not path.name.startswith(".in-progress-") and verified_snapshot(path) and not (path / ".pinned").exists()
+    ) if root.exists() else []
+    remove_count = max(0, len(eligible) - keep)
+    removed = []
+    for path in eligible[:remove_count]:
+        shutil.rmtree(path)
+        removed.append(path.name)
+    return removed
+
+
+def result_value(run_id: str, status: str, code: str | None, message: str | None, plan: dict[str, Any] | None) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "snapshot_id": run_id,
+        "status": status,
+        "failure_code": code,
+        "message": message,
+        "finished_at": utc_now(),
+        "estimated_new_bytes": plan.get("estimated_new_bytes") if plan else None,
+        "estimated_payload_bytes": plan.get("estimated_payload_bytes") if plan else None,
+        "estimated_metadata_bytes": plan.get("estimated_metadata_bytes") if plan else None,
+        "required_reserve_bytes": plan.get("required_reserve_bytes") if plan else None,
+        "reserve_after_bytes": plan.get("reserve_after_bytes") if plan else None,
+        "preflight_allowed": plan.get("preflight_allowed") if plan else False,
+        "tier_results": {"internal": status, "vault": "not-in-slice", "icloud": "not-in-slice"},
+    }
+
+
+def run_backup(policy: dict[str, Any], roots: Roots, keep: int) -> int:
+    run_id = snapshot_id()
+    started_at = utc_now()
+    lock_fd: int | None = None
+    plan: dict[str, Any] | None = None
+    staging = roots.backup / f".in-progress-{run_id}"
+    final = roots.backup / run_id
+    try:
+        lock_fd = acquire_lock(roots.lock, run_id)
+        plan = build_plan(policy, roots, run_id, started_at)
+        schedule = {
+            "schema_version": 1,
+            "schedule_id": SCHEDULE_ID,
+            "timezone": "America/Los_Angeles",
+            "expected_slot": "03:00",
+            "containment_status": os.environ.get("LDM_BACKUP_CONTAINMENT_STATUS", "unknown"),
+            "evidence_status": read_evidence_status(roots.state),
+            "next_due_time": None,
+        }
+        write_atomic(roots.state / "schedule.json", schedule)
+        write_atomic(roots.state / "attempt.json", {
+            "schema_version": 1, "snapshot_id": run_id, "slot_id": run_id,
+            "start_time": started_at, "pid": os.getpid(), "tool_version": TOOL_VERSION,
+            "preflight": {key: plan[key] for key in (
+                "estimated_new_bytes", "disk_total_bytes", "disk_available_bytes",
+                "required_reserve_bytes", "reserve_after_bytes", "preflight_allowed",
+            )},
+        })
+        if not plan["preflight_allowed"]:
+            raise BackupError("preflight-failed", ",".join(plan["blocking_reasons"]) or "preflight failed")
+        if staging.exists() or final.exists():
+            raise BackupError("snapshot-collision", "snapshot path already exists")
+        roots.backup.mkdir(parents=True, exist_ok=True)
+        staging.mkdir(mode=0o700)
+        records, observations, evidence, payload_written = capture(plan, staging, roots)
+        drop_evidence_id = os.environ.get("LDM_BACKUP_TEST_DROP_MANIFEST_EVIDENCE_ID")
+        if drop_evidence_id:
+            evidence = [item for item in evidence if item["source_id"] != drop_evidence_id]
+        manifest = plan["manifest_template"]
+        manifest["sources"] = records
+        manifest["source_observations"] = observations
+        manifest["manifest_evidence"] = evidence
+        manifest["planned_payload_bytes"] = plan["initial_estimated_payload_bytes"]
+        manifest["captured_payload_bytes"] = payload_written
+        manifest["completed_at"] = utc_now()
+        revalidate_final_metadata_reserve(plan, roots, payload_written, manifest)
+        validate_manifest(manifest, staging, plan)
+        write_atomic(staging / "manifest.json", manifest)
+        if os.environ.get("LDM_BACKUP_TEST_FAIL_BEFORE_COMPLETION") == "1":
+            raise BackupError("completion-gate-failed", "simulated failure before completion marker")
+        marker = completion_value(run_id)
+        marker["manifest_sha256"] = sha256_file(staging / "manifest.json")
+        marker["completed_at"] = utc_now()
+        write_atomic(staging / "completion.json", marker)
+        if not verified_snapshot(staging):
+            raise BackupError("completion-validation-failed", "completion proof failed before promotion")
+        os.replace(staging, final)
+        success = result_value(run_id, "success", None, None, plan)
+        success["snapshot_path"] = str(final)
+        success["manifest_sha256"] = marker["manifest_sha256"]
+        write_atomic(roots.state / "result.json", success)
+        write_atomic(roots.state / "success-local.json", success)
+        removed = rotate(roots.backup, keep)
+        print("=== Backup complete ===")
+        print(f"Location: {final}")
+        print(f"Estimated and captured payload bytes: {payload_written}")
+        if removed:
+            print(f"Rotated verified snapshots: {', '.join(removed)}")
+        return 0
+    except BackupError as exc:
+        if lock_fd is not None:
+            try:
+                write_atomic(roots.state / "result.json", result_value(run_id, "failure", exc.code, str(exc), plan))
+            except OSError:
+                pass
+        print(f"Backup failed [{exc.code}]: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        code = "disk-full-during-capture" if exc.errno == errno.ENOSPC else "io-failure"
+        try:
+            write_atomic(roots.state / "result.json", result_value(run_id, "failure", code, str(exc), plan))
+        except OSError:
+            pass
+        print(f"Backup failed [{code}]: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        release_lock(roots.lock, lock_fd)
+
+
+def verify_snapshot(path: Path) -> int:
+    if verified_snapshot(path):
+        print("Snapshot verified complete")
+        return 0
+    print("Snapshot is missing valid completion proof", file=sys.stderr)
+    return 1
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="LDM OS backup engine")
+    parser.add_argument("--policy", type=Path)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--keep", type=int, default=None)
+    parser.add_argument("--include-secrets", action="store_true")
+    parser.add_argument("--verify-snapshot", type=Path)
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv or sys.argv[1:])
+    if args.verify_snapshot:
+        return verify_snapshot(args.verify_snapshot)
+    try:
+        roots = resolve_roots()
+        fixture = prove_fixture_isolation(roots)
+        policy_path = args.policy or Path(__file__).with_name("ldm-backup-policy.json")
+        policy = load_policy(policy_path)
+        prove_policy_fixture_isolation(policy, roots, fixture)
+        if args.include_secrets:
+            raise BackupError("encryption-not-implemented", "--include-secrets is blocked until artifact encryption ships")
+        if args.dry_run:
+            run_id = snapshot_id()
+            started_at = utc_now()
+            plan = build_plan(policy, roots, run_id, started_at)
+            plan["dry_run"] = True
+            print_plan(plan, args.json)
+            return 0 if plan["preflight_allowed"] else 1
+        config = load_config(roots.ldm)
+        keep = args.keep if args.keep is not None else int(config.get("backup", {}).get("keep", 7))
+        if keep < 1:
+            raise BackupError("keep-invalid", "keep must be one or greater")
+        return run_backup(policy, roots, keep)
+    except BackupError as exc:
+        print(f"Backup failed [{exc.code}]: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())