mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/update.py

@@ -0,0 +1,891 @@
+"""Installing a published catalog generation onto this computer, with no service in between.
+
+A generation is distributed as one zip archive whose exact SHA-256 the operator publishes next
+to it. The archive holds the generation's folder under one ``catalog/`` prefix plus one
+``release.json`` naming the store kind, the store file's digest, and the digest of the store file
+this release descends from. Trust flows from exactly two places and nowhere else: the archive
+digest the person typed, and the state this computer recorded when it installed the current
+generation. There is no ambient discovery, no version service, and no clock: everything verified
+here is a pure function of the archive bytes, the arguments, and the recorded state.
+
+The descent statement is cross-checked against the store itself for a packed generation, whose
+head names its own predecessor. A v2 retrieval store carries no predecessor field, so for that
+kind the statement stands on the packaging invocation alone, bound by the archive digest: it is
+the packager's word, published under the digest the person typed.
+
+Installation is append-only. Each generation lands in its own folder named by its store digest,
+written under a private staging name, verified in place by the real store loading -- the same
+checks a search performs -- and only then made visible by one atomic rename; the recorded state
+is replaced through the same append-only receipt discipline the publish lane uses, so the
+previous state is retained rather than overwritten. A destination folder that already holds this
+generation -- retained from an earlier install -- is re-verified and adopted rather than refused,
+so rolling back to a retained generation and retrying after an interrupted state write both work.
+
+The archive is screened the way the execution-coordinate wheel is screened: member names are
+refused rather than sanitised (no absolute names, no ``..`` parts, no backslashes, no folder
+members, no duplicate names -- including names that collide once case or accent normalisation is
+applied, because the destination filesystem may apply either -- no links or special files, no
+encrypted members), and byte budgets bound every member, the whole expansion, and the expansion
+ratio, so a hostile archive is refused before a byte of it reaches the destination folder.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import re
+import stat
+import unicodedata
+import zipfile
+import zlib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    parse_canonical_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.readers.containers import read_bounded, screen_zip_entry
+from mostlyright.data_harness.readers.contracts import ReaderError
+from mostlyright.data_harness.sources.catalog.generation_receipt import (
+    ARCHIVE_EXPANSION_FLOOR_BYTES,
+    ARCHIVE_EXPANSION_RATIO,
+    install_receipt,
+    is_digest,
+    read_bounded_document,
+)
+from mostlyright.data_harness.sources.catalog.packed_catalog import (
+    MAX_PACKED_HEAD_BYTES,
+    PACKED_HEAD_FILENAME,
+    verify_packed_generation,
+)
+from mostlyright.data_harness.sources.catalog.packed_retrieval import detect_public_store_kind
+from mostlyright.data_harness.sources.catalog.retrieval_manifest import (
+    MAX_RETRIEVAL_MANIFEST_BYTES,
+    RETRIEVAL_MANIFEST_FILENAME,
+    load_retrieval_catalog,
+)
+from mostlyright.data_harness.sources.contracts import (
+    SourceContractError,
+    require_canonical_timestamp,
+)
+
+__all__ = [
+    "ARCHIVE_MEMBER_PREFIX",
+    "GENERATIONS_DIRNAME",
+    "INSTALLED_STATE_FILENAME",
+    "INSTALLED_STATE_SCHEMA",
+    "MAX_RELEASE_ARCHIVE_BYTES",
+    "RELEASE_DESCRIPTOR_FILENAME",
+    "RELEASE_DESCRIPTOR_SCHEMA",
+    "SUPPORTED_STORE_KINDS",
+    "CatalogUpdateReport",
+    "InstalledState",
+    "ReleaseDescriptor",
+    "build_release_archive",
+    "confirm_already_current",
+    "install_release",
+    "load_installed_state",
+    "verify_release_archive",
+]
+
+RELEASE_DESCRIPTOR_FILENAME = "release.json"
+RELEASE_DESCRIPTOR_SCHEMA = "mr-data-catalog-release.v1"
+INSTALLED_STATE_FILENAME = "installed.json"
+INSTALLED_STATE_SCHEMA = "mr-data-catalog-installed.v1"
+GENERATIONS_DIRNAME = "generations"
+ARCHIVE_MEMBER_PREFIX = "catalog/"
+SUPPORTED_STORE_KINDS = ("packed", "retrieval_v2")
+
+MAX_RELEASE_ARCHIVE_BYTES = 1_073_741_824
+MAX_RELEASE_MEMBER_BYTES = 268_435_456
+MAX_RELEASE_MEMBER_COUNT = 50_000
+MAX_RELEASE_DESCRIPTOR_BYTES = 4_096
+MAX_INSTALLED_STATE_BYTES = 65_536
+MAX_RELEASE_ENTRY_COUNT = 10_000_000
+MAX_MEMBER_NAME_PARTS = 16
+MAX_MEMBER_NAME_PART_LENGTH = 255
+
+_STORE_FILENAMES = {
+    "packed": PACKED_HEAD_FILENAME,
+    "retrieval_v2": RETRIEVAL_MANIFEST_FILENAME,
+}
+_STORE_FILE_MAXIMUMS = {
+    "packed": MAX_PACKED_HEAD_BYTES,
+    "retrieval_v2": MAX_RETRIEVAL_MANIFEST_BYTES,
+}
+_RELEASE_DESCRIPTOR_KEYS = frozenset(
+    {
+        "entry_count",
+        "predecessor_store_sha256",
+        "published_at",
+        "schema_version",
+        "store_kind",
+        "store_sha256",
+    }
+)
+_INSTALLED_STATE_KEYS = frozenset(
+    {
+        "archive_sha256",
+        "entry_count",
+        "generation_path",
+        "predecessor_store_sha256",
+        "published_at",
+        "schema_version",
+        "store_kind",
+        "store_sha256",
+    }
+)
+# A generation folder is named by the first twelve characters of its store digest and by
+# nothing else, so the recorded path is a closed shape rather than a screened one.
+_GENERATION_FOLDER_PATTERN = re.compile(r"[0-9a-f]{12}")
+
+
+def _refuse(code: str, path: str, detail: str) -> SourceContractError:
+    return SourceContractError(code, path, detail)
+
+
+def _require_release_facts(
+    *,
+    store_kind: str,
+    store_sha256: str,
+    predecessor_store_sha256: str | None,
+    entry_count: int,
+    published_at: str,
+    code: str,
+    path: str,
+) -> None:
+    """The field rules a release statement and a recorded install state share."""
+
+    if store_kind not in SUPPORTED_STORE_KINDS:
+        raise _refuse(
+            "CATALOG_UPDATE_STORE", f"{path}.store_kind", "must name a supported store kind"
+        )
+    if not is_digest(store_sha256):
+        raise _refuse(code, f"{path}.store_sha256", "must be one exact lowercase SHA-256")
+    if predecessor_store_sha256 is not None:
+        if not is_digest(predecessor_store_sha256):
+            raise _refuse(
+                code,
+                f"{path}.predecessor_store_sha256",
+                "must be one exact lowercase SHA-256 or null",
+            )
+        if predecessor_store_sha256 == store_sha256:
+            raise _refuse(
+                code, f"{path}.predecessor_store_sha256", "must not name the release itself"
+            )
+    if (
+        not isinstance(entry_count, int)
+        or isinstance(entry_count, bool)
+        or not 0 <= entry_count <= MAX_RELEASE_ENTRY_COUNT
+    ):
+        raise _refuse(code, f"{path}.entry_count", "must be a bounded whole number")
+    require_canonical_timestamp(published_at, f"{path}.published_at")
+
+
+@dataclass(frozen=True)
+class ReleaseDescriptor:
+    """The one statement a release archive makes about itself."""
+
+    store_kind: str
+    store_sha256: str
+    predecessor_store_sha256: str | None
+    entry_count: int
+    published_at: str
+
+    def __post_init__(self) -> None:
+        _require_release_facts(
+            store_kind=self.store_kind,
+            store_sha256=self.store_sha256,
+            predecessor_store_sha256=self.predecessor_store_sha256,
+            entry_count=self.entry_count,
+            published_at=self.published_at,
+            code="CATALOG_UPDATE_RELEASE",
+            path="release",
+        )
+
+    @classmethod
+    def from_dict(cls, data: Any, *, path: str = "release") -> ReleaseDescriptor:
+        if not isinstance(data, dict):
+            raise _refuse("CATALOG_UPDATE_RELEASE", path, "must be one JSON object")
+        if set(data) != _RELEASE_DESCRIPTOR_KEYS:
+            raise _refuse(
+                "CATALOG_UPDATE_RELEASE",
+                path,
+                "must carry exactly the declared release fields",
+            )
+        if data["schema_version"] != RELEASE_DESCRIPTOR_SCHEMA:
+            raise _refuse(
+                "CATALOG_UPDATE_RELEASE",
+                f"{path}.schema_version",
+                f"must be {RELEASE_DESCRIPTOR_SCHEMA}",
+            )
+        return cls(
+            store_kind=data["store_kind"],
+            store_sha256=data["store_sha256"],
+            predecessor_store_sha256=data["predecessor_store_sha256"],
+            entry_count=data["entry_count"],
+            published_at=data["published_at"],
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": RELEASE_DESCRIPTOR_SCHEMA,
+            "store_kind": self.store_kind,
+            "store_sha256": self.store_sha256,
+            "predecessor_store_sha256": self.predecessor_store_sha256,
+            "entry_count": self.entry_count,
+            "published_at": self.published_at,
+        }
+
+
+@dataclass(frozen=True)
+class InstalledState:
+    """What this computer remembers about the generation it installed."""
+
+    store_kind: str
+    store_sha256: str
+    archive_sha256: str
+    predecessor_store_sha256: str | None
+    entry_count: int
+    published_at: str
+    generation_path: str
+
+    def __post_init__(self) -> None:
+        _require_release_facts(
+            store_kind=self.store_kind,
+            store_sha256=self.store_sha256,
+            predecessor_store_sha256=self.predecessor_store_sha256,
+            entry_count=self.entry_count,
+            published_at=self.published_at,
+            code="CATALOG_UPDATE_STATE",
+            path="installed",
+        )
+        if not is_digest(self.archive_sha256):
+            raise _refuse(
+                "CATALOG_UPDATE_STATE",
+                "installed.archive_sha256",
+                "must be one exact lowercase SHA-256",
+            )
+        prefix = f"{GENERATIONS_DIRNAME}/"
+        folder = (
+            self.generation_path[len(prefix) :]
+            if isinstance(self.generation_path, str) and self.generation_path.startswith(prefix)
+            else ""
+        )
+        if not _GENERATION_FOLDER_PATTERN.fullmatch(folder):
+            raise _refuse(
+                "CATALOG_UPDATE_STATE",
+                "installed.generation_path",
+                "must name one digest-named folder directly under the generations folder",
+            )
+        if not self.store_sha256.startswith(folder):
+            raise _refuse(
+                "CATALOG_UPDATE_STATE",
+                "installed.generation_path",
+                "must be named by the recorded store digest",
+            )
+
+    @classmethod
+    def from_dict(cls, data: Any, *, path: str = "installed") -> InstalledState:
+        if not isinstance(data, dict) or set(data) != _INSTALLED_STATE_KEYS:
+            raise _refuse(
+                "CATALOG_UPDATE_STATE", path, "must carry exactly the recorded install fields"
+            )
+        if data["schema_version"] != INSTALLED_STATE_SCHEMA:
+            raise _refuse(
+                "CATALOG_UPDATE_STATE",
+                f"{path}.schema_version",
+                f"must be {INSTALLED_STATE_SCHEMA}",
+            )
+        return cls(
+            store_kind=data["store_kind"],
+            store_sha256=data["store_sha256"],
+            archive_sha256=data["archive_sha256"],
+            predecessor_store_sha256=data["predecessor_store_sha256"],
+            entry_count=data["entry_count"],
+            published_at=data["published_at"],
+            generation_path=data["generation_path"],
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": INSTALLED_STATE_SCHEMA,
+            "store_kind": self.store_kind,
+            "store_sha256": self.store_sha256,
+            "archive_sha256": self.archive_sha256,
+            "predecessor_store_sha256": self.predecessor_store_sha256,
+            "entry_count": self.entry_count,
+            "published_at": self.published_at,
+            "generation_path": self.generation_path,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogUpdateReport:
+    """The complete account of one install decision."""
+
+    status: str
+    state: InstalledState
+    catalog_root: str
+
+    def to_dict(self) -> dict[str, Any]:
+        generation_root = os.path.join(self.catalog_root, self.state.generation_path)
+        return {
+            "schema_version": "mr-data-catalog-update.v1",
+            "status": self.status,
+            "store_kind": self.state.store_kind,
+            "store_sha256": self.state.store_sha256,
+            "archive_sha256": self.state.archive_sha256,
+            "predecessor_store_sha256": self.state.predecessor_store_sha256,
+            "entry_count": self.state.entry_count,
+            "published_at": self.state.published_at,
+            "catalog_root": self.catalog_root,
+            "generation_root": generation_root,
+            "search": {
+                "public_index_root": generation_root,
+                "public_manifest_sha256": self.state.store_sha256,
+            },
+        }
+
+
+def _screen_member_name(name: str) -> None:
+    """Admit one archive member name, or refuse it outright. Folder members are refused."""
+
+    if "\\" in name:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "member names never contain a backslash")
+    if name.startswith("/") or "//" in name:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "member names are relative and clean")
+    if name.endswith("/"):
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "folder members are not admitted")
+    parts = name.split("/")
+    if len(parts) > MAX_MEMBER_NAME_PARTS:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "member name has too many folders")
+    for part in parts:
+        if part in {"", ".", ".."}:
+            raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "member name has an empty or dot part")
+        if len(part) > MAX_MEMBER_NAME_PART_LENGTH:
+            raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "member name part is too long")
+
+
+def _screen_archive(
+    archive: zipfile.ZipFile,
+) -> tuple[zipfile.ZipInfo, tuple[zipfile.ZipInfo, ...]]:
+    """Screen every member, returning the release descriptor member and the payload members."""
+
+    descriptor_member: zipfile.ZipInfo | None = None
+    payload: list[zipfile.ZipInfo] = []
+    # Duplicates are judged after case folding and accent normalisation because the destination
+    # filesystem may apply either: two names this set cannot tell apart cannot both land.
+    seen: set[str] = set()
+    total_bytes = 0
+    total_compressed = 0
+    for info in archive.infolist():
+        name = info.filename
+        _screen_member_name(name)
+        folded = unicodedata.normalize("NFC", name).casefold()
+        if folded in seen:
+            raise _refuse(
+                "CATALOG_UPDATE_ARCHIVE",
+                name,
+                "member name appears more than once, or collides with another on a filesystem "
+                "that folds case or accents",
+            )
+        seen.add(folded)
+        try:
+            screen_zip_entry(info, subject=name, described="release archive member")
+        except ReaderError as error:
+            raise _refuse(
+                "CATALOG_UPDATE_ARCHIVE", name, "member is not one plain admissible file"
+            ) from error
+        if info.file_size > MAX_RELEASE_MEMBER_BYTES:
+            raise _refuse("CATALOG_UPDATE_ARCHIVE", name, "member is larger than the bound")
+        total_bytes += info.file_size
+        total_compressed += info.compress_size
+        if name == RELEASE_DESCRIPTOR_FILENAME:
+            if info.file_size > MAX_RELEASE_DESCRIPTOR_BYTES:
+                raise _refuse(
+                    "CATALOG_UPDATE_ARCHIVE", name, "release statement is larger than the bound"
+                )
+            descriptor_member = info
+            continue
+        if not name.startswith(ARCHIVE_MEMBER_PREFIX) or len(name) <= len(ARCHIVE_MEMBER_PREFIX):
+            raise _refuse(
+                "CATALOG_UPDATE_ARCHIVE",
+                name,
+                "every payload member lives under the catalog prefix",
+            )
+        payload.append(info)
+    if len(payload) > MAX_RELEASE_MEMBER_COUNT:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE", "archive", "archive holds more members than the bound"
+        )
+    if total_bytes > MAX_RELEASE_ARCHIVE_BYTES:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", "archive", "archive expands past the byte bound")
+    if total_bytes > max(ARCHIVE_EXPANSION_FLOOR_BYTES, total_compressed * ARCHIVE_EXPANSION_RATIO):
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE", "archive", "archive expands out of proportion to its size"
+        )
+    if descriptor_member is None:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE", RELEASE_DESCRIPTOR_FILENAME, "release statement is missing"
+        )
+    if not payload:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", "archive", "archive holds no catalog members")
+    return descriptor_member, tuple(payload)
+
+
+def _read_member(archive: zipfile.ZipFile, info: zipfile.ZipInfo) -> bytes:
+    """Read one screened member, holding it to its declared size exactly.
+
+    The archive digest covers the packed bytes, not the unpacking: a member whose stream is
+    corrupt, or whose checksum disagrees, is a typed refusal rather than a crash.
+    """
+
+    try:
+        with archive.open(info) as handle:
+            return read_bounded(handle, declared=info.file_size, subject=info.filename)
+    except ReaderError as error:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE", info.filename, "member bytes differ from the declared size"
+        ) from error
+    except (zipfile.BadZipFile, zlib.error) as error:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE", info.filename, "member bytes are corrupt inside the archive"
+        ) from error
+
+
+def verify_release_archive(
+    raw: bytes, *, expected_archive_sha256: str
+) -> tuple[ReleaseDescriptor, zipfile.ZipFile, tuple[zipfile.ZipInfo, ...]]:
+    """Verify one release archive down to its store file digest, without touching a disk."""
+
+    if not isinstance(raw, bytes):
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", "archive", "archive must be bytes")
+    if len(raw) > MAX_RELEASE_ARCHIVE_BYTES:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", "archive", "archive is larger than the bound")
+    if not is_digest(expected_archive_sha256):
+        raise _refuse(
+            "CATALOG_UPDATE_DIGEST_SPELLING",
+            "expected_archive_sha256",
+            "must be exactly 64 lowercase hex characters",
+        )
+    if sha256_bytes(raw) != expected_archive_sha256:
+        raise _refuse(
+            "CATALOG_UPDATE_DIGEST",
+            "archive",
+            "archive bytes do not match the published SHA-256",
+        )
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(raw))
+    except (zipfile.BadZipFile, ValueError) as error:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", "archive", "archive is not a readable zip") from (
+            error
+        )
+    descriptor_member, payload = _screen_archive(archive)
+    try:
+        descriptor_data = parse_canonical_json(_read_member(archive, descriptor_member))
+    except CanonicalJSONError as error:
+        raise _refuse(
+            "CATALOG_UPDATE_RELEASE",
+            RELEASE_DESCRIPTOR_FILENAME,
+            "release statement is not canonical JSON",
+        ) from error
+    descriptor = ReleaseDescriptor.from_dict(descriptor_data)
+    store_name = ARCHIVE_MEMBER_PREFIX + _STORE_FILENAMES[descriptor.store_kind]
+    store_member = next((info for info in payload if info.filename == store_name), None)
+    if store_member is None:
+        raise _refuse(
+            "CATALOG_UPDATE_RELEASE", store_name, "the named store file is not in the archive"
+        )
+    if store_member.file_size > _STORE_FILE_MAXIMUMS[descriptor.store_kind]:
+        raise _refuse("CATALOG_UPDATE_RELEASE", store_name, "store file is larger than its bound")
+    store_raw = _read_member(archive, store_member)
+    if sha256_bytes(store_raw) != descriptor.store_sha256:
+        raise _refuse(
+            "CATALOG_UPDATE_RELEASE",
+            store_name,
+            "store file bytes do not match the release statement",
+        )
+    if descriptor.store_kind == "packed":
+        try:
+            head = parse_canonical_json(store_raw)
+        except CanonicalJSONError as error:
+            raise _refuse(
+                "CATALOG_UPDATE_RELEASE", store_name, "store file is not canonical JSON"
+            ) from error
+        head_predecessor = head.get("predecessor_head_sha256") if isinstance(head, dict) else None
+        if head_predecessor != descriptor.predecessor_store_sha256:
+            raise _refuse(
+                "CATALOG_UPDATE_RELEASE",
+                store_name,
+                "release statement disagrees with the store file about the predecessor",
+            )
+    return descriptor, archive, payload
+
+
+def load_installed_state(root: Path) -> tuple[InstalledState, bytes] | None:
+    """Read the recorded install state under ``root``, or None when nothing is recorded."""
+
+    if not isinstance(root, Path):
+        raise _refuse("CATALOG_UPDATE_STATE", "root", "must be a pathlib.Path")
+    state_path = root / INSTALLED_STATE_FILENAME
+    if not os.path.lexists(state_path):
+        return None
+    try:
+        raw = read_bounded_document(
+            state_path, maximum=MAX_INSTALLED_STATE_BYTES, label="catalog update state"
+        )
+    except SourceContractError as error:
+        raise _refuse(
+            "CATALOG_UPDATE_STATE",
+            str(state_path),
+            "recorded install state could not be read safely",
+        ) from error
+    try:
+        data = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise _refuse(
+            "CATALOG_UPDATE_STATE", str(state_path), "recorded install state is not canonical"
+        ) from error
+    return InstalledState.from_dict(data), raw
+
+
+def _materialize(
+    archive: zipfile.ZipFile,
+    payload: tuple[zipfile.ZipInfo, ...],
+    *,
+    staging: Path,
+) -> None:
+    """Write the payload under the private staging folder, durably, without publishing it."""
+
+    os.makedirs(staging, mode=0o755)
+    try:
+        for info in sorted(payload, key=lambda member: member.filename):
+            relative = info.filename[len(ARCHIVE_MEMBER_PREFIX) :]
+            target = staging.joinpath(*relative.split("/"))
+            os.makedirs(target.parent, mode=0o755, exist_ok=True)
+            data = _read_member(archive, info)
+            descriptor = os.open(
+                target, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o644
+            )
+            try:
+                view = memoryview(data)
+                while view:
+                    written = os.write(descriptor, view)
+                    if written <= 0:
+                        raise _refuse(
+                            "CATALOG_UPDATE_INSTALL",
+                            str(target),
+                            "the destination stopped accepting bytes",
+                        )
+                    view = view[written:]
+                os.fsync(descriptor)
+            finally:
+                os.close(descriptor)
+        for current, _directories, _files in os.walk(staging):
+            dir_fd = os.open(current, os.O_RDONLY)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+    except OSError as error:
+        raise _refuse(
+            "CATALOG_UPDATE_INSTALL", str(staging), "the generation could not be written out"
+        ) from error
+
+
+def _publish(staging: Path, destination: Path, generations_root: Path) -> None:
+    """Make one fully verified staging folder visible under its final name, atomically."""
+
+    try:
+        os.rename(staging, destination)
+        root_fd = os.open(generations_root, os.O_RDONLY)
+        try:
+            os.fsync(root_fd)
+        finally:
+            os.close(root_fd)
+    except OSError as error:
+        raise _refuse(
+            "CATALOG_UPDATE_INSTALL", str(destination), "the generation could not be published"
+        ) from error
+
+
+def _verify_installed_store(
+    root: Path, descriptor: ReleaseDescriptor, *, neural_backend: Any = None
+) -> None:
+    """Run the real store verification over the installed folder, exactly as a search would."""
+
+    kind = detect_public_store_kind(root)
+    if kind != descriptor.store_kind:
+        raise _refuse(
+            "CATALOG_UPDATE_RELEASE",
+            str(root),
+            "installed folder is not the store kind the release names",
+        )
+    if descriptor.store_kind == "packed":
+        verified = verify_packed_generation(root, expected_head_sha256=descriptor.store_sha256)
+        installed_count = verified.entry_count
+    else:
+        loaded = load_retrieval_catalog(
+            root,
+            expected_manifest_sha256=descriptor.store_sha256,
+            neural_backend=neural_backend,
+        )
+        installed_count = len(loaded.lexical.entries)
+    if installed_count != descriptor.entry_count:
+        raise _refuse(
+            "CATALOG_UPDATE_RELEASE",
+            str(root),
+            "installed entry count differs from the release statement",
+        )
+
+
+def confirm_already_current(
+    root: Path, *, expected_archive_sha256: str, neural_backend: Any = None
+) -> CatalogUpdateReport | None:
+    """Answer whether the release named by this digest is already installed, without the archive.
+
+    The recorded state binds the archive digest it was installed from, so equality of the typed
+    digest is enough to know no bytes need to move; the installed folder is still re-verified
+    end to end before "already-current" is claimed.
+    """
+
+    if not is_digest(expected_archive_sha256):
+        raise _refuse(
+            "CATALOG_UPDATE_DIGEST_SPELLING",
+            "expected_archive_sha256",
+            "must be exactly 64 lowercase hex characters",
+        )
+    recorded = load_installed_state(root)
+    if recorded is None:
+        return None
+    state, _state_raw = recorded
+    if state.archive_sha256 != expected_archive_sha256:
+        return None
+    _verify_installed_store(
+        root / state.generation_path,
+        ReleaseDescriptor(
+            store_kind=state.store_kind,
+            store_sha256=state.store_sha256,
+            predecessor_store_sha256=state.predecessor_store_sha256,
+            entry_count=state.entry_count,
+            published_at=state.published_at,
+        ),
+        neural_backend=neural_backend,
+    )
+    return CatalogUpdateReport(status="already-current", state=state, catalog_root=str(root))
+
+
+def install_release(
+    root: Path,
+    raw: bytes,
+    *,
+    expected_archive_sha256: str,
+    replace: bool = False,
+    neural_backend: Any = None,
+) -> CatalogUpdateReport:
+    """Verify one release archive and install it under ``root``, honouring the recorded chain."""
+
+    if not isinstance(root, Path):
+        raise _refuse("CATALOG_UPDATE_INSTALL", "root", "must be a pathlib.Path")
+    recorded = load_installed_state(root)
+    descriptor, archive, payload = verify_release_archive(
+        raw, expected_archive_sha256=expected_archive_sha256
+    )
+    if recorded is not None:
+        state, _state_raw = recorded
+        if state.store_sha256 == descriptor.store_sha256:
+            _verify_installed_store(
+                root / state.generation_path, descriptor, neural_backend=neural_backend
+            )
+            return CatalogUpdateReport(
+                status="already-current", state=state, catalog_root=str(root)
+            )
+        if not replace and descriptor.predecessor_store_sha256 != state.store_sha256:
+            raise _refuse(
+                "CATALOG_UPDATE_CHAIN",
+                str(root / INSTALLED_STATE_FILENAME),
+                "release does not descend from the installed generation",
+            )
+    generation_name = descriptor.store_sha256[:12]
+    generations_root = root / GENERATIONS_DIRNAME
+    os.makedirs(generations_root, exist_ok=True)
+    destination = generations_root / generation_name
+    if os.path.lexists(destination):
+        # The append-only design retains every generation ever installed, so the folder may be
+        # a complete earlier install of this same release -- re-verify and adopt it. Anything
+        # else wearing this name is refused, never overwritten.
+        try:
+            _verify_installed_store(destination, descriptor, neural_backend=neural_backend)
+        except SourceContractError as error:
+            raise _refuse(
+                "CATALOG_UPDATE_INSTALL",
+                str(destination),
+                "a folder with this generation's name is present but is not this release; "
+                "remove it and run the update again",
+            ) from error
+    else:
+        staging = generations_root / f".staging-{generation_name}"
+        if os.path.lexists(staging):
+            raise _refuse(
+                "CATALOG_UPDATE_INSTALL",
+                str(staging),
+                "an unfinished earlier install is in the way; remove it and run the update again",
+            )
+        _materialize(archive, payload, staging=staging)
+        archive.close()
+        _verify_installed_store(staging, descriptor, neural_backend=neural_backend)
+        _publish(staging, destination, generations_root)
+    new_state = InstalledState(
+        store_kind=descriptor.store_kind,
+        store_sha256=descriptor.store_sha256,
+        archive_sha256=expected_archive_sha256,
+        predecessor_store_sha256=descriptor.predecessor_store_sha256,
+        entry_count=descriptor.entry_count,
+        published_at=descriptor.published_at,
+        generation_path=f"{GENERATIONS_DIRNAME}/{generation_name}",
+    )
+    replaces: Mapping[str, Any] | None = None
+    if recorded is not None:
+        replaces = {"receipt_sha256": sha256_bytes(recorded[1])}
+    install_receipt(
+        root / INSTALLED_STATE_FILENAME,
+        new_state.to_dict(),
+        maximum=MAX_INSTALLED_STATE_BYTES,
+        label="catalog update state",
+        code_prefix="CATALOG_UPDATE",
+        refusal=SourceContractError,
+        replaces=replaces,
+    )
+    return CatalogUpdateReport(status="installed", state=new_state, catalog_root=str(root))
+
+
+def _collect_generation_files(generation_root: Path) -> tuple[tuple[str, Path], ...]:
+    """Walk one generation folder, admitting only plain files reached without links.
+
+    Names are screened exactly as the installer will screen them -- with the archive prefix on --
+    so nothing packages here that an installer would refuse there, and the byte bounds are
+    enforced from sizes before any file is read.
+    """
+
+    collected: list[tuple[str, Path]] = []
+    total_bytes = 0
+    for current, directories, files in os.walk(generation_root, followlinks=False):
+        for directory in directories:
+            if stat.S_ISLNK(os.lstat(Path(current) / directory).st_mode):
+                raise _refuse(
+                    "CATALOG_UPDATE_ARCHIVE",
+                    str(Path(current) / directory),
+                    "a folder inside the generation may not be a symbolic link",
+                )
+        directories.sort()
+        for name in sorted(files):
+            full = Path(current) / name
+            probe = os.lstat(full)
+            if not stat.S_ISREG(probe.st_mode):
+                raise _refuse(
+                    "CATALOG_UPDATE_ARCHIVE", str(full), "only plain files can be released"
+                )
+            if probe.st_size > MAX_RELEASE_MEMBER_BYTES:
+                raise _refuse(
+                    "CATALOG_UPDATE_ARCHIVE", str(full), "member is larger than the bound"
+                )
+            total_bytes += probe.st_size
+            relative = full.relative_to(generation_root).as_posix()
+            _screen_member_name(ARCHIVE_MEMBER_PREFIX + relative)
+            collected.append((relative, full))
+    if not collected:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE", str(generation_root), "generation folder holds no files"
+        )
+    if len(collected) > MAX_RELEASE_MEMBER_COUNT:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE",
+            str(generation_root),
+            "generation folder holds more files than the bound",
+        )
+    if total_bytes > MAX_RELEASE_ARCHIVE_BYTES:
+        raise _refuse(
+            "CATALOG_UPDATE_ARCHIVE",
+            str(generation_root),
+            "generation folder is larger than the release bound",
+        )
+    return tuple(sorted(collected))
+
+
+def _write_archive_member(archive: zipfile.ZipFile, name: str, data: bytes) -> None:
+    info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+    info.create_system = 3
+    info.external_attr = (stat.S_IFREG | 0o644) << 16
+    info.compress_type = zipfile.ZIP_STORED
+    archive.writestr(info, data)
+
+
+def build_release_archive(
+    generation_root: Path,
+    *,
+    predecessor_store_sha256: str | None,
+    published_at: str,
+    neural_backend: Any = None,
+) -> tuple[bytes, ReleaseDescriptor]:
+    """Package one verified generation folder into a byte-reproducible release archive.
+
+    Every member is stored uncompressed with fixed metadata, so the archive's SHA-256 is a pure
+    function of the generation's bytes: the same generation packaged on any machine yields the
+    same published digest.
+    """
+
+    kind = detect_public_store_kind(generation_root)
+    if kind not in SUPPORTED_STORE_KINDS:
+        raise _refuse(
+            "CATALOG_UPDATE_STORE", str(generation_root), "must name a supported store kind"
+        )
+    store_raw = read_bounded_document(
+        generation_root / _STORE_FILENAMES[kind],
+        maximum=_STORE_FILE_MAXIMUMS[kind],
+        label="release store file",
+    )
+    store_sha256 = sha256_bytes(store_raw)
+    if kind == "packed":
+        verified = verify_packed_generation(generation_root, expected_head_sha256=store_sha256)
+        entry_count = verified.entry_count
+        head_predecessor = verified.head.get("predecessor_head_sha256")
+        if head_predecessor != predecessor_store_sha256:
+            raise _refuse(
+                "CATALOG_UPDATE_RELEASE",
+                str(generation_root),
+                "stated predecessor disagrees with the store file",
+            )
+    else:
+        loaded = load_retrieval_catalog(
+            generation_root,
+            expected_manifest_sha256=store_sha256,
+            neural_backend=neural_backend,
+        )
+        entry_count = len(loaded.lexical.entries)
+    descriptor = ReleaseDescriptor(
+        store_kind=kind,
+        store_sha256=store_sha256,
+        predecessor_store_sha256=predecessor_store_sha256,
+        entry_count=entry_count,
+        published_at=published_at,
+    )
+    files = _collect_generation_files(generation_root)
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_STORED) as archive:
+        # "catalog/..." sorts before "release.json", and the constant prefix preserves the
+        # files' own order, so writing files first then the statement is the sorted order.
+        for relative, full in files:
+            _write_archive_member(archive, ARCHIVE_MEMBER_PREFIX + relative, full.read_bytes())
+        _write_archive_member(
+            archive, RELEASE_DESCRIPTOR_FILENAME, canonical_json_bytes(descriptor.to_dict())
+        )
+    raw = buffer.getvalue()
+    if len(raw) > MAX_RELEASE_ARCHIVE_BYTES:
+        raise _refuse("CATALOG_UPDATE_ARCHIVE", "archive", "archive is larger than the bound")
+    return raw, descriptor