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

package/remote-broker/archive.py

@@ -0,0 +1,1227 @@
+"""Operator-only confirmed receipt maintenance; no broker RPC exposes this CLI."""
+
+import argparse
+import contextlib
+import fcntl
+import hashlib
+import json
+import logging
+import os
+import runpy
+import stat
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+from typing import Any, Iterator, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+L = logging.getLogger(__name__)
+INSTALLATION = Path(__file__).resolve().parent
+MAX_RECORD_BYTES = 1024 * 1024
+MAX_SOURCE_BYTES = 256 * 1024 * 1024
+
+
+class Endpoint(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=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, frozen=True)
+    id: str = Field(min_length=1, max_length=100)
+    root: str = Field(min_length=1, max_length=4096)
+    endpoint: Endpoint
+    write_staging_directory: str | None = Field(default=None, max_length=4096)
+
+
+class Policy(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+    version: Literal[1]
+    receipt_archive_index: bool = False
+    resources: list[Resource] = Field(min_length=1, max_length=100)
+    legacy_write_staging_directories: list[str] = Field(
+        default_factory=list, max_length=100
+    )
+
+
+class View(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 Manifest(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+    version: Literal[1]
+    clients_quiesced: Literal[True]
+    state_directory: str = Field(min_length=1, max_length=4096)
+    resource_policy_file: str = Field(min_length=1, max_length=4096)
+    worker_file: str = Field(min_length=1, max_length=4096)
+    client_journals: list[str] = Field(min_length=1, max_length=100)
+    staging_views: list[View] = Field(min_length=1, max_length=201)
+    root_views: list[View] = Field(default_factory=list, max_length=100)
+
+
+def encode(value: Any) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8", errors="backslashreplace")
+
+
+def sha(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+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 canonical(path: str, directory: bool = True, private: bool = True) -> Path:
+    result = Path(path)
+    if not result.is_absolute() or str(result.resolve(strict=True)) != path:
+        raise ValueError("Maintenance paths must be existing canonical absolute paths")
+    info = result.lstat()
+    if (
+        directory
+        and not stat.S_ISDIR(info.st_mode)
+        or not directory
+        and not stat.S_ISREG(info.st_mode)
+    ):
+        raise ValueError("Maintenance inputs must be regular files or real directories")
+    if private and (info.st_uid != os.geteuid() or info.st_mode & 0o077):
+        raise ValueError(
+            "Maintenance journals and staging must be private to the operator UID"
+        )
+    return result
+
+
+def fingerprint(path: Path) -> dict[str, int]:
+    info = path.lstat()
+    return {
+        "device": info.st_dev,
+        "inode": info.st_ino,
+        "uid": info.st_uid,
+        "mode": info.st_mode,
+    }
+
+
+def bounded(path: Path, limit: int = MAX_RECORD_BYTES) -> bytes:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as stream:
+        before = os.fstat(stream.fileno())
+        if not stat.S_ISREG(before.st_mode) or before.st_size > limit:
+            raise ValueError("Maintenance evidence exceeds its regular-file bound")
+        data = stream.read(limit + 1)
+        after = os.fstat(stream.fileno())
+        if len(data) > limit or (
+            before.st_dev,
+            before.st_ino,
+            before.st_size,
+            before.st_mtime_ns,
+        ) != (after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns):
+            raise ValueError("Maintenance evidence changed during its bounded read")
+        return data
+
+
+def process_namespace() -> dict[str, Any]:
+    if sys.platform == "linux":
+        boot = (
+            bounded(Path("/proc/sys/kernel/random/boot_id"), 4096)
+            .decode()
+            .strip()
+            .lower()
+        )
+        namespace = Path("/proc/self/ns/pid").stat()
+        result: dict[str, Any] = {
+            "platform": "linux",
+            "pid_namespace": [namespace.st_dev, namespace.st_ino],
+        }
+    elif sys.platform == "darwin":
+        query = subprocess.run(
+            ["/usr/sbin/sysctl", "-n", "kern.bootsessionuuid"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=True,
+        )
+        boot = query.stdout.strip().lower()
+        result = {"platform": "darwin"}
+    else:
+        raise ValueError(
+            "Operator lock recovery requires a supported process namespace"
+        )
+    if str(uuid.UUID(boot)) != boot:
+        raise ValueError("Invalid operator kernel boot identity")
+    return {**result, "boot_id": boot}
+
+
+def overlaps(first: Path, second: Path) -> bool:
+    return first.is_relative_to(second) or second.is_relative_to(first)
+
+
+def private_tree(path: Path) -> None:
+    missing: list[Path] = []
+    current = path
+    while not os.path.lexists(current):
+        missing.append(current)
+        current = current.parent
+    canonical(str(current), private=False)
+    for directory in reversed(missing):
+        directory.mkdir(mode=0o700)
+        sync_directory(directory)
+        sync_directory(directory.parent)
+
+
+def publish(path: Path, data: bytes, replace: bool = False) -> None:
+    private_tree(path.parent)
+    canonical(str(path.parent))
+    temporary = path.parent / (".archive-" + str(uuid.uuid4()))
+    descriptor = os.open(
+        temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        if replace:
+            os.replace(temporary, path)
+        else:
+            try:
+                os.link(temporary, path)
+            except FileExistsError:
+                if bounded(path, max(MAX_RECORD_BYTES, len(data))) != data:
+                    raise ValueError(
+                        "Existing archive evidence differs; explicit recovery is required"
+                    )
+        sync_directory(path.parent)
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            temporary.unlink()
+
+
+class JournalArchive:
+    def __init__(self, manifest_file: str) -> None:
+        self._init_manifest_system(manifest_file)
+        self._init_worker_system()
+        self._init_policy_system()
+        self._init_binding_system()
+
+    def _init_manifest_system(self, manifest_file: str) -> None:
+        self.manifest_path = canonical(manifest_file, directory=False, private=False)
+        self.manifest_bytes = bounded(self.manifest_path)
+        self.manifest = Manifest.model_validate_json(self.manifest_bytes)
+        self.control = canonical(self.manifest.state_directory)
+        self.clients = [canonical(path) for path in self.manifest.client_journals]
+        if len(set(self.clients)) != len(self.clients):
+            raise ValueError("Client journals must be unique")
+        for index, first in enumerate([self.control, *self.clients]):
+            if any(
+                overlaps(first, second)
+                for second in [self.control, *self.clients][index + 1 :]
+            ):
+                raise ValueError("Host and client journal namespaces must be disjoint")
+        self.fences = [
+            self.control / "journal-maintenance.json",
+            *[Path(str(path) + ".maintenance.json") for path in self.clients],
+        ]
+
+    def _init_worker_system(self) -> None:
+        self.worker = canonical(
+            self.manifest.worker_file, directory=False, private=False
+        )
+        packaged = canonical(
+            str(INSTALLATION / "worker.py"), directory=False, private=False
+        )
+        self.worker_bytes = bounded(self.worker, 8 * MAX_RECORD_BYTES)
+        if self.worker_bytes != bounded(packaged, 8 * MAX_RECORD_BYTES):
+            raise ValueError(
+                "Maintenance requires the matching packaged immutable worker"
+            )
+        self.worker_api = runpy.run_path(str(packaged))
+
+    def _init_policy_system(self) -> None:
+        self.policy_path = canonical(
+            self.manifest.resource_policy_file, directory=False, private=False
+        )
+        self.policy_bytes = bounded(self.policy_path)
+        self.policy = Policy.model_validate_json(self.policy_bytes)
+        if not self.policy.receipt_archive_index:
+            raise ValueError(
+                "Enable receipt_archive_index in immutable operator policy before maintenance"
+            )
+        self.resources = {resource.id: resource for resource in self.policy.resources}
+        if len(self.resources) != len(self.policy.resources):
+            raise ValueError("Policy resource IDs must be unique")
+        configured = {
+            "/data/.ztc-delete-quarantine",
+            *self.policy.legacy_write_staging_directories,
+        }
+        configured.update(
+            resource.write_staging_directory
+            for resource in self.policy.resources
+            if resource.write_staging_directory is not None
+        )
+        self.staging = {
+            view.configured_path: canonical(view.directory)
+            for view in self.manifest.staging_views
+        }
+        if (
+            set(self.staging) != configured
+            or len(self.staging) != len(self.manifest.staging_views)
+            or len(set(self.staging.values())) != len(self.staging)
+        ):
+            raise ValueError(
+                "A complete unique default/current/historical staging inventory is required"
+            )
+        views = {
+            view.configured_path: view.directory for view in self.manifest.root_views
+        }
+        if len(views) != len(self.manifest.root_views) or set(views) - {
+            resource.root for resource in self.policy.resources
+        }:
+            raise ValueError("Root views must have unique configured policy paths")
+        self.roots = {
+            resource.id: canonical(
+                views.get(resource.root, resource.root), private=False
+            )
+            for resource in self.policy.resources
+        }
+        for root in self.roots.values():
+            if any(
+                overlaps(root, protected)
+                for protected in [self.control, *self.clients, *self.staging.values()]
+            ):
+                raise ValueError(
+                    "Resource views overlap maintenance journals or private staging"
+                )
+
+    def _init_binding_system(self) -> None:
+        paths = [
+            self.control,
+            *self.clients,
+            *self.staging.values(),
+            *self.roots.values(),
+            self.worker,
+            self.policy_path,
+        ]
+        self.bindings = {str(path): fingerprint(path) for path in paths}
+        self.process_namespace = process_namespace()
+        self.records: dict[str, dict[str, Any]] = {}
+        self.source_bytes = 0
+
+    @contextlib.contextmanager
+    def locked(self, digest: str | None = None) -> Iterator[None]:
+        with contextlib.ExitStack() as handles:
+            for journal in sorted(self.clients):
+                lock = Path(str(journal) + ".admission-lock")
+                try:
+                    lock.mkdir(mode=0o700)
+                except FileExistsError:
+                    if digest is None:
+                        raise ValueError(
+                            "Client journal is locked; inspect its owner before confirmed recovery"
+                        )
+                    self.recover_dead_operator_lock(lock, journal, digest)
+                    lock.mkdir(mode=0o700)
+                metadata = encode(
+                    {
+                        "version": 1,
+                        "nonce": str(uuid.uuid4()),
+                        "pid": os.getpid(),
+                        "operator": "ztc-archive",
+                        "digest": digest,
+                        "manifest_sha256": sha(self.manifest_bytes),
+                        "journal_identity": fingerprint(journal),
+                        "process_namespace": self.process_namespace,
+                    }
+                )
+                publish(lock / "owner.json", metadata)
+                identity = fingerprint(lock)
+                handles.callback(self.release_lock, lock, identity, metadata)
+                sync_directory(lock.parent)
+            descriptor = os.open(
+                self.control / "lock",
+                os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK,
+                0o600,
+            )
+            handles.callback(os.close, descriptor)
+            if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+                raise ValueError("Broker lock must be a regular file")
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            sync_directory(self.control)
+            yield
+
+    def recover_dead_operator_lock(
+        self, lock: Path, journal: Path, digest: str
+    ) -> None:
+        canonical(str(lock))
+        identity = fingerprint(lock)
+        data = bounded(lock / "owner.json")
+        owner = json.loads(data)
+        if (
+            not isinstance(owner, dict)
+            or type(owner.get("version")) is not int
+            or owner["version"] != 1
+            or owner.get("operator") != "ztc-archive"
+            or owner.get("digest") != digest
+            or owner.get("manifest_sha256") != sha(self.manifest_bytes)
+            or owner.get("journal_identity") != fingerprint(journal)
+            or owner.get("process_namespace") != self.process_namespace
+            or type(owner.get("pid")) is not int
+            or owner["pid"] <= 0
+            or not isinstance(owner.get("nonce"), str)
+            or str(uuid.UUID(owner["nonce"])) != owner["nonce"]
+        ):
+            raise ValueError(
+                "Client journal lock requires explicit reviewed recovery; its owner is unknown or belongs to another namespace"
+            )
+        try:
+            os.kill(owner["pid"], 0)
+        except ProcessLookupError:
+            pass
+        else:
+            raise ValueError(
+                "Operator journal lock owner is still live; confirmed resume cannot steal it"
+            )
+        retained = Path(str(lock) + ".retained-" + owner["nonce"])
+        descriptor = os.open(lock.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        try:
+            if fingerprint(lock) != identity or bounded(lock / "owner.json") != data:
+                raise ValueError(
+                    "Operator lock changed during review; preserve its evidence"
+                )
+            self.worker_api["rename_without_replacement"](
+                descriptor, lock.name, descriptor, retained.name
+            )
+            os.fsync(descriptor)
+            if (
+                fingerprint(retained) != identity
+                or bounded(retained / "owner.json") != data
+            ):
+                with contextlib.suppress(OSError):
+                    self.worker_api["rename_without_replacement"](
+                        descriptor, retained.name, descriptor, lock.name
+                    )
+                    os.fsync(descriptor)
+                raise ValueError(
+                    "Operator lock recovery changed; original evidence was retained"
+                )
+        finally:
+            os.close(descriptor)
+
+    @staticmethod
+    def release_lock(path: Path, identity: dict[str, int], metadata: bytes) -> None:
+        if fingerprint(path) != identity or bounded(path / "owner.json") != metadata:
+            raise ValueError(
+                "Maintenance lock changed; explicit operator recovery is required"
+            )
+        (path / "owner.json").unlink()
+        path.rmdir()
+        sync_directory(path.parent)
+
+    def capture(self, path: Path) -> bytes:
+        data = bounded(path)
+        self.source_bytes += len(data)
+        if self.source_bytes > MAX_SOURCE_BYTES:
+            raise ValueError("Maintenance export exceeds its aggregate 256 MiB bound")
+        return data
+
+    def scan(self, directory: Path, source: str) -> list[dict[str, Any]]:
+        canonical(str(directory))
+        names = sorted(directory.iterdir())
+        if len(names) > 10000:
+            raise ValueError(
+                "Active journal exceeds its 10,000-entry bound; preserve and inspect it"
+            )
+        result: list[dict[str, Any]] = []
+        for path in names:
+            if path.suffix != ".json" or str(uuid.UUID(path.stem)) != path.stem:
+                raise ValueError("Invalid active journal record name")
+            canonical(str(path), directory=False)
+            data = self.capture(path)
+            value = json.loads(data)
+            if (
+                not isinstance(value, dict)
+                or value.get("version") != 1
+                or value.get("id") != path.stem
+                or value.get("operation") not in ["write", "delete"]
+            ):
+                raise ValueError("Invalid active journal operation identity")
+            requested = value.get("requested_path")
+            if (
+                not isinstance(requested, str)
+                or not requested
+                or os.path.isabs(requested)
+                or "\x00" in requested
+            ):
+                raise ValueError("Invalid original relative target path")
+            endpoint = Endpoint.model_validate(value.get("endpoint"))
+            owner = value.get("owner_id")
+            call = value.get("tool_call_id")
+            if (
+                not isinstance(owner, str)
+                or not owner
+                or len(owner) > 200
+                or call is not None
+                and (not isinstance(call, str) or not call or len(call) > 200)
+            ):
+                raise ValueError("Invalid original owner or originating-call linkage")
+            target_evidence = value.get("target")
+            if source == "host":
+                if not isinstance(target_evidence, dict):
+                    raise ValueError("Invalid original target verification evidence")
+                target = target_evidence.get("path")
+            else:
+                target = target_evidence
+            statuses = (
+                ["pending", "resolved", "not_dispatched"]
+                if source != "host"
+                else [
+                    "pending",
+                    "verified",
+                    "failed",
+                    "unverified",
+                    "dry_run",
+                    "cancelled",
+                ]
+            )
+            if (
+                value.get("status") not in statuses
+                or type(value.get("version")) is not int
+            ):
+                raise ValueError("Invalid original journal status or schema version")
+            if not isinstance(target, str) or not os.path.isabs(target):
+                raise ValueError("Invalid original target evidence")
+            record = {
+                "source": source,
+                "id": path.stem,
+                "sha256": sha(data),
+                "size": len(data),
+                "identity": fingerprint(path),
+                "status": value.get("status"),
+                "owner_id": owner,
+                "tool_call_id": call,
+                "endpoint": endpoint.model_dump(),
+                "resource_id": value.get("resource_id"),
+                "operation": value["operation"],
+                "target": target,
+                "requested_path": value.get("requested_path"),
+                "archive": False,
+                "reason": "requires recovery",
+            }
+            self.records[source + "/" + path.stem] = {
+                "path": path,
+                "bytes": data,
+                "value": value,
+                "record": record,
+            }
+            result.append(record)
+        return result
+
+    def preview(self) -> dict[str, Any]:
+        if any(os.path.lexists(path) for path in self.fences) or os.path.lexists(
+            self.control / "cutover-fence.json"
+        ):
+            raise ValueError(
+                "Maintenance or cutover is frozen; inspect and resume its confirmed transaction"
+            )
+        self.records = {}
+        self.source_bytes = 0
+        receipts = self.control / "receipts"
+        if not receipts.exists():
+            raise ValueError(
+                "Receipt journal must already exist; initialization is a separate host setup operation"
+            )
+        host = self.scan(receipts, "host")
+        clients = [
+            self.scan(path, "client-" + str(index))
+            for index, path in enumerate(self.clients)
+        ]
+        if sum(len(records) for records in clients) > 10000:
+            raise ValueError(
+                "Participating client journals exceed the aggregate 10,000-entry maintenance bound"
+            )
+        staged: set[str] = set()
+        blockers: list[str] = []
+        for configured, directory in sorted(self.staging.items()):
+            entries = list(directory.iterdir())
+            if len(entries) > 10000:
+                raise ValueError("Private staging exceeds its bounded inventory")
+            for entry in entries:
+                try:
+                    if str(uuid.UUID(entry.name)) != entry.name:
+                        raise ValueError("Unknown staging entry")
+                except ValueError:
+                    blockers.append(
+                        "Unknown retained staging evidence at " + configured
+                    )
+                    continue
+                staged.add(entry.name)
+        by_id = {record["id"]: record for record in host}
+        if staged - set(by_id):
+            blockers.append("Unlinked private staging evidence requires recovery")
+        client_records = [record for records in clients for record in records]
+        client_linkage: dict[str, list[dict[str, Any]]] = {}
+        for record in client_records:
+            client_linkage.setdefault(record["id"], []).append(record)
+        for record in host:
+            value = self.records["host/" + record["id"]]["value"]
+            linked = client_linkage.get(record["id"], [])
+            if record["status"] not in ["verified", "failed", "dry_run", "cancelled"]:
+                record["reason"] = "pending or unverified remote outcome"
+            elif value.get("admission_resolved") is not True:
+                record["reason"] = "unresolved remote admission or recovery"
+            elif record["id"] in staged:
+                record["reason"] = "private staging still retains operation evidence"
+            elif not linked or any(other["status"] != "resolved" for other in linked):
+                record["reason"] = "missing or unresolved participating client linkage"
+            elif any(not self.same_origin(record, other) for other in linked):
+                record["reason"] = "original client/host linkage differs"
+            elif record["status"] == "verified" and (
+                not isinstance(value.get("verification"), dict)
+                or not (
+                    value["verification"].get("target_matches") is True
+                    or value["verification"].get("target_absent") is True
+                )
+            ):
+                record["reason"] = (
+                    "verified receipt lacks its original target verification"
+                )
+            elif record["status"] == "cancelled" and (
+                not isinstance(value.get("resolution"), dict)
+                or value["resolution"].get("decision") != "accept_current_state"
+            ):
+                record["reason"] = (
+                    "cancellation lacks its confirmed original reconciliation"
+                )
+            else:
+                record.update(
+                    archive=True,
+                    reason="terminal acknowledged outcome with exact client linkage",
+                )
+        for record in client_records:
+            receipt = by_id.get(record["id"])
+            if record["id"] in staged:
+                record["reason"] = "private staging still retains operation evidence"
+            elif record["status"] == "pending":
+                record["reason"] = "unresolved client admission"
+            elif record["status"] == "not_dispatched" and receipt is None:
+                record.update(
+                    archive=True,
+                    reason="terminal not-dispatched origin; retain host replay protection",
+                )
+            elif (
+                record["status"] == "resolved"
+                and receipt is not None
+                and receipt["archive"]
+                and self.same_origin(record, receipt)
+            ):
+                record.update(
+                    archive=True,
+                    reason="terminal client linked to archived acknowledged remote receipt",
+                )
+            else:
+                record["reason"] = "missing, uncertain or conflicting remote linkage"
+        origins: dict[str, str] = {}
+        for record in [*host, *client_records]:
+            if record["tool_call_id"] is not None:
+                endpoint = record["endpoint"]
+                key = sha(
+                    encode(
+                        [
+                            "call",
+                            endpoint["host"],
+                            endpoint["user"],
+                            endpoint["port"],
+                            record["owner_id"],
+                            record["tool_call_id"],
+                        ]
+                    )
+                )
+                if key in origins and origins[key] != record["id"]:
+                    blockers.append(
+                        "Conflicting original operation IDs for an originating call"
+                    )
+                origins[key] = record["id"]
+        index_states: dict[str, str | None] = {}
+        for source, directory, archives in [
+            ("host", self.control / "replay-index", self.control / "receipt-archives"),
+            *[
+                (
+                    "client-" + str(i),
+                    Path(str(path) + ".replay"),
+                    Path(str(path) + ".archives"),
+                )
+                for i, path in enumerate(self.clients)
+            ],
+        ]:
+            required = os.path.lexists(archives) or (
+                source != "host"
+                and os.path.lexists(
+                    Path(str(self.clients[int(source[7:])]) + ".replay-required.json")
+                )
+            )
+            header = self.worker_api["replay_manifest"](str(directory), required)
+            if header is not None:
+                for prefix, bucket in header["buckets"].items():
+                    self.worker_api["replay_bucket"](str(directory), prefix, bucket)
+                index_states[source] = sha(bounded(directory / "manifest.json"))
+            else:
+                index_states[source] = None
+        leases = self.control / "leases.json"
+        lease_bytes = bounded(leases, 16 * MAX_RECORD_BYTES) if leases.exists() else b""
+        plan = {
+            "version": 1,
+            "manifest_sha256": sha(self.manifest_bytes),
+            "worker_sha256": sha(self.worker_bytes),
+            "policy_sha256": sha(self.policy_bytes),
+            "operator_sha256": sha(bounded(Path(__file__), 8 * MAX_RECORD_BYTES)),
+            "bindings": self.bindings,
+            "lease_sha256": sha(lease_bytes),
+            "journals": {
+                "host": host,
+                **{"client-" + str(i): records for i, records in enumerate(clients)},
+            },
+            "replay_before": index_states,
+            "blockers": blockers,
+        }
+        return {
+            "ready": not blockers,
+            "digest": sha(encode(plan)),
+            "plan": plan,
+            "archive_count": sum(
+                record["archive"] for record in [*host, *client_records]
+            ),
+            "preserved_count": sum(
+                not record["archive"] for record in [*host, *client_records]
+            ),
+            "index_initialization": [
+                source for source, value in index_states.items() if value is None
+            ],
+        }
+
+    def archive_roots(self, digest: str) -> dict[str, Path]:
+        return {
+            "host": self.control / "receipt-archives" / digest,
+            **{
+                "client-" + str(index): Path(str(path) + ".archives") / digest
+                for index, path in enumerate(self.clients)
+            },
+        }
+
+    def journal_roots(self) -> dict[str, Path]:
+        return {
+            "host": self.control / "receipts",
+            **{"client-" + str(index): path for index, path in enumerate(self.clients)},
+        }
+
+    def index_roots(self) -> dict[str, Path]:
+        return {
+            "host": self.control / "replay-index",
+            **{
+                "client-" + str(index): Path(str(path) + ".replay")
+                for index, path in enumerate(self.clients)
+            },
+        }
+
+    def fence_bytes(self, digest: str) -> bytes:
+        return encode(
+            {
+                "version": 1,
+                "digest": digest,
+                "manifest_sha256": sha(self.manifest_bytes),
+                "worker_sha256": sha(self.worker_bytes),
+                "policy_sha256": sha(self.policy_bytes),
+            }
+        )
+
+    def require_fences(self, digest: str) -> None:
+        expected = self.fence_bytes(digest)
+        for path in self.fences:
+            if not os.path.lexists(path) or bounded(path) != expected:
+                raise ValueError(
+                    "Maintenance fence differs or is missing; preserve evidence for explicit recovery"
+                )
+
+    def record_export_path(self, root: Path, source: str, identifier: str) -> Path:
+        return (
+            root
+            / ("receipts" if source == "host" else "records")
+            / (identifier + ".json")
+        )
+
+    def export(self, plan: dict[str, Any], digest: str) -> None:
+        roots = self.archive_roots(digest)
+        payload = encode(plan)
+        if len(payload) > 16 * MAX_RECORD_BYTES:
+            raise ValueError("Concrete archive plan exceeds its 16 MiB bound")
+        for root in roots.values():
+            publish(root / "plan.json", payload)
+        for name, data in [
+            ("manifest.json", self.manifest_bytes),
+            ("resources.json", self.policy_bytes),
+            ("worker.py", self.worker_bytes),
+            ("operator.py", bounded(Path(__file__), 8 * MAX_RECORD_BYTES)),
+        ]:
+            publish(roots["host"] / name, data)
+        for source, records in plan["journals"].items():
+            for record in records:
+                data = self.records[source + "/" + record["id"]]["bytes"]
+                publish(
+                    self.record_export_path(roots[source], source, record["id"]), data
+                )
+                if source != "host":
+                    publish(
+                        roots["host"]
+                        / "clients"
+                        / source
+                        / "records"
+                        / (record["id"] + ".json"),
+                        data,
+                    )
+            (roots[source] / "compacted").mkdir(mode=0o700, exist_ok=True)
+        # Copy the exact old replay header and objects before any index publication.
+        # Resume builds from this immutable view even after one live header changes.
+        for source, directory in self.index_roots().items():
+            before = roots[source] / "replay-before"
+            before.mkdir(mode=0o700, exist_ok=True)
+            if plan["replay_before"][source] is None:
+                publish(
+                    before / "manifest.json",
+                    encode({"version": 1, "total": 0, "buckets": {}}),
+                )
+            elif not (before / "manifest.json").exists():
+                data = bounded(directory / "manifest.json")
+                if sha(data) != plan["replay_before"][source]:
+                    raise ValueError("Original replay manifest changed before export")
+                header = self.worker_api["replay_manifest"](str(directory), True)
+                for bucket in header["buckets"].values():
+                    publish(
+                        before / "objects" / (bucket["sha256"] + ".json"),
+                        bounded(
+                            directory / "objects" / (bucket["sha256"] + ".json"),
+                            2 * MAX_RECORD_BYTES,
+                        ),
+                    )
+                publish(before / "manifest.json", data)
+        self.sync_export_roots(roots)
+
+    @staticmethod
+    def sync_export_roots(roots: dict[str, Path]) -> None:
+        for root in roots.values():
+            # Each file was fsynced before publication. Settle every directory
+            # binding, including archive ancestors, before active records move.
+            directories: list[Path] = []
+            for path, names, files in os.walk(root, followlinks=False):
+                directory = canonical(path)
+                directories.append(directory)
+                if len(names) + len(files) > 20000:
+                    raise ValueError("Archive directory exceeds its inventory bound")
+            for directory in reversed(directories):
+                sync_directory(directory)
+            sync_directory(root.parent)
+            sync_directory(root.parent.parent)
+
+    def replay_after(
+        self, plan: dict[str, Any], digest: str
+    ) -> dict[str, tuple[bytes, dict[str, bytes]]]:
+        roots = self.archive_roots(digest)
+        additions: dict[str, dict[str, dict[str, Any]]] = {
+            source: {} for source in roots
+        }
+        host_ids = {
+            record["id"]: record
+            for record in plan["journals"]["host"]
+            if record["archive"]
+        }
+        for source, records in plan["journals"].items():
+            for record in records:
+                if not record["archive"]:
+                    continue
+                pointer = {
+                    "id": record["id"],
+                    "archive": digest,
+                    "sha256": record["sha256"],
+                    "kind": "receipt" if source == "host" else "client",
+                }
+                keys = [self.worker_api["replay_key"](["operation", record["id"]])]
+                endpoint = record["endpoint"]
+                if record["tool_call_id"] is not None:
+                    keys.append(
+                        self.worker_api["replay_key"](
+                            [
+                                "call",
+                                endpoint["host"],
+                                endpoint["user"],
+                                endpoint["port"],
+                                record["owner_id"],
+                                record["tool_call_id"],
+                            ]
+                        )
+                    )
+                for key in keys:
+                    previous = additions[source].get(key)
+                    if previous is not None and previous != pointer:
+                        raise ValueError(
+                            "Conflicting original replay linkage; preserve both full records"
+                        )
+                    additions[source][key] = pointer
+                    if source != "host" and record["id"] not in host_ids:
+                        previous = additions["host"].get(key)
+                        if previous is not None and previous != pointer:
+                            raise ValueError(
+                                "Ambiguous client-origin archive evidence; preserve both records"
+                            )
+                        additions["host"][key] = pointer
+                        publish(
+                            roots["host"] / "client-records" / (record["id"] + ".json"),
+                            self.records[source + "/" + record["id"]]["bytes"],
+                        )
+        after: dict[str, tuple[bytes, dict[str, bytes]]] = {}
+        aggregate_bytes = 0
+        for source, pending in additions.items():
+            directory = roots[source] / "replay-before"
+            header = self.worker_api["replay_manifest"](str(directory), True)
+            groups: dict[str, dict[str, Any]] = {}
+            for key, pointer in pending.items():
+                groups.setdefault(key[:3], {})[key] = pointer
+            buckets: dict[str, dict[str, Any]] = {}
+            objects: dict[str, bytes] = {}
+            total = 0
+            for prefix in sorted(set(header["buckets"]) | set(groups)):
+                entries = (
+                    self.worker_api["replay_bucket"](
+                        str(directory), prefix, header["buckets"][prefix]
+                    )
+                    if prefix in header["buckets"]
+                    else {}
+                )
+                for key, pointer in groups.get(prefix, {}).items():
+                    if key in entries and entries[key] != pointer:
+                        raise ValueError(
+                            "An active origin already appears in retired replay protection; preserve and inspect it"
+                        )
+                    entries[key] = pointer
+                data = encode({"version": 1, "entries": entries})
+                if len(entries) > 4096 or len(data) > 2 * MAX_RECORD_BYTES:
+                    raise ValueError(
+                        "Replay bucket is full; existing protection cannot be discarded"
+                    )
+                total += len(entries)
+                aggregate_bytes += len(data)
+                if total > 1000000 or aggregate_bytes > 256 * MAX_RECORD_BYTES:
+                    raise ValueError(
+                        "Replay maintenance exceeds its bounded key or byte budget"
+                    )
+                checksum = sha(data)
+                objects[checksum + ".json"] = data
+                buckets[prefix] = {"sha256": checksum, "count": len(entries)}
+            data = encode({"version": 1, "total": total, "buckets": buckets})
+            if len(data) > MAX_RECORD_BYTES:
+                raise ValueError("Replay manifest exceeds its 1 MiB bound")
+            after[source] = (data, objects)
+            for name, body in objects.items():
+                publish(roots[source] / "replay-after" / "objects" / name, body)
+            publish(roots[source] / "replay-after" / "manifest.json", data)
+        self.sync_export_roots(roots)
+        return after
+
+    def load_plan(self, digest: str) -> dict[str, Any]:
+        root = self.archive_roots(digest)["host"]
+        data = bounded(root / "plan.json", 16 * MAX_RECORD_BYTES)
+        if sha(data) != digest:
+            raise ValueError("Confirmed archive plan checksum changed")
+        plan = json.loads(data)
+        if (
+            not isinstance(plan, dict)
+            or plan.get("manifest_sha256") != sha(self.manifest_bytes)
+            or plan.get("worker_sha256") != sha(self.worker_bytes)
+            or plan.get("policy_sha256") != sha(self.policy_bytes)
+            or plan.get("operator_sha256")
+            != sha(bounded(Path(__file__), 8 * MAX_RECORD_BYTES))
+            or plan.get("bindings") != self.bindings
+        ):
+            raise ValueError(
+                "Original archive source, policy or namespace bindings changed"
+            )
+        return dict(plan)
+
+    def restore_snapshot(self, plan: dict[str, Any], digest: str) -> None:
+        self.records = {}
+        roots = self.archive_roots(digest)
+        sources = self.journal_roots()
+        for source, records in plan["journals"].items():
+            expected_names = {record["id"] + ".json" for record in records}
+            if set(os.listdir(sources[source])) - expected_names:
+                raise ValueError(
+                    "Active journal acquired unreviewed records; preserve the maintenance fence"
+                )
+            for record in records:
+                exported = self.record_export_path(roots[source], source, record["id"])
+                active = sources[source] / (record["id"] + ".json")
+                captured = roots[source] / "compacted" / (record["id"] + ".json")
+                if exported.exists():
+                    data = bounded(exported)
+                elif active.exists() and fingerprint(active) == record["identity"]:
+                    data = bounded(active)
+                else:
+                    raise ValueError(
+                        "Original full archive export is missing; preserve remaining active evidence"
+                    )
+                if sha(data) != record["sha256"]:
+                    raise ValueError("Original archived record checksum changed")
+                if active.exists():
+                    if (
+                        fingerprint(active) != record["identity"]
+                        or sha(bounded(active)) != record["sha256"]
+                    ):
+                        raise ValueError(
+                            "Original active record changed; preserve the maintenance fence"
+                        )
+                elif (
+                    not record["archive"]
+                    or not captured.exists()
+                    or fingerprint(captured) != record["identity"]
+                    or sha(bounded(captured)) != record["sha256"]
+                ):
+                    raise ValueError(
+                        "Original active record disappeared without its durable archive capture"
+                    )
+                self.records[source + "/" + record["id"]] = {
+                    "path": active,
+                    "bytes": data,
+                    "value": json.loads(data),
+                    "record": record,
+                }
+
+    def compact(self, plan: dict[str, Any], digest: str) -> None:
+        roots = self.archive_roots(digest)
+        for source, records in plan["journals"].items():
+            with contextlib.ExitStack() as handles:
+                journal = os.open(
+                    self.journal_roots()[source],
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                )
+                destination = os.open(
+                    roots[source] / "compacted",
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                )
+                handles.callback(os.close, journal)
+                handles.callback(os.close, destination)
+                for record in records:
+                    if not record["archive"]:
+                        continue
+                    name = record["id"] + ".json"
+                    path = roots[source] / "compacted" / name
+                    active = self.journal_roots()[source] / name
+                    if not os.path.lexists(path):
+                        self.worker_api["rename_without_replacement"](
+                            journal, name, destination, name
+                        )
+                        os.fsync(journal)
+                        os.fsync(destination)
+                    if (
+                        fingerprint(path) != record["identity"]
+                        or sha(bounded(path)) != record["sha256"]
+                    ):
+                        # Capture may have raced an external administrator. Keep
+                        # all bytes, restoring only into an unoccupied old name.
+                        with contextlib.suppress(OSError):
+                            self.worker_api["rename_without_replacement"](
+                                destination, name, journal, name
+                            )
+                            os.fsync(journal)
+                            os.fsync(destination)
+                        raise ValueError(
+                            "Archive capture changed; replacement evidence was retained for explicit recovery"
+                        )
+                    if os.path.lexists(active):
+                        raise ValueError(
+                            "An unreviewed active replacement exists; preserve both records"
+                        )
+
+    def clear_matching_fences(self, digest: str) -> None:
+        expected = self.fence_bytes(digest)
+        existing = [path for path in self.fences if os.path.lexists(path)]
+        if any(bounded(path) != expected for path in existing):
+            raise ValueError(
+                "A different maintenance fence is present; preserve its authority"
+            )
+        for path in existing:
+            path.unlink()
+            sync_directory(path.parent)
+
+    def apply(self, digest: str) -> dict[str, Any]:
+        if len(digest) != 64 or any(
+            character not in "0123456789abcdef" for character in digest
+        ):
+            raise ValueError("Confirmation must be the exact archive preview digest")
+        roots = self.archive_roots(digest)
+        completed = roots["host"] / "complete.json"
+        if completed.exists():
+            plan = self.load_plan(digest)
+            for source, records in plan["journals"].items():
+                for record in records:
+                    if (
+                        sha(
+                            bounded(
+                                self.record_export_path(
+                                    roots[source], source, record["id"]
+                                )
+                            )
+                        )
+                        != record["sha256"]
+                    ):
+                        raise ValueError("Completed archive evidence checksum changed")
+            result = json.loads(bounded(completed))
+            if result.get("digest") != digest or result.get("state") != "archived":
+                raise ValueError("Completed archive receipt differs")
+            self.clear_matching_fences(digest)
+            return {**result, "historical": True}
+        prepared = roots["host"] / "plan.json"
+        if prepared.exists():
+            plan = self.load_plan(digest)
+            self.restore_snapshot(plan, digest)
+            leases = self.control / "leases.json"
+            lease_bytes = (
+                bounded(leases, 16 * MAX_RECORD_BYTES) if leases.exists() else b""
+            )
+            if sha(lease_bytes) != plan["lease_sha256"]:
+                raise ValueError(
+                    "Original lease state changed; inspect a fresh archive preview"
+                )
+            expected = self.fence_bytes(digest)
+            if any(
+                os.path.lexists(path) and bounded(path) != expected
+                for path in self.fences
+            ):
+                raise ValueError(
+                    "A different maintenance fence is present; preserve its authority"
+                )
+            for path in self.fences:
+                publish(path, expected)
+        else:
+            preview = self.preview()
+            if preview["digest"] != digest:
+                raise ValueError(
+                    "Confirmation changed; inspect the exact current preview"
+                )
+            if not preview["ready"]:
+                raise ValueError(
+                    "Maintenance is blocked by retained or conflicting evidence"
+                )
+            plan = preview["plan"]
+            # The full reviewed plan is durable before the first persistent fence.
+            for root in roots.values():
+                publish(root / "plan.json", encode(plan))
+            self.sync_export_roots(roots)
+            for path in self.fences:
+                publish(path, self.fence_bytes(digest))
+        self.require_fences(digest)
+        self.export(plan, digest)
+        after = self.replay_after(plan, digest)
+        for source, directory in self.index_roots().items():
+            expected_before = plan["replay_before"][source]
+            live = directory / "manifest.json"
+            if live.exists() and sha(bounded(live)) not in [
+                expected_before,
+                sha(after[source][0]),
+            ]:
+                raise ValueError(
+                    "Live replay manifest changed outside this transaction"
+                )
+            if not live.exists() and expected_before is not None:
+                raise ValueError("Original live replay manifest disappeared")
+            for name, body in after[source][1].items():
+                publish(directory / "objects" / name, body)
+            publish(live, after[source][0], replace=True)
+            if source != "host":
+                publish(
+                    Path(str(self.clients[int(source[7:])]) + ".replay-required.json"),
+                    encode({"version": 1}),
+                    replace=False,
+                )
+        for source, directory in self.index_roots().items():
+            if sha(bounded(directory / "manifest.json")) != sha(after[source][0]):
+                raise ValueError(
+                    "Replay publication is unresolved; preserve the maintenance fences"
+                )
+        self.restore_snapshot(plan, digest)
+        self.compact(plan, digest)
+        result = {
+            "ok": True,
+            "version": 1,
+            "state": "archived",
+            "digest": digest,
+            "archived_counts": {
+                source: sum(record["archive"] for record in records)
+                for source, records in plan["journals"].items()
+            },
+            "historical": False,
+            "target_effects": "none",
+            "reclaimed_bytes": None,
+        }
+        for root in roots.values():
+            publish(root / "complete.json", encode(result))
+        self.sync_export_roots(roots)
+        self.require_fences(digest)
+        self.clear_matching_fences(digest)
+        return result
+
+    @staticmethod
+    def same_origin(first: dict[str, Any], second: dict[str, Any]) -> bool:
+        return all(
+            first[key] == second[key]
+            for key in [
+                "id",
+                "owner_id",
+                "tool_call_id",
+                "endpoint",
+                "resource_id",
+                "operation",
+                "target",
+                "requested_path",
+            ]
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("operation", choices=["preview", "apply"])
+    parser.add_argument("--manifest", required=True)
+    parser.add_argument("--confirm")
+    args = parser.parse_args()
+    try:
+        archive = JournalArchive(args.manifest)
+        with archive.locked(args.confirm):
+            if args.operation == "apply":
+                if args.confirm is None:
+                    raise ValueError(
+                        "Inspect preview and confirm its exact digest before archival"
+                    )
+                result = archive.apply(args.confirm)
+                print(json.dumps(result))
+            else:
+                print(json.dumps({"ok": True, "preview": archive.preview()}))
+    except (
+        ValueError,
+        OSError,
+        KeyError,
+        TypeError,
+        subprocess.SubprocessError,
+    ) as error:
+        print(json.dumps({"ok": False, "error": str(error)}))
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()