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

package/dist/remote-broker/cutover.py

@@ -0,0 +1,761 @@
+"""Offline operator cutover. Archives evidence; never imports lease authority."""
+
+import argparse
+import contextlib
+import fcntl
+import hashlib
+import json
+import logging
+import os
+import re
+import stat
+import tempfile
+from pathlib import Path
+from typing import Any, Iterator, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+L = logging.getLogger(__name__)
+MAX_FILE = 8 * 1024 * 1024
+MAX_TOTAL = 64 * 1024 * 1024
+UUID = re.compile(r"^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$")
+FENCE = "cutover-fence.json"
+
+
+class Endpoint(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    host: str = Field(min_length=1, max_length=253)
+    user: str = Field(min_length=1, max_length=100)
+    port: int = Field(ge=1, le=65535)
+
+
+class Resource(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    id: str = Field(pattern=r"^[a-zA-Z0-9._:-]{1,100}$")
+    configured_root: str
+    root_directory: str
+    endpoint: Endpoint
+
+
+class StagingView(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+    configured_path: str = Field(min_length=1, max_length=4096)
+    directory: str = Field(min_length=1, max_length=4096)
+
+
+class PolicyResource(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+    id: str = Field(pattern=r"^[a-zA-Z0-9._:-]{1,100}$")
+    root: str = Field(min_length=1, max_length=4096)
+    endpoint: Endpoint
+    write_staging_directory: str | None = Field(default=None, max_length=4096)
+
+
+class ResourcePolicy(BaseModel):
+    # Unknown policy fields fail closed rather than becoming omitted locations.
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+    version: Literal[1]
+    resources: list[PolicyResource] = Field(min_length=1, max_length=100)
+    receipt_archive_index: bool = False
+    legacy_write_staging_directories: list[str] = Field(
+        default_factory=list, max_length=100
+    )
+
+
+class Authority(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    state_directory: str
+    staging_directory: str
+    worker_file: str
+    resources: list[Resource] = Field(min_length=1, max_length=100)
+    resource_policy_file: str | None = Field(default=None, max_length=4096)
+    legacy_default_staging_only: bool = False
+    staging_views: list[StagingView] = Field(default_factory=list, max_length=201)
+
+
+class Mapping(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    legacy: str
+    receiver: str
+
+
+class Manifest(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    version: Literal[1]
+    clients_stopped: bool
+    legacy: Authority
+    receiver: Authority
+    client_journals: list[str] = Field(min_length=1, max_length=100)
+    identity_mapping: list[Mapping] = Field(min_length=1, max_length=100)
+
+
+class Lease(BaseModel):
+    model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False)
+    root: str
+    identity: list[int] = Field(min_length=2, max_length=2)
+    ancestors: list[list[int]]
+    owner_id: str | None
+    generation: int = Field(ge=0)
+    expires_at: float | int
+
+
+class Receipt(BaseModel):
+    model_config = ConfigDict(extra="allow", strict=True)
+    version: Literal[1]
+    id: str
+    operation: Literal["write", "delete"]
+    status: Literal[
+        "pending", "verified", "failed", "unverified", "dry_run", "cancelled"
+    ]
+    admission_resolved: bool = False
+    owner_id: str
+    resource_id: str
+    endpoint: Endpoint
+    configured_root: str
+    root_identity: list[int] = Field(min_length=2, max_length=2)
+    requested_path: str
+    tool_call_id: str | None
+    target: dict[str, Any]
+
+
+class ClientRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    version: Literal[1]
+    id: str
+    status: Literal["pending", "resolved", "not_dispatched"]
+    operation: Literal["write", "delete"]
+    owner_id: str
+    resource_id: str
+    endpoint: Endpoint
+    target: str
+    requested_path: str
+    tool_call_id: str | None
+
+
+def canonical(data: Any) -> bytes:
+    return json.dumps(
+        data, sort_keys=True, separators=(",", ":"), allow_nan=False
+    ).encode()
+
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def normalized_manifest(manifest: Manifest) -> dict[str, Any]:
+    value: dict[str, Any] = manifest.model_dump()
+    value["identity_mapping"] = sorted(
+        value["identity_mapping"], key=lambda m: m["legacy"]
+    )
+    value["client_journals"] = sorted(value["client_journals"])
+    for side in ["legacy", "receiver"]:
+        value[side]["resources"] = sorted(
+            value[side]["resources"], key=lambda r: r["id"]
+        )
+        value[side]["staging_views"] = sorted(
+            value[side]["staging_views"], key=lambda view: view["configured_path"]
+        )
+    return value
+
+
+def directory(value: str) -> Path:
+    path = Path(value)
+    if not path.is_absolute() or str(path.resolve(strict=True)) != value:
+        raise ValueError(
+            "Evidence directories must be existing canonical absolute paths"
+        )
+    if not stat.S_ISDIR(path.lstat().st_mode):
+        raise ValueError("Evidence path is not a directory")
+    return path
+
+
+def read_file(path: Path) -> bytes:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    try:
+        if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+            raise ValueError("Evidence must be a regular file")
+        with os.fdopen(descriptor, "rb", closefd=False) as stream:
+            data = stream.read(MAX_FILE + 1)
+        if len(data) > MAX_FILE:
+            raise ValueError("Evidence file exceeds the byte bound")
+        return data
+    finally:
+        os.close(descriptor)
+
+
+def json_data(data: bytes) -> Any:
+    try:
+        return json.loads(data)
+    except (ValueError, UnicodeError) as error:
+        raise ValueError(
+            "Invalid JSON evidence; restore or reconcile it first"
+        ) from error
+
+
+def entries(path: Path) -> list[Path]:
+    result = sorted(path.iterdir())
+    if len(result) > 10000:
+        raise ValueError(
+            "Journal exceeds the entry bound; reviewed maintenance required"
+        )
+    for item in result:
+        if item.suffix != ".json" or UUID.fullmatch(item.stem) is None:
+            raise ValueError("Invalid journal evidence entry")
+    return result
+
+
+def sync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def publish(path: Path, data: bytes) -> None:
+    """No-overwrite, durable, resumable publication of exact immutable bytes."""
+    if os.path.lexists(path):
+        if read_file(path) != data:
+            raise ValueError(
+                "Existing cutover evidence conflicts; preserve it for recovery"
+            )
+        sync_directory(path.parent)
+        return
+    descriptor, temporary = tempfile.mkstemp(prefix=".cutover-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.link(temporary, path)
+        sync_directory(path.parent)
+    finally:
+        os.unlink(temporary)
+
+
+def make_directory(path: Path) -> None:
+    if not path.exists():
+        make_directory(path.parent)
+        path.mkdir(mode=0o700)
+        sync_directory(path.parent)
+    directory(str(path))
+    sync_directory(path)
+
+
+@contextlib.contextmanager
+def locked(manifest: Manifest) -> Iterator[None]:
+    """Use the same lock as every managed worker, in canonical path order."""
+    states = sorted(
+        {manifest.legacy.state_directory, manifest.receiver.state_directory}
+    )
+    if len(states) != 2 or any(
+        Path(a).is_relative_to(b) for a in states for b in states if a != b
+    ):
+        raise ValueError(
+            "Legacy and receiver state directories must be distinct and disjoint"
+        )
+    with contextlib.ExitStack() as stack:
+        for value in states:
+            state = directory(value)
+            descriptor = os.open(
+                state / "lock", os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK
+            )
+            stack.callback(os.close, descriptor)
+            if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+                raise ValueError("Missing regular broker lock evidence")
+            fcntl.flock(descriptor, fcntl.LOCK_EX)
+        yield
+
+
+class Survey:
+    def __init__(self, manifest: Manifest, reference: Path) -> None:
+        self.manifest = manifest
+        self.files: dict[str, bytes] = {}
+        self.blockers: list[str] = []
+        self.inventory: list[dict[str, Any]] = []
+        self.bindings: list[dict[str, Any]] = []
+        self.receipts: list[Receipt] = []
+        self.staging_bindings: list[dict[str, Any]] = []
+        self.reference = read_file(reference)
+        if (
+            b"os.path.lexists(os.path.join(control, 'cutover-fence.json'))"
+            not in self.reference
+        ):
+            raise ValueError("Reference worker lacks the cutover fence protocol")
+
+    def capture(self, path: Path, name: str) -> bytes:
+        data = read_file(path)
+        self.files[name] = data
+        if sum(map(len, self.files.values())) > MAX_TOTAL:
+            raise ValueError("Cutover evidence exceeds the aggregate byte bound")
+        return data
+
+    def inspect_staging(
+        self, side: str, authority: Authority, *, check_contents: bool = True
+    ) -> None:
+        default = directory(authority.staging_directory)
+        if authority.resource_policy_file is None:
+            if (
+                side == "receiver"
+                or not authority.legacy_default_staging_only
+                or authority.staging_views
+            ):
+                self.blockers.append(
+                    side + ": complete resource policy and staging inventory required"
+                )
+            info = default.stat()
+            self.staging_bindings.append(
+                {
+                    "side": side,
+                    "configured_path": "legacy-default",
+                    "directory": str(default),
+                    "identity": [info.st_dev, info.st_ino],
+                    "owner_uid": info.st_uid,
+                    "mode": stat.S_IMODE(info.st_mode),
+                }
+            )
+            if check_contents and any(default.iterdir()):
+                self.blockers.append(
+                    side + ": retained staging objects require confirmed recovery"
+                )
+            return
+        if authority.legacy_default_staging_only:
+            raise ValueError(
+                "Legacy default-only attestation conflicts with complete policy inventory"
+            )
+        policy_path = Path(authority.resource_policy_file)
+        if not policy_path.is_absolute() or str(
+            policy_path.resolve(strict=True)
+        ) != str(policy_path):
+            raise ValueError(
+                "Resource policy must have an existing canonical absolute path"
+            )
+        policy = ResourcePolicy.model_validate_json(
+            self.capture(policy_path, side + "/resource-policy.json")
+        )
+        resources = {resource.id: resource for resource in authority.resources}
+        if len(resources) != len(authority.resources) or len(
+            {resource.id for resource in policy.resources}
+        ) != len(policy.resources):
+            raise ValueError(
+                "Resource policy and inventory require unique resource IDs"
+            )
+        if set(resources) != {resource.id for resource in policy.resources}:
+            raise ValueError("Resource policy inventory is incomplete")
+        expected = {
+            "/data/.ztc-delete-quarantine",
+            *policy.legacy_write_staging_directories,
+        }
+        for resource in policy.resources:
+            mapped = resources[resource.id]
+            if (
+                resource.root != mapped.configured_root
+                or resource.endpoint != mapped.endpoint
+            ):
+                raise ValueError(
+                    "Resource policy lacks its original reviewed root/endpoint binding"
+                )
+            if resource.write_staging_directory is not None:
+                expected.add(resource.write_staging_directory)
+        views = {view.configured_path: view for view in authority.staging_views}
+        if len(views) != len(authority.staging_views) or set(views) != expected:
+            raise ValueError(
+                "Complete current/legacy staging view inventory is required"
+            )
+        if views["/data/.ztc-delete-quarantine"].directory != str(default):
+            raise ValueError(
+                "Default staging view conflicts with the authority inventory"
+            )
+        roots = {
+            resource.id: directory(resource.root_directory)
+            for resource in authority.resources
+        }
+        for configured, view in sorted(views.items()):
+            if (
+                not os.path.isabs(configured)
+                or os.path.normpath(configured) != configured
+                or "\x00" in configured
+            ):
+                raise ValueError(
+                    "Configured staging paths must be canonical absolute paths"
+                )
+            location = directory(view.directory)
+            info = location.stat()
+            if info.st_mode & 0o077:
+                raise ValueError("Staging views must have private permissions")
+            if any(
+                Path(configured).is_relative_to(resource.root)
+                or Path(resource.root).is_relative_to(configured)
+                for resource in policy.resources
+            ):
+                raise ValueError(
+                    "Private staging overlaps an original resource policy path"
+                )
+            if any(
+                location.is_relative_to(root)
+                or root.is_relative_to(location)
+                or (info.st_dev, info.st_ino)
+                == (root.stat().st_dev, root.stat().st_ino)
+                for root in roots.values()
+            ):
+                raise ValueError("Private staging views overlap a mapped resource")
+            for resource in policy.resources:
+                if (
+                    resource.write_staging_directory == configured
+                    and roots[resource.id].stat().st_dev != info.st_dev
+                ):
+                    raise ValueError(
+                        "Configured write staging view must share the resource filesystem"
+                    )
+            self.staging_bindings.append(
+                {
+                    "side": side,
+                    "configured_path": configured,
+                    "directory": str(location),
+                    "identity": [info.st_dev, info.st_ino],
+                    "owner_uid": info.st_uid,
+                    "mode": stat.S_IMODE(info.st_mode),
+                }
+            )
+            if check_contents and any(location.iterdir()):
+                self.blockers.append(
+                    side
+                    + ": retained staging objects require confirmed recovery: "
+                    + configured
+                )
+
+    def inspect_authority(self, side: str, authority: Authority) -> None:
+        state = directory(authority.state_directory)
+        self.inspect_staging(side, authority)
+        if read_file(Path(authority.worker_file)) != self.reference:
+            raise ValueError(
+                "Deployed worker differs from the reviewed fence-capable worker"
+            )
+        resources: dict[str, Resource] = {}
+        identities: dict[str, list[int]] = {}
+        for resource in authority.resources:
+            root = directory(resource.root_directory)
+            if (
+                not os.path.isabs(resource.configured_root)
+                or os.path.normpath(resource.configured_root)
+                != resource.configured_root
+            ):
+                raise ValueError("Configured roots must be canonical absolute paths")
+            if resource.id in resources or resource.configured_root in identities:
+                raise ValueError("Authority resource IDs and roots must be unique")
+            info = root.stat()
+            identity = [info.st_dev, info.st_ino]
+            resources[resource.id] = resource
+            identities[resource.configured_root] = identity
+            self.bindings.append(
+                {"side": side, **resource.model_dump(), "root_identity": identity}
+            )
+        lease_data = json_data(
+            self.capture(state / "leases.json", side + "/leases.json")
+        )
+        if not isinstance(lease_data, dict):
+            raise ValueError("Invalid lease registry evidence")
+        for key, value in lease_data.items():
+            lease = Lease.model_validate(value)
+            if (
+                key != digest(lease.root.encode())
+                or identities.get(lease.root) != lease.identity
+            ):
+                raise ValueError(
+                    "Lease root or physical identity lacks reviewed mapping"
+                )
+            # Explicit stop is required even for expired owners; expiry is not quiescence.
+            if lease.owner_id is not None:
+                self.blockers.append(
+                    side + ": stop every recorded lease before cutover"
+                )
+        owners = json_data(self.capture(state / "owners.json", side + "/owners.json"))
+        if not isinstance(owners, dict) or any(
+            type(v) not in [int, float] for v in owners.values()
+        ):
+            raise ValueError("Invalid owner-presence evidence")
+        canonical(owners)  # Reject nonfinite presence timestamps.
+        paths = entries(directory(str(state / "receipts")))
+        for path in paths:
+            receipt = Receipt.model_validate_json(
+                self.capture(path, side + "/receipts/" + path.name)
+            )
+            matched_resource = resources.get(receipt.resource_id)
+            if (
+                receipt.id != path.stem
+                or matched_resource is None
+                or receipt.endpoint != matched_resource.endpoint
+                or receipt.configured_root != matched_resource.configured_root
+                or receipt.root_identity != identities[matched_resource.configured_root]
+            ):
+                raise ValueError("Receipt identity lacks its original reviewed binding")
+            expected_target = os.path.normpath(
+                os.path.join(matched_resource.configured_root, receipt.requested_path)
+            )
+            if (
+                os.path.isabs(receipt.requested_path)
+                or not receipt.requested_path
+                or "\x00" in receipt.requested_path
+                or not expected_target.startswith(
+                    matched_resource.configured_root.rstrip("/") + "/"
+                )
+                or receipt.target.get("path") != expected_target
+            ):
+                raise ValueError("Receipt target lacks its original reviewed binding")
+            if (
+                receipt.status in ["pending", "unverified"]
+                or not receipt.admission_resolved
+            ):
+                self.blockers.append(side + ": unresolved receipt " + receipt.id)
+            self.receipts.append(receipt)
+        self.inventory.append(
+            {"side": side, "receipt_count": len(paths), "lease_count": len(lease_data)}
+        )
+
+    def inspect(self) -> dict[str, Any]:
+        if not self.manifest.clients_stopped:
+            self.blockers.append(
+                "Operator must stop all clients and confirm the complete client inventory"
+            )
+        for side in ["legacy", "receiver"]:
+            authority = (
+                self.manifest.legacy if side == "legacy" else self.manifest.receiver
+            )
+            self.inspect_authority(side, authority)
+        mappings = sorted(
+            [m.model_dump() for m in self.manifest.identity_mapping],
+            key=lambda m: m["legacy"],
+        )
+        for side in ["legacy", "receiver"]:
+            expected = {
+                r.id
+                for r in (
+                    self.manifest.legacy if side == "legacy" else self.manifest.receiver
+                ).resources
+            }
+            actual = [m[side] for m in mappings]
+            if len(set(actual)) != len(actual) or set(actual) != expected:
+                raise ValueError(
+                    "Identity mapping must cover both authorities exactly once"
+                )
+        count = 0
+        journals = sorted(self.manifest.client_journals)
+        if len(set(journals)) != len(journals):
+            raise ValueError("Duplicate client journal in reviewed inventory")
+        for index, value in enumerate(journals):
+            journal = directory(value)
+            for path in entries(journal):
+                record = ClientRecord.model_validate_json(
+                    self.capture(path, f"clients/{index}/" + path.name)
+                )
+                if record.id != path.stem:
+                    raise ValueError("Invalid client operation identity")
+                resources = [
+                    r
+                    for a in [self.manifest.legacy, self.manifest.receiver]
+                    for r in a.resources
+                    if r.id == record.resource_id and r.endpoint == record.endpoint
+                ]
+                if len(resources) != 1:
+                    raise ValueError(
+                        "Client endpoint lacks its original reviewed mapping"
+                    )
+                expected_target = os.path.normpath(
+                    os.path.join(resources[0].configured_root, record.requested_path)
+                )
+                if (
+                    os.path.isabs(record.requested_path)
+                    or not record.requested_path
+                    or "\x00" in record.requested_path
+                    or not expected_target.startswith(
+                        resources[0].configured_root.rstrip("/") + "/"
+                    )
+                    or record.target != expected_target
+                ):
+                    raise ValueError(
+                        "Client target lacks its original reviewed mapping"
+                    )
+                count += 1
+                if record.status == "pending":
+                    self.blockers.append("pending client operation " + record.id)
+                matches = [
+                    r
+                    for r in self.receipts
+                    if r.id == record.id
+                    and r.owner_id == record.owner_id
+                    and r.resource_id == record.resource_id
+                    and r.endpoint == record.endpoint
+                    and r.operation == record.operation
+                    and r.tool_call_id == record.tool_call_id
+                    and r.requested_path == record.requested_path
+                    and r.target.get("path") == record.target
+                ]
+                if record.status == "resolved" and len(matches) != 1:
+                    self.blockers.append(
+                        "Original receipt missing or mismatched for client operation "
+                        + record.id
+                    )
+                if record.status == "not_dispatched" and any(
+                    r.id == record.id for r in self.receipts
+                ):
+                    self.blockers.append(
+                        "No-dispatch client evidence conflicts with a recorded receipt "
+                        + record.id
+                    )
+        self.inventory.append(
+            {"side": "clients", "client_count": count, "journal_count": len(journals)}
+        )
+        # Canonical mapping order is not an ownership grant. Raw journal bytes are retained.
+        plan: dict[str, Any] = {
+            "version": 1,
+            "manifest": normalized_manifest(self.manifest),
+            "bindings": sorted(self.bindings, key=lambda b: (b["side"], b["id"])),
+            "staging_bindings": sorted(
+                self.staging_bindings,
+                key=lambda view: (view["side"], view["configured_path"]),
+            ),
+            "worker_sha256": digest(self.reference),
+            "files": {n: digest(d) for n, d in sorted(self.files.items())},
+        }
+        plan["manifest"]["identity_mapping"] = mappings
+        plan["manifest"]["client_journals"] = journals
+        self.files["plan.json"] = canonical(plan)
+        return {
+            "ready": not self.blockers,
+            "digest": digest(self.files["plan.json"]),
+            "blockers": self.blockers,
+            "identity_mapping": mappings,
+            "bindings": self.bindings,
+            "inventory": self.inventory,
+            "staging_bindings": sorted(
+                self.staging_bindings,
+                key=lambda view: (view["side"], view["configured_path"]),
+            ),
+        }
+
+
+def execute(
+    operation: str, manifest: Manifest, reference: Path, confirmation: str | None
+) -> dict[str, Any]:
+    with locked(manifest):
+        if operation != "preview" and (
+            confirmation is None or re.fullmatch(r"[a-f0-9]{64}", confirmation) is None
+        ):
+            raise ValueError("Explicit preview digest confirmation is required")
+        legacy = Path(manifest.legacy.state_directory)
+        receiver = Path(manifest.receiver.state_directory)
+        fence = canonical({"version": 1, "digest": confirmation})
+        archive = receiver / "cutovers" / str(confirmation)
+        # Lost activation acknowledgement: do not freeze an already active receiver again.
+        if operation == "activate" and not os.path.lexists(receiver / FENCE):
+            # Settle a visible unlink left by a lost response before acknowledging it.
+            sync_directory(receiver)
+            completed = json_data(read_file(archive / "completed.json"))
+            plan = json_data(read_file(archive / "plan.json"))
+            if (
+                completed
+                != {"version": 1, "digest": confirmation, "state": "activated"}
+                or read_file(legacy / FENCE) != fence
+                or digest(read_file(archive / "plan.json")) != confirmation
+                or plan["manifest"] != normalized_manifest(manifest)
+            ):
+                raise ValueError(
+                    "Activation recovery evidence does not match the confirmed mapping"
+                )
+            for name, expected in plan["files"].items():
+                if digest(read_file(archive / name)) != expected:
+                    raise ValueError(
+                        "Archived evidence damaged; preserve it for operator recovery"
+                    )
+            current = Survey(manifest, reference)
+            for side, authority in [
+                ("legacy", manifest.legacy),
+                ("receiver", manifest.receiver),
+            ]:
+                current.inspect_staging(side, authority, check_contents=False)
+            if current.blockers or sorted(
+                current.staging_bindings,
+                key=lambda view: (view["side"], view["configured_path"]),
+            ) != plan.get("staging_bindings"):
+                raise ValueError(
+                    "Activation recovery staging identity or policy inventory changed"
+                )
+            for name, data in current.files.items():
+                if read_file(archive / name) != data:
+                    raise ValueError("Activation recovery resource policy changed")
+            return {"state": "activated", "archive": str(archive)}
+        survey = Survey(manifest, reference)
+        preview = survey.inspect()
+        if operation == "preview":
+            return {"preview": preview}
+        if confirmation != preview["digest"]:
+            raise ValueError(
+                "Preview confirmation changed; review current evidence and mapping"
+            )
+        if not preview["ready"]:
+            raise ValueError("Cutover blocked: " + "; ".join(preview["blockers"]))
+        if operation == "apply":
+            # Freeze the destination first. Every interruption leaves at least
+            # that authority closed; neither operation copies or resets leases.
+            for state in [receiver, legacy]:
+                publish(state / FENCE, fence)
+            make_directory(archive)
+            for name, data in sorted(survey.files.items()):
+                target = archive / name
+                make_directory(target.parent)
+                publish(target, data)
+            publish(
+                archive / "prepared.json",
+                canonical({"version": 1, "digest": confirmation, "state": "frozen"}),
+            )
+            return {"state": "frozen", "archive": str(archive)}
+        for state in [legacy, receiver]:
+            if read_file(state / FENCE) != fence:
+                raise ValueError(
+                    "Cutover fence conflicts; explicit operator recovery required"
+                )
+        if json_data(read_file(archive / "prepared.json")) != {
+            "version": 1,
+            "digest": confirmation,
+            "state": "frozen",
+        }:
+            raise ValueError("Cutover archive has no complete preparation receipt")
+        for name, data in survey.files.items():
+            if read_file(archive / name) != data:
+                raise ValueError(
+                    "Cutover archive differs from original evidence; keep both authorities frozen"
+                )
+        publish(
+            archive / "completed.json",
+            canonical({"version": 1, "digest": confirmation, "state": "activated"}),
+        )
+        os.unlink(receiver / FENCE)
+        sync_directory(receiver)
+        return {"state": "activated", "archive": str(archive)}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Preview and confirm remote journal cutover"
+    )
+    parser.add_argument("operation", choices=["preview", "apply", "activate"])
+    parser.add_argument("--manifest", required=True)
+    parser.add_argument("--confirm")
+    parser.add_argument("--worker-file")
+    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")
+        )
+        result = execute(args.operation, manifest, reference, args.confirm)
+        print(json.dumps({"ok": True, **result}, allow_nan=False))
+    except (ValueError, OSError) as error:
+        print(json.dumps({"ok": False, "error": str(error)}))
+        raise SystemExit(2) from error
+
+
+if __name__ == "__main__":
+    main()