@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/remote-broker/retained_cleanup.py

@@ -0,0 +1,550 @@
+"""Confirmed empty-directory maintenance; never disposes retained objects."""
+
+import argparse
+import contextlib
+import ctypes
+import errno
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from cutover import (  # noqa: E402
+    Authority,
+    FENCE,
+    Lease,
+    MAX_TOTAL,
+    Receipt,
+    UUID,
+    canonical,
+    digest,
+    directory,
+    entries,
+    json_data,
+    make_directory,
+    publish,
+    read_file,
+    sync_directory,
+)
+from retained import (  # noqa: E402
+    FLAGS,
+    Manifest as RecoveryManifest,
+    locked,
+    observe,
+    parent,
+    physical,
+    private,
+    relative,
+    restored_record,
+    same_object,
+    valid_digest,
+)
+
+L = logging.getLogger(__name__)
+
+
+class Manifest(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    version: Literal[1]
+    clients_stopped: bool
+    authority: Authority
+    configured_staging_directory: str | None = None
+    receipt_id: str = Field(pattern=UUID.pattern)
+    recovery_digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+def archive_for(state: Path, receipt_id: str) -> Path:
+    return state / "retained-directory-cleanup" / receipt_id
+
+
+def record(plan: dict[str, Any], confirmation: str) -> dict[str, Any]:
+    return {
+        "version": 1,
+        "digest": confirmation,
+        "receipt_id": plan["manifest"]["receipt_id"],
+        "decision": "remove_reviewed_empty_operation_directory",
+        "directory_identity": plan["directory_identity"],
+        "recovery_digest": plan["manifest"]["recovery_digest"],
+        "original_receipt_sha256": plan["original_receipt_sha256"],
+        "current_receipt_sha256": plan["files"][
+            "receipts/" + plan["manifest"]["receipt_id"] + ".json"
+        ],
+        "deleted_retained_object": False,
+        "quota_reclaimed": False,
+        "earlier_mutation_status": plan["earlier_mutation_status"],
+    }
+
+
+def evidence(manifest: Manifest, reference: Path) -> dict[str, Any]:
+    """Read bounded original/current evidence, independently of directory absence."""
+    state = directory(manifest.authority.state_directory)
+    staging = directory(manifest.authority.staging_directory)
+    private(state)
+    private(staging)
+    worker = read_file(reference)
+    if (
+        read_file(Path(manifest.authority.worker_file)) != worker
+        or b"os.path.lexists(os.path.join(control, 'cutover-fence.json'))" not in worker
+    ):
+        raise ValueError("Matching reviewed fence-capable worker is required")
+    archive = directory(str(state / "retained-recovery" / manifest.recovery_digest))
+    files = {
+        "recovery/" + name: read_file(archive / name)
+        for name in [
+            "plan.json",
+            "original-receipt.json",
+            "restored.json",
+            "released.json",
+        ]
+    }
+    recovery = json_data(files["recovery/plan.json"])
+    if digest(canonical(recovery)) != manifest.recovery_digest:
+        raise ValueError("Recovery plan digest changed")
+    original_manifest = RecoveryManifest.model_validate(recovery["manifest"])
+    if (
+        original_manifest.authority != manifest.authority
+        or original_manifest.receipt_id != manifest.receipt_id
+        or original_manifest.configured_staging_directory
+        != manifest.configured_staging_directory
+    ):
+        raise ValueError("Cleanup lacks exact original recovery binding")
+    original = files["recovery/original-receipt.json"]
+    if (
+        digest(original)
+        != recovery["files"]["receipts/" + manifest.receipt_id + ".json"]
+    ):
+        raise ValueError("Original recovery receipt changed")
+    if json_data(files["recovery/restored.json"]) != restored_record(
+        recovery, manifest.recovery_digest
+    ):
+        raise ValueError("Matching durable restoration receipt is required")
+    released = json_data(files["recovery/released.json"])
+    if released != {
+        "version": 1,
+        "digest": manifest.recovery_digest,
+        "review_token": valid_digest(released.get("review_token")),
+        "state": "released",
+    }:
+        raise ValueError("Matching reviewed recovery release is required")
+    bindings = []
+    resources = {r.id: r for r in manifest.authority.resources}
+    if len(resources) != len(manifest.authority.resources):
+        raise ValueError("Resource identities must be unique")
+    for resource in manifest.authority.resources:
+        root = directory(resource.root_directory)
+        if any(
+            root.is_relative_to(p) or p.is_relative_to(root) for p in [state, staging]
+        ):
+            raise ValueError("Resource root overlaps private operator evidence")
+        bindings.append(
+            {**resource.model_dump(), "root_identity": physical(root.stat())}
+        )
+    bindings.sort(key=lambda item: item["id"])
+    if (
+        bindings != recovery["bindings"]
+        or physical(state.stat()) != recovery["selected"]["state_identity"]
+        or physical(staging.stat()) != recovery["selected"]["staging_identity"]
+        or digest(worker) != recovery["worker_sha256"]
+    ):
+        raise ValueError("Recovery root, private parent or worker identity changed")
+    files["leases.json"] = read_file(state / "leases.json")
+    leases = json_data(files["leases.json"])
+    if not isinstance(leases, dict):
+        raise ValueError("Invalid lease registry evidence")
+    identities = {item["configured_root"]: item["root_identity"] for item in bindings}
+    blockers = [] if manifest.clients_stopped else ["Stop all clients before cleanup"]
+    if sum(map(len, files.values())) > MAX_TOTAL:
+        raise ValueError("Cleanup evidence exceeds the aggregate byte bound")
+    for key, value in leases.items():
+        lease = Lease.model_validate(value)
+        if (
+            key != digest(lease.root.encode())
+            or identities.get(lease.root) != lease.identity
+        ):
+            raise ValueError("Lease lacks its original resource identity")
+        if lease.owner_id is not None:
+            blockers.append("Stop every recorded lease before cleanup")
+    receipts = {}
+    for path in entries(directory(str(state / "receipts"))):
+        raw = read_file(path)
+        files["receipts/" + path.name] = raw
+        if sum(map(len, files.values())) > MAX_TOTAL:
+            raise ValueError("Cleanup evidence exceeds the aggregate byte bound")
+        receipt = Receipt.model_validate_json(raw)
+        mapped = resources.get(receipt.resource_id)
+        if (
+            mapped is None
+            or receipt.id != path.stem
+            or receipt.configured_root != mapped.configured_root
+            or receipt.endpoint != mapped.endpoint
+            or receipt.root_identity != identities[mapped.configured_root]
+            or receipt.target.get("path")
+            != os.path.join(mapped.configured_root, relative(receipt.requested_path))
+        ):
+            raise ValueError("Receipt lacks its original resource binding")
+        receipts[receipt.id] = json_data(raw)
+        if not receipt.admission_resolved:
+            blockers.append(
+                "Explicit current-state review is required for receipt " + receipt.id
+            )
+    if sum(map(len, files.values())) > MAX_TOTAL:
+        raise ValueError("Cleanup evidence exceeds the aggregate byte bound")
+    receipt = receipts[manifest.receipt_id]
+    original_receipt = json_data(original)
+    for name in [
+        "version",
+        "id",
+        "operation",
+        "owner_id",
+        "resource_id",
+        "endpoint",
+        "configured_root",
+        "root_identity",
+        "requested_path",
+        "tool_call_id",
+        "target",
+        "deletion_staging",
+    ]:
+        if receipt[name] != original_receipt[name]:
+            raise ValueError("Current receipt changed original mutation identity")
+    stage = receipt["deletion_staging"]
+    configured = manifest.configured_staging_directory or str(staging)
+    if (
+        stage["path"] != os.path.join(configured, manifest.receipt_id, "target")
+        or stage["directory_identity"] != recovery["selected"]["directory_identity"]
+    ):
+        raise ValueError("Operation directory lacks its exact receipt identity")
+    destination = recovery["selected"]["destination"]
+    root = Path(resources[receipt["resource_id"]].root_directory)
+    with parent(root, original_manifest.destination, receipt["root_identity"]) as (
+        descriptor,
+        leaf,
+    ):
+        observed = observe(descriptor, leaf)
+        if (
+            physical(os.fstat(descriptor))
+            != recovery["selected"]["destination_parent_identity"]
+        ):
+            raise ValueError("Restored destination parent changed")
+    if not same_object(observed, recovery["selected"]["source"]):
+        blockers.append("Restored object changed; review current recovery state")
+    return {
+        "version": 1,
+        "manifest": manifest.model_dump(),
+        "bindings": bindings,
+        "worker_sha256": digest(worker),
+        "state_identity": physical(state.stat()),
+        "staging_identity": physical(staging.stat()),
+        "directory_identity": stage["directory_identity"],
+        "original_receipt_sha256": digest(original),
+        "earlier_mutation_status": receipt["status"],
+        "files": {name: digest(raw) for name, raw in sorted(files.items())},
+        "restored_destination": destination,
+        "restored_object": observed,
+        "blockers": blockers,
+    }
+
+
+def completed_evidence(state: Path, staging: Path, receipt: dict[str, Any]) -> bool:
+    """Validate durable historical cleanup without interpreting absence as an effect."""
+    archive = archive_for(state, receipt["id"])
+    if not os.path.lexists(archive / "completed.json"):
+        return False
+    directory(str(archive))
+    private(archive)
+    plan = json_data(read_file(archive / "plan.json"))
+    confirmation = digest(canonical(plan))
+    manifest = Manifest.model_validate(plan["manifest"])
+    if (
+        manifest.receipt_id != receipt["id"]
+        or directory(manifest.authority.state_directory) != state
+        or directory(manifest.authority.staging_directory) != staging
+        or physical(state.stat()) != plan["state_identity"]
+        or physical(staging.stat()) != plan["staging_identity"]
+        or plan["directory_identity"]
+        != receipt["deletion_staging"]["directory_identity"]
+        or digest(read_file(state / "receipts" / (receipt["id"] + ".json")))
+        != plan["files"]["receipts/" + receipt["id"] + ".json"]
+        or json_data(read_file(archive / "completed.json"))
+        != record(plan, confirmation)
+    ):
+        raise ValueError("Completed directory cleanup evidence changed")
+    recovery = state / "retained-recovery" / manifest.recovery_digest
+    for name in [
+        "plan.json",
+        "original-receipt.json",
+        "restored.json",
+        "released.json",
+    ]:
+        if digest(read_file(recovery / name)) != plan["files"]["recovery/" + name]:
+            raise ValueError("Completed cleanup recovery archive changed")
+    for binding in plan["bindings"]:
+        if (
+            physical(directory(binding["root_directory"]).stat())
+            != binding["root_identity"]
+        ):
+            raise ValueError("Completed cleanup resource root changed")
+    return True
+
+
+def rename_directory(descriptor: int, source: str, destination: str) -> None:
+    library = ctypes.CDLL(None, use_errno=True)
+    if sys.platform == "linux":
+        function, flag = library.renameat2, 1
+    elif sys.platform == "darwin":
+        function, flag = library.renameatx_np, 4
+    else:
+        raise OSError(errno.ENOTSUP, "Cleanup requires atomic no-replace rename")
+    function.argtypes = [
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_uint,
+    ]
+    function.restype = ctypes.c_int
+    if function(
+        descriptor, os.fsencode(source), descriptor, os.fsencode(destination), flag
+    ):
+        error = ctypes.get_errno()
+        raise OSError(error, "Cleanup capture refused: " + os.strerror(error))
+
+
+def empty_directory(descriptor: int, name: str, identity: list[int]) -> bool:
+    try:
+        child = os.open(name, FLAGS, dir_fd=descriptor)
+    except FileNotFoundError:
+        return False
+    try:
+        info = os.fstat(child)
+        if (
+            physical(info) != identity
+            or info.st_uid != os.geteuid()
+            or info.st_mode & 0o077
+        ):
+            raise ValueError(
+                "Empty operation directory identity or private ownership changed"
+            )
+        if os.listdir(child):
+            raise ValueError(
+                "Operation directory is nonempty; no retained objects may be removed"
+            )
+        return True
+    finally:
+        os.close(child)
+
+
+def execute(
+    operation: str, manifest: Manifest, reference: Path, confirmation: str | None
+) -> dict[str, Any]:
+    with locked(manifest):
+        state = directory(manifest.authority.state_directory)
+        staging = directory(manifest.authority.staging_directory)
+        archive = archive_for(state, manifest.receipt_id)
+        if os.path.lexists(archive):
+            directory(str(archive))
+            private(archive)
+        tomb = ".cleanup-" + manifest.receipt_id
+        saved = os.path.lexists(archive / "plan.json")
+        if saved:
+            plan = json_data(read_file(archive / "plan.json"))
+            if plan["manifest"] != manifest.model_dump():
+                raise ValueError(
+                    "Existing cleanup belongs to another manifest; preserve evidence"
+                )
+            selected_digest = digest(canonical(plan))
+            receipt = json_data(
+                read_file(state / "receipts" / (manifest.receipt_id + ".json"))
+            )
+            if completed_evidence(state, staging, receipt):
+                if (
+                    read_file(Path(manifest.authority.worker_file))
+                    != read_file(reference)
+                    or digest(read_file(reference)) != plan["worker_sha256"]
+                ):
+                    raise ValueError("Completed cleanup worker binding changed")
+                if os.path.lexists(staging / manifest.receipt_id) or os.path.lexists(
+                    staging / tomb
+                ):
+                    raise ValueError(
+                        "Completed cleanup namespace was repopulated; "
+                        "preserve new evidence"
+                    )
+                if operation == "cleanup":
+                    if valid_digest(confirmation) != selected_digest:
+                        raise ValueError(
+                            "Cleanup requires its exact original confirmation"
+                        )
+                    finish_fence(state, plan, selected_digest, archive)
+                return {
+                    "state": "completed",
+                    "digest": selected_digest,
+                    "archive": str(archive),
+                    **record(plan, selected_digest),
+                }
+            current = evidence(manifest, reference)
+            if current != plan:
+                raise ValueError(
+                    "Cleanup evidence changed; preserve the authority fence"
+                )
+        else:
+            plan = evidence(manifest, reference)
+            selected_digest = digest(canonical(plan))
+        marker = canonical(
+            {
+                "version": 1,
+                "kind": "retained-directory-cleanup",
+                "digest": selected_digest,
+            }
+        )
+        with contextlib.ExitStack() as handles:
+            descriptor = os.open(staging, FLAGS)
+            handles.callback(os.close, descriptor)
+            if physical(os.fstat(descriptor)) != plan["staging_identity"]:
+                raise ValueError("Private staging parent changed")
+            blockers = list(plan["blockers"])
+            try:
+                present = empty_directory(
+                    descriptor, manifest.receipt_id, plan["directory_identity"]
+                )
+                captured = empty_directory(descriptor, tomb, plan["directory_identity"])
+                if present and captured:
+                    blockers.append("Conflicting cleanup capture namespace")
+                if captured and not saved:
+                    blockers.append("Cleanup capture lacks its durable original plan")
+                if (
+                    not present
+                    and not captured
+                    and not os.path.lexists(archive / "removing.json")
+                ):
+                    blockers.append("Directory absent without durable removal intent")
+                if (
+                    not present
+                    and not captured
+                    and os.path.lexists(archive / "removing.json")
+                ):
+                    if not saved or json_data(
+                        read_file(archive / "removing.json")
+                    ) != record(plan, selected_digest):
+                        blockers.append(
+                            "Directory absence lacks exact durable removal intent"
+                        )
+            except (ValueError, OSError) as error:
+                blockers.append(str(error))
+                present = captured = False
+            if os.path.lexists(state / FENCE) and read_file(state / FENCE) != marker:
+                blockers.append("Authority has a conflicting operator fence")
+            preview = {
+                "ready": not blockers,
+                "digest": selected_digest,
+                "blockers": blockers,
+                "receipt_id": manifest.receipt_id,
+                "directory_identity": plan["directory_identity"],
+                "decision": "remove_reviewed_empty_operation_directory",
+                "quota_reclaimed": False,
+            }
+            if operation in ["preview", "status"]:
+                return {
+                    "state": "pending" if saved else "unprepared",
+                    "preview": preview,
+                }
+            if valid_digest(confirmation) != selected_digest:
+                raise ValueError(
+                    "Cleanup confirmation changed; review the current preview"
+                )
+            if blockers:
+                raise ValueError("Cleanup refused: " + "; ".join(blockers))
+            publish(state / FENCE, marker)
+            make_directory(archive)
+            publish(archive / "plan.json", canonical(plan))
+            if present:
+                rename_directory(descriptor, manifest.receipt_id, tomb)
+                os.fsync(descriptor)
+                captured = empty_directory(descriptor, tomb, plan["directory_identity"])
+            if captured:
+                publish(
+                    archive / "removing.json", canonical(record(plan, selected_digest))
+                )
+                # rmdir refuses a late entry; no recursive deletion is ever performed.
+                if not empty_directory(descriptor, tomb, plan["directory_identity"]):
+                    raise ValueError("Cleanup capture disappeared before removal")
+                os.rmdir(tomb, dir_fd=descriptor)
+            elif json_data(read_file(archive / "removing.json")) != record(
+                plan, selected_digest
+            ):
+                raise ValueError("Missing exact durable removal intent")
+            os.fsync(descriptor)
+            if (
+                physical(staging.stat()) != plan["staging_identity"]
+                or os.path.lexists(staging / manifest.receipt_id)
+                or os.path.lexists(staging / tomb)
+            ):
+                raise ValueError(
+                    "Cleanup namespace changed; preserve the authority fence"
+                )
+            publish(
+                archive / "completed.json", canonical(record(plan, selected_digest))
+            )
+        finish_fence(state, plan, selected_digest, archive)
+        return {
+            "state": "completed",
+            "archive": str(archive),
+            **record(plan, selected_digest),
+        }
+
+
+def finish_fence(
+    state: Path, plan: dict[str, Any], confirmation: str, archive: Path
+) -> None:
+    marker = canonical(
+        {"version": 1, "kind": "retained-directory-cleanup", "digest": confirmation}
+    )
+    if read_file(archive / "completed.json") != canonical(record(plan, confirmation)):
+        raise ValueError("Missing durable directory-cleanup completion")
+    # Settle visible completion publication and namespace effects after lost replies.
+    sync_directory(archive)
+    sync_directory(directory(plan["manifest"]["authority"]["staging_directory"]))
+    if os.path.lexists(state / FENCE):
+        if read_file(state / FENCE) != marker:
+            raise ValueError("Conflicting operator fence; preserve it")
+        os.unlink(state / FENCE)
+    sync_directory(state)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Separately confirm reviewed empty-directory cleanup"
+    )
+    parser.add_argument("operation", choices=["preview", "cleanup", "status"])
+    parser.add_argument("--manifest", required=True)
+    parser.add_argument("--worker-file")
+    parser.add_argument("--confirm")
+    args = parser.parse_args()
+    try:
+        manifest = Manifest.model_validate_json(read_file(Path(args.manifest)))
+        reference = (
+            Path(args.worker_file)
+            if args.worker_file
+            else Path(__file__).with_name("worker.py")
+        )
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    **execute(args.operation, manifest, reference, args.confirm),
+                },
+                allow_nan=False,
+            )
+        )
+    except (ValueError, OSError, KeyError) as error:
+        print(json.dumps({"ok": False, "error": str(error)}))
+        raise SystemExit(2) from error
+
+
+if __name__ == "__main__":
+    main()