mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/generation_receipt.py

@@ -0,0 +1,1607 @@
+"""The composite generation receipt, and the bounded reads every stage of it is built from.
+
+One provider-scale generation is produced by three separate mutations -- harvest, author, publish
+-- and the only durable evidence a downstream verifier may read is the composite receipt this module
+composes.  It is authoritative rather than descriptive: it carries the *exact bytes* of the harvest
+and author receipts it was handed, together with their fingerprints, so nothing downstream has to
+reconstruct a stage from counts somebody transcribed.
+
+Every untrusted evidence document that reaches it is opened the same way.  The parent chain is
+walked with ``O_DIRECTORY|O_NOFOLLOW`` and retained, the final component is opened
+``O_NOFOLLOW``, the descriptor is confirmed to be a single-link regular file inside its byte cap,
+the bytes are read through that one descriptor, and the descriptor's identity is confirmed
+unchanged afterwards.  A link, a swap during the read, a directory, a device, or one byte over the
+cap is a refusal before anything is parsed.  The sole narrower exception is a wheel-installed
+distribution member: installers may hardlink an authenticated cache member into ``site-packages``,
+so that reader permits a regular hardlink while retaining the same no-follow, bounded, stable
+descriptor checks; the resulting complete distribution digest must still equal the exact wheel
+coordinate.
+
+The caps below are fixed.  There is deliberately no argument anywhere on the three commands that
+widens one: a caller who could raise the composite-receipt ceiling could publish evidence nobody
+can read back inside the budget the reader states.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import errno
+import fcntl
+import hashlib
+import importlib.metadata as metadata
+import io
+import os
+import stat
+import zipfile
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_canonical_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+
+#: The composite receipt this module composes, and the two stage receipts it binds.
+GENERATION_RECEIPT_SCHEMA = "mr-data-catalog-generation.v1"
+HARVEST_RECEIPT_SCHEMA = "mr-data-catalog-harvest.v1"
+HARVEST_PREFLIGHT_SCHEMA = "mr-data-catalog-harvest-preflight.v1"
+
+#: The committed tree one generation was produced from: wheel inputs, product source, tests,
+#: verifier scripts, the Makefile and the lock. It deliberately names no narrative document.
+EXECUTION_COORDINATE_SCHEMA = "mr-data-execution-coordinate.v1"
+
+# --- the fixed caps, none of which any caller may widen ------------------------------------------
+
+MAX_STAGE_RECEIPT_BYTES = 8_388_608
+MAX_STAGE_RECEIPT_DEPTH = 16
+MAX_STAGE_RECEIPT_MEMBERS = 512
+MAX_STAGE_RECEIPT_ITEMS = 1024
+
+MAX_EXECUTION_MANIFEST_BYTES = 16_777_216
+MAX_EXECUTION_MANIFEST_DEPTH = 8
+MAX_EXECUTION_MANIFEST_FILES = 20_000
+MAX_EXECUTION_PATH_BYTES = 512
+MAX_DISTRIBUTION_FILES = 10_000
+MAX_DISTRIBUTION_MEMBER_BYTES = 33_554_432
+MAX_DISTRIBUTION_TOTAL_BYTES = 33_554_432
+MAX_DISTRIBUTION_COMPRESSED_BYTES = 67_108_864
+# One expansion guard, shared with every other archive this package screens: an archive
+# may not inflate past this floor unless it stays within this ratio of its packed size.
+ARCHIVE_EXPANSION_FLOOR_BYTES = 4_194_304
+ARCHIVE_EXPANSION_RATIO = 100
+MAX_WHEEL_BYTES = 67_108_864
+
+MAX_PREDECESSOR_HEAD_BYTES = 4_194_304
+MAX_PREDECESSOR_HEAD_DEPTH = 16
+MAX_PREDECESSOR_RANGE_DESCRIPTORS = 1024
+
+MAX_RANGE_MANIFEST_BYTES = 65_536
+MAX_RANGE_MANIFEST_MEMBERS = 24
+
+MAX_COMPOSITE_RECEIPT_BYTES = 33_554_432
+MAX_COMPOSITE_RECEIPT_DEPTH = 20
+MAX_COMPOSITE_RANGE_DESCRIPTORS = 1024
+MAX_COMPOSITE_ARRAY_ITEMS = 8192
+
+_OPEN_MEMBER = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
+_OPEN_DIRECTORY = (
+    os.O_RDONLY
+    | getattr(os, "O_DIRECTORY", 0)
+    | getattr(os, "O_NOFOLLOW", 0)
+    | getattr(os, "O_CLOEXEC", 0)
+)
+_OPEN_LOCK = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
+
+
+@dataclass(frozen=True)
+class ReceiptInstallation:
+    """The exact receipt parent retained for one locked mutation window."""
+
+    destination: Path
+    parent_descriptor: int
+    parent_identity: tuple[int, int]
+    name: str
+
+
+_ACTIVE_RECEIPT_INSTALLATIONS: ContextVar[tuple[ReceiptInstallation, ...]] = ContextVar(
+    "active_receipt_installations", default=()
+)
+
+
+class GenerationReceiptRefused(SourceContractError):
+    """A stable refusal of a bounded input, an execution coordinate, or a composite receipt."""
+
+
+def _absolute_path(path: Path) -> Path:
+    raw = os.fspath(path)
+    if not raw or "\x00" in raw:
+        raise OSError
+    return Path(os.path.abspath(raw))
+
+
+def _open_directory_chain(path: Path, *, create: bool = False) -> list[int]:
+    """Open one absolute directory path without following any component."""
+
+    absolute = _absolute_path(path)
+    descriptors = [os.open("/", _OPEN_DIRECTORY)]
+    try:
+        for component in absolute.parts[1:]:
+            parent = descriptors[-1]
+            if create:
+                try:
+                    os.mkdir(component, mode=0o700, dir_fd=parent)
+                except FileExistsError:
+                    pass
+            descriptors.append(os.open(component, _OPEN_DIRECTORY, dir_fd=parent))
+    except BaseException:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+        raise
+    return descriptors
+
+
+def _same_identity(left: os.stat_result, right: os.stat_result) -> bool:
+    return (left.st_dev, left.st_ino, left.st_size, left.st_mtime_ns, left.st_ctime_ns) == (
+        right.st_dev,
+        right.st_ino,
+        right.st_size,
+        right.st_mtime_ns,
+        right.st_ctime_ns,
+    )
+
+
+@contextmanager
+def publication_output_lock(
+    root: Path,
+    *,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+) -> Iterator[int]:
+    """Retain and exclusively lock one private no-follow publication root."""
+
+    descriptors: list[int] = []
+    lock_descriptor: int | None = None
+    try:
+        absolute = _absolute_path(root)
+        if absolute == Path("/"):
+            raise OSError
+        descriptors = _open_directory_chain(absolute.parent, create=True)
+        parent_descriptor = descriptors[-1]
+        name = absolute.name
+        if name in {"", ".", ".."}:
+            raise OSError
+        # Lock a stable parent/name coordinate. Locking the root inode itself would let a rename
+        # plus replacement create a second lock domain at the same pathname.
+        lock_descriptor = os.open(
+            f".{name}.publication.lock", _OPEN_LOCK, 0o600, dir_fd=parent_descriptor
+        )
+        lock_info = os.fstat(lock_descriptor)
+        if not stat.S_ISREG(lock_info.st_mode) or lock_info.st_nlink != 1:
+            raise OSError
+        os.fchmod(lock_descriptor, 0o600)
+        fcntl.flock(lock_descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        try:
+            os.mkdir(name, mode=0o700, dir_fd=parent_descriptor)
+        except FileExistsError:
+            pass
+        root_descriptor = os.open(name, _OPEN_DIRECTORY, dir_fd=parent_descriptor)
+        descriptors.append(root_descriptor)
+        info = os.fstat(root_descriptor)
+        if not stat.S_ISDIR(info.st_mode):
+            raise OSError
+        os.fchmod(root_descriptor, 0o700)
+    except OSError as error:
+        if lock_descriptor is not None:
+            try:
+                fcntl.flock(lock_descriptor, fcntl.LOCK_UN)
+            except OSError:
+                pass
+            os.close(lock_descriptor)
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+        code = (
+            f"{code_prefix}_OUTPUT_LOCKED"
+            if error.errno in {errno.EACCES, errno.EAGAIN}
+            else f"{code_prefix}_OUTPUT_PATH"
+        )
+        detail = (
+            "another invocation owns this output root"
+            if code.endswith("_LOCKED")
+            else "output root must be a retained no-follow directory path"
+        )
+        raise refusal(
+            code,
+            label,
+            detail,
+        ) from error
+    try:
+        require_output_root_identity(
+            absolute,
+            root_descriptor,
+            label=label,
+            code_prefix=code_prefix,
+            refusal=refusal,
+        )
+        yield root_descriptor
+    finally:
+        assert lock_descriptor is not None
+        fcntl.flock(lock_descriptor, fcntl.LOCK_UN)
+        os.close(lock_descriptor)
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+
+
+def require_output_root_identity(
+    root: Path,
+    descriptor: int,
+    *,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+) -> None:
+    """Require the named root to remain the exact retained, no-follow directory."""
+
+    try:
+        named = os.stat(_absolute_path(root), follow_symlinks=False)
+        retained = os.fstat(descriptor)
+    except OSError as error:
+        raise refusal(
+            f"{code_prefix}_OUTPUT_PATH",
+            label,
+            "output root no longer names the retained directory",
+        ) from error
+    if (
+        not stat.S_ISDIR(named.st_mode)
+        or not stat.S_ISDIR(retained.st_mode)
+        or (named.st_dev, named.st_ino) != (retained.st_dev, retained.st_ino)
+    ):
+        raise refusal(
+            f"{code_prefix}_OUTPUT_PATH",
+            label,
+            "output root no longer names the retained directory",
+        )
+
+
+@contextmanager
+def retained_child_directory(
+    parent_descriptor: int,
+    name: str,
+    *,
+    create: bool,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+) -> Iterator[int]:
+    """Open one private child relative to a retained parent, without reopening its pathname."""
+
+    descriptor = -1
+    try:
+        if not name or name in {".", ".."} or "/" in name or "\x00" in name:
+            raise OSError
+        if create:
+            try:
+                os.mkdir(name, mode=0o700, dir_fd=parent_descriptor)
+            except FileExistsError:
+                pass
+        descriptor = os.open(name, _OPEN_DIRECTORY, dir_fd=parent_descriptor)
+        info = os.fstat(descriptor)
+        if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) & 0o077:
+            raise OSError
+    except OSError as error:
+        if descriptor >= 0:
+            os.close(descriptor)
+        raise refusal(
+            f"{code_prefix}_OUTPUT_PATH", label, "output child must be a private directory"
+        ) from error
+    try:
+        yield descriptor
+    finally:
+        os.close(descriptor)
+
+
+@contextmanager
+def retained_input_directory(
+    root: Path,
+    *,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+) -> Iterator[int]:
+    """Retain one existing private input root without following any path component."""
+
+    descriptors: list[int] = []
+    try:
+        descriptors = _open_directory_chain(root)
+        descriptor = descriptors[-1]
+        info = os.fstat(descriptor)
+        if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) & 0o077:
+            raise OSError
+    except OSError as error:
+        for opened in reversed(descriptors):
+            os.close(opened)
+        raise refusal(
+            f"{code_prefix}_INPUT_PATH",
+            label,
+            "input root must be an existing retained private no-follow directory",
+        ) from error
+    try:
+        yield descriptor
+    finally:
+        for opened in reversed(descriptors):
+            os.close(opened)
+
+
+@contextmanager
+def receipt_installation_lock(
+    path: Path,
+    *,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+) -> Iterator[ReceiptInstallation]:
+    """Exclude another cooperative writer for the receipt's whole mutation window."""
+
+    descriptors: list[int] = []
+    try:
+        destination = _absolute_path(path)
+        descriptors = _open_directory_chain(destination.parent)
+        descriptor = descriptors[-1]
+        opened = os.fstat(descriptor)
+        if not stat.S_ISDIR(opened.st_mode):
+            raise OSError
+        name = destination.name
+        if name in {"", ".", ".."}:
+            raise OSError
+        fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError as error:
+        for opened_descriptor in reversed(descriptors):
+            os.close(opened_descriptor)
+        raise refusal(
+            f"{code_prefix}_RECEIPT_LOCKED",
+            label,
+            "another invocation owns this receipt destination",
+        ) from error
+    installation = ReceiptInstallation(
+        destination=destination,
+        parent_descriptor=descriptor,
+        parent_identity=(opened.st_dev, opened.st_ino),
+        name=name,
+    )
+    token = _ACTIVE_RECEIPT_INSTALLATIONS.set((*_ACTIVE_RECEIPT_INSTALLATIONS.get(), installation))
+    try:
+        _require_receipt_parent_identity(
+            installation, label=label, code_prefix=code_prefix, refusal=refusal
+        )
+        yield installation
+    finally:
+        _ACTIVE_RECEIPT_INSTALLATIONS.reset(token)
+        fcntl.flock(descriptor, fcntl.LOCK_UN)
+        for opened_descriptor in reversed(descriptors):
+            os.close(opened_descriptor)
+
+
+def _require_receipt_parent_identity(
+    installation: ReceiptInstallation,
+    *,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError],
+) -> None:
+    """Require the receipt pathname to retain the locked parent directory."""
+
+    try:
+        retained = os.fstat(installation.parent_descriptor)
+        # The named-parent lookup is deliberately last. Callers use this helper as their final
+        # filesystem operation before reporting success, so no retained-descriptor observation may
+        # follow and hide a pathname replacement that happened during it.
+        named = os.stat(installation.destination.parent, follow_symlinks=False)
+    except OSError as error:
+        raise refusal(
+            f"{code_prefix}_RECEIPT_DESTINATION",
+            label,
+            "receipt parent no longer names the retained locked directory",
+        ) from error
+    if (
+        not stat.S_ISDIR(named.st_mode)
+        or not stat.S_ISDIR(retained.st_mode)
+        or (named.st_dev, named.st_ino) != installation.parent_identity
+        or (retained.st_dev, retained.st_ino) != installation.parent_identity
+    ):
+        raise refusal(
+            f"{code_prefix}_RECEIPT_DESTINATION",
+            label,
+            "receipt parent no longer names the retained locked directory",
+        )
+
+
+def is_digest(value: Any) -> bool:
+    """Whether this value is a lowercase SHA-256, which is the only fingerprint spelling here."""
+
+    return (
+        isinstance(value, str) and len(value) == 64 and all(c in "0123456789abcdef" for c in value)
+    )
+
+
+def is_commit(value: Any) -> bool:
+    """Whether this value is a full lowercase 40-character commit identifier."""
+
+    return (
+        isinstance(value, str) and len(value) == 40 and all(c in "0123456789abcdef" for c in value)
+    )
+
+
+# ------------------------------------------------------------------------------------------------
+# Bounded reads
+# ------------------------------------------------------------------------------------------------
+
+
+def read_bounded_document(path: Path, *, maximum: int, label: str) -> bytes:
+    """Read one document through a retained no-follow parent chain and a stable descriptor.
+
+    The name is resolved component by component so that no directory in the chain may be a link
+    swapped underneath the read, and the file's own identity is compared before and after: a
+    document that moved while it was being read never becomes evidence.
+    """
+
+    raw_path = os.fspath(path)
+    if not raw_path or "\x00" in raw_path:
+        raise GenerationReceiptRefused("GENERATION_INPUT_PATH", label, "path is not a usable name")
+    absolute = Path(os.path.abspath(raw_path))
+    if absolute.name in {"", ".", ".."}:
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_PATH", label, "path does not name one document"
+        )
+    owned: list[int] = []
+    descriptor = -1
+    try:
+        parent = os.open("/", _OPEN_DIRECTORY)
+        owned.append(parent)
+        for component in absolute.parts[1:-1]:
+            parent = os.open(component, _OPEN_DIRECTORY, dir_fd=parent)
+            owned.append(parent)
+        descriptor = os.open(absolute.name, _OPEN_MEMBER, dir_fd=parent)
+    except OSError as error:
+        for opened in reversed(owned):
+            os.close(opened)
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_PATH",
+            label,
+            "must be reachable without following one link, from a retained parent",
+        ) from error
+    try:
+        before = os.fstat(descriptor)
+        if not stat.S_ISREG(before.st_mode) or before.st_nlink != 1:
+            raise GenerationReceiptRefused(
+                "GENERATION_INPUT_PATH", label, "must be a single-link regular file"
+            )
+        if before.st_size > maximum:
+            raise GenerationReceiptRefused(
+                "GENERATION_INPUT_LIMIT", label, f"must be at most {maximum} bytes"
+            )
+        chunks: list[bytes] = []
+        remaining = maximum + 1
+        while remaining > 0:
+            chunk = os.read(descriptor, min(remaining, 1 << 16))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        after = os.fstat(descriptor)
+        if (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 GenerationReceiptRefused(
+                "GENERATION_INPUT_RACE", label, "document changed while it was being read"
+            )
+    finally:
+        os.close(descriptor)
+        for opened in reversed(owned):
+            os.close(opened)
+    raw = b"".join(chunks)
+    if len(raw) > maximum:
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_LIMIT", label, f"must be at most {maximum} bytes"
+        )
+    return raw
+
+
+def _read_installed_distribution_member(path: Path, *, maximum: int, label: str) -> bytes:
+    """Read one installer-owned member without rejecting a legitimate cache hardlink.
+
+    Unlike :func:`read_bounded_document`, this helper is used only for the closed
+    ``importlib.metadata`` distribution inventory that is subsequently compared with the exact
+    wheel coordinate. It deliberately permits ``st_nlink > 1`` because uv and other installers
+    may install wheel payloads by hardlink. It still refuses symlinks and special files, retains
+    every no-follow parent descriptor, enforces the byte cap, and requires the complete file
+    identity (including link count and ctime) and its current parent binding to remain stable
+    during the read.
+    """
+
+    raw_path = os.fspath(path)
+    if not raw_path or "\x00" in raw_path:
+        raise GenerationReceiptRefused("GENERATION_INPUT_PATH", label, "path is not a usable name")
+    absolute = Path(os.path.abspath(raw_path))
+    if absolute.name in {"", ".", ".."}:
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_PATH", label, "path does not name one document"
+        )
+    owned: list[int] = []
+    descriptor = -1
+    try:
+        parent = os.open("/", _OPEN_DIRECTORY)
+        owned.append(parent)
+        for component in absolute.parts[1:-1]:
+            parent = os.open(component, _OPEN_DIRECTORY, dir_fd=parent)
+            owned.append(parent)
+        descriptor = os.open(
+            absolute.name,
+            _OPEN_MEMBER | getattr(os, "O_NONBLOCK", 0),
+            dir_fd=parent,
+        )
+    except OSError as error:
+        for opened in reversed(owned):
+            os.close(opened)
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_PATH",
+            label,
+            "must be reachable without following one link, from a retained parent",
+        ) from error
+    try:
+        before = os.fstat(descriptor)
+        if not stat.S_ISREG(before.st_mode) or before.st_nlink < 1:
+            raise GenerationReceiptRefused(
+                "GENERATION_INPUT_PATH", label, "must be a regular installed file"
+            )
+        if before.st_size > maximum:
+            raise GenerationReceiptRefused(
+                "GENERATION_INPUT_LIMIT", label, f"must be at most {maximum} bytes"
+            )
+        chunks: list[bytes] = []
+        remaining = maximum + 1
+        while remaining > 0:
+            chunk = os.read(descriptor, min(remaining, 1 << 16))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        after = os.fstat(descriptor)
+        before_identity = (
+            before.st_dev,
+            before.st_ino,
+            before.st_mode,
+            before.st_nlink,
+            before.st_size,
+            before.st_mtime_ns,
+            before.st_ctime_ns,
+        )
+        after_identity = (
+            after.st_dev,
+            after.st_ino,
+            after.st_mode,
+            after.st_nlink,
+            after.st_size,
+            after.st_mtime_ns,
+            after.st_ctime_ns,
+        )
+        raw = b"".join(chunks)
+        current_chain: list[int] = []
+        try:
+            current_chain = _open_directory_chain(absolute.parent)
+            current_parent = os.fstat(current_chain[-1])
+            captured_parent = os.fstat(owned[-1])
+            current_member = os.stat(
+                absolute.name,
+                dir_fd=current_chain[-1],
+                follow_symlinks=False,
+            )
+        except OSError as error:
+            raise GenerationReceiptRefused(
+                "GENERATION_INPUT_RACE", label, "installed file path changed while it was read"
+            ) from error
+        finally:
+            for opened in reversed(current_chain):
+                os.close(opened)
+        current_identity = (
+            current_member.st_dev,
+            current_member.st_ino,
+            current_member.st_mode,
+            current_member.st_nlink,
+            current_member.st_size,
+            current_member.st_mtime_ns,
+            current_member.st_ctime_ns,
+        )
+        if (
+            before_identity != after_identity
+            or current_identity != after_identity
+            or (current_parent.st_dev, current_parent.st_ino)
+            != (captured_parent.st_dev, captured_parent.st_ino)
+            or len(raw) != before.st_size
+        ):
+            raise GenerationReceiptRefused(
+                "GENERATION_INPUT_RACE", label, "installed file or path changed while it was read"
+            )
+        return raw
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        for opened in reversed(owned):
+            os.close(opened)
+
+
+def enforce_shape(
+    value: Any,
+    *,
+    label: str,
+    max_depth: int,
+    max_members: int,
+    max_items: int,
+    code: str = "GENERATION_INPUT_SHAPE",
+) -> None:
+    """Refuse a parsed document deeper, wider, or longer than its stated structural bounds."""
+
+    stack: list[tuple[Any, int]] = [(value, 1)]
+    while stack:
+        current, depth = stack.pop()
+        if depth > max_depth:
+            raise GenerationReceiptRefused(code, label, f"nesting exceeds {max_depth} levels")
+        if isinstance(current, Mapping):
+            if len(current) > max_members:
+                raise GenerationReceiptRefused(
+                    code, label, f"an object exceeds {max_members} members"
+                )
+            stack.extend((member, depth + 1) for member in current.values())
+        elif isinstance(current, Sequence) and not isinstance(current, str | bytes | bytearray):
+            if len(current) > max_items:
+                raise GenerationReceiptRefused(code, label, f"an array exceeds {max_items} items")
+            stack.extend((member, depth + 1) for member in current)
+
+
+def load_bounded_json(
+    path: Path,
+    *,
+    label: str,
+    maximum: int,
+    max_depth: int,
+    max_members: int,
+    max_items: int,
+    expected_sha256: str | None = None,
+    shape_code: str = "GENERATION_INPUT_SHAPE",
+) -> tuple[bytes, dict[str, Any]]:
+    """Read, fingerprint, parse, and shape-check one bounded canonical JSON document."""
+
+    if expected_sha256 is not None and not is_digest(expected_sha256):
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_DIGEST", label, "must be a lowercase SHA-256"
+        )
+    raw = read_bounded_document(path, maximum=maximum, label=label)
+    if expected_sha256 is not None and sha256_bytes(raw) != expected_sha256:
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_DIGEST", label, "document bytes differ from the required digest"
+        )
+    try:
+        parsed = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise GenerationReceiptRefused(
+            shape_code, label, "document is not canonical JSON"
+        ) from error
+    if not isinstance(parsed, dict):
+        raise GenerationReceiptRefused(shape_code, label, "document must be one JSON object")
+    enforce_shape(
+        parsed,
+        label=label,
+        max_depth=max_depth,
+        max_members=max_members,
+        max_items=max_items,
+        code=shape_code,
+    )
+    return raw, parsed
+
+
+def load_bounded_json_at(
+    parent_descriptor: int,
+    name: str,
+    *,
+    label: str,
+    maximum: int,
+    max_depth: int,
+    max_members: int,
+    max_items: int,
+    shape_code: str = "GENERATION_INPUT_SHAPE",
+) -> tuple[bytes, dict[str, Any]]:
+    """Read one bounded canonical JSON member relative to an already retained directory."""
+
+    try:
+        raw, _identity = _read_bounded_at(parent_descriptor, name, maximum=maximum)
+    except OSError as error:
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_PATH", label, "member is not a bounded single-link regular file"
+        ) from error
+    try:
+        parsed = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise GenerationReceiptRefused(
+            shape_code, label, "document is not canonical JSON"
+        ) from error
+    if not isinstance(parsed, dict):
+        raise GenerationReceiptRefused(shape_code, label, "document must be one JSON object")
+    enforce_shape(
+        parsed,
+        label=label,
+        max_depth=max_depth,
+        max_members=max_members,
+        max_items=max_items,
+        code=shape_code,
+    )
+    return raw, parsed
+
+
+def load_stage_receipt(
+    path: Path,
+    expected_sha256: str,
+    *,
+    label: str,
+    schemas: frozenset[str],
+) -> tuple[bytes, dict[str, Any]]:
+    """One component receipt, read under the fixed stage caps and its caller-retained digest."""
+
+    raw, payload = load_bounded_json(
+        path,
+        label=label,
+        maximum=MAX_STAGE_RECEIPT_BYTES,
+        max_depth=MAX_STAGE_RECEIPT_DEPTH,
+        max_members=MAX_STAGE_RECEIPT_MEMBERS,
+        max_items=MAX_STAGE_RECEIPT_ITEMS,
+        expected_sha256=expected_sha256,
+    )
+    if payload.get("schema_version") not in schemas:
+        raise GenerationReceiptRefused(
+            "GENERATION_INPUT_SCHEMA", label, "receipt does not name one accepted stage schema"
+        )
+    return raw, payload
+
+
+def load_execution_coordinate(path: Path, expected_commit: str) -> dict[str, Any]:
+    """The committed tree this generation was produced from, named by its own exact commit."""
+
+    if not is_commit(expected_commit):
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_COMMIT",
+            "execution_commit",
+            "must be a full lowercase 40-character commit",
+        )
+    _raw, payload = load_bounded_json(
+        path,
+        label="execution_manifest",
+        maximum=MAX_EXECUTION_MANIFEST_BYTES,
+        max_depth=MAX_EXECUTION_MANIFEST_DEPTH,
+        max_members=MAX_EXECUTION_MANIFEST_FILES,
+        max_items=MAX_EXECUTION_MANIFEST_FILES,
+        shape_code="GENERATION_EXECUTION_SHAPE",
+    )
+    if payload.get("schema_version") != EXECUTION_COORDINATE_SCHEMA:
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_SHAPE",
+            "execution_manifest",
+            "manifest does not name the execution coordinate schema",
+        )
+    files = payload.get("files")
+    if not isinstance(files, list) or not files or len(files) > MAX_EXECUTION_MANIFEST_FILES:
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_SHAPE",
+            "execution_manifest.files",
+            f"must name 1 to {MAX_EXECUTION_MANIFEST_FILES} committed files",
+        )
+    seen: set[str] = set()
+    for index, item in enumerate(files):
+        member = f"execution_manifest.files[{index}]"
+        if not isinstance(item, dict) or set(item) != {"path", "sha256"}:
+            raise GenerationReceiptRefused(
+                "GENERATION_EXECUTION_SHAPE", member, "each file is one path and one fingerprint"
+            )
+        name = item["path"]
+        if (
+            not isinstance(name, str)
+            or not name
+            or len(name.encode("utf-8")) > MAX_EXECUTION_PATH_BYTES
+            or name in seen
+        ):
+            raise GenerationReceiptRefused(
+                "GENERATION_EXECUTION_SHAPE",
+                member,
+                f"each path is stated once and is at most {MAX_EXECUTION_PATH_BYTES} bytes",
+            )
+        seen.add(name)
+        if not is_digest(item["sha256"]):
+            raise GenerationReceiptRefused(
+                "GENERATION_EXECUTION_SHAPE", member, "each file states a lowercase SHA-256"
+            )
+    body = {key: value for key, value in payload.items() if key != "root_sha256"}
+    if payload.get("root_sha256") != canonical_sha256(body):
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_SHAPE",
+            "execution_manifest.root_sha256",
+            "the manifest does not reproduce its own root fingerprint",
+        )
+    if payload.get("commit") != expected_commit:
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_COMMIT",
+            "execution_manifest.commit",
+            "the manifest was written for another execution commit",
+        )
+    coordinate: dict[str, Any] = {
+        "commit": expected_commit,
+        "root_sha256": payload["root_sha256"],
+        "file_count": len(files),
+    }
+    installed = payload.get("installed_runtime")
+    if installed is not None:
+        if not isinstance(installed, dict) or set(installed) != {
+            "wheel_sha256",
+            "distribution_sha256",
+            "distribution_file_count",
+        }:
+            raise GenerationReceiptRefused(
+                "GENERATION_EXECUTION_SHAPE",
+                "execution_manifest.installed_runtime",
+                "installed runtime must be one exact wheel/distribution coordinate",
+            )
+        for member in ("wheel_sha256", "distribution_sha256"):
+            if not is_digest(installed.get(member)):
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_SHAPE",
+                    f"execution_manifest.installed_runtime.{member}",
+                    "must be a lowercase SHA-256",
+                )
+        count = installed.get("distribution_file_count")
+        if type(count) is not int or count <= 0 or count > MAX_DISTRIBUTION_FILES:
+            raise GenerationReceiptRefused(
+                "GENERATION_EXECUTION_SHAPE",
+                "execution_manifest.installed_runtime.distribution_file_count",
+                "must be a positive bounded file count",
+            )
+        observed = installed_distribution_coordinate()
+        if observed != {
+            "distribution_sha256": installed["distribution_sha256"],
+            "distribution_file_count": count,
+        }:
+            raise GenerationReceiptRefused(
+                "GENERATION_EXECUTION_DISTRIBUTION",
+                "execution_manifest.installed_runtime",
+                "the executing installed distribution differs from the wheel coordinate",
+            )
+        coordinate["installed_runtime"] = dict(installed)
+    return coordinate
+
+
+def _distribution_member(path: str, dist_info: str) -> bool:
+    if path.startswith("mostlyright/"):
+        return True
+    if not path.startswith(f"{dist_info}/"):
+        return False
+    relative = path[len(dist_info) + 1 :]
+    return relative not in {
+        "RECORD",
+        "INSTALLER",
+        "REQUESTED",
+        "direct_url.json",
+        "uv_cache.json",
+    }
+
+
+def _distribution_coordinate(files: Sequence[Mapping[str, str]], version: str) -> dict[str, Any]:
+    ordered = sorted((dict(item) for item in files), key=lambda item: item["path"])
+    if not ordered or len(ordered) > MAX_DISTRIBUTION_FILES:
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_DISTRIBUTION",
+            "installed_runtime.distribution",
+            "the installed distribution file inventory is absent or over its cap",
+        )
+    body = {"name": "mostlyright-data", "version": version, "files": ordered}
+    return {
+        "distribution_sha256": canonical_sha256(body),
+        "distribution_file_count": len(ordered),
+    }
+
+
+def wheel_runtime_coordinate(
+    path: Path, *, expected_product_sha256s: Mapping[str, str] | None = None
+) -> dict[str, Any]:
+    """Fingerprint one wheel and the portable distribution bytes it must install."""
+
+    try:
+        wheel_raw = read_bounded_document(path, maximum=MAX_WHEEL_BYTES, label="installed_wheel")
+        with zipfile.ZipFile(io.BytesIO(wheel_raw)) as archive:
+            names = archive.namelist()
+            if len(names) != len(set(names)):
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_DISTRIBUTION",
+                    "installed_wheel",
+                    "wheel carries duplicate member names",
+                )
+            records = [name for name in names if name.endswith(".dist-info/RECORD")]
+            if len(records) != 1 or len(names) > MAX_DISTRIBUTION_FILES:
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_DISTRIBUTION",
+                    "installed_wheel",
+                    "wheel must carry one bounded distribution RECORD",
+                )
+            dist_info = records[0].split("/", 1)[0]
+            for info in archive.infolist():
+                name = info.filename
+                member_type = stat.S_IFMT(info.external_attr >> 16)
+                if (
+                    "\\" in name
+                    or name.startswith("/")
+                    or "//" in name
+                    or any(part in {".", ".."} for part in name.split("/"))
+                    or not (name.startswith("mostlyright/") or name.startswith(f"{dist_info}/"))
+                    or member_type not in {0, stat.S_IFREG, stat.S_IFDIR}
+                    or bool(info.flag_bits & 0x1)
+                ):
+                    raise GenerationReceiptRefused(
+                        "GENERATION_EXECUTION_DISTRIBUTION",
+                        "installed_wheel",
+                        "wheel carries a payload outside its closed installed roots",
+                    )
+            metadata_name = f"{dist_info}/METADATA"
+            version = ""
+            if metadata_name in names:
+                for line in archive.read(metadata_name).decode("utf-8").splitlines():
+                    if line.startswith("Version: "):
+                        version = line.removeprefix("Version: ").strip()
+                        break
+            if not version:
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_DISTRIBUTION",
+                    "installed_wheel",
+                    "wheel metadata states no distribution version",
+                )
+            selected_infos: list[zipfile.ZipInfo] = []
+            total_bytes = 0
+            total_compressed_bytes = 0
+            for name in names:
+                if not _distribution_member(name, dist_info):
+                    continue
+                info = archive.getinfo(name)
+                if info.is_dir() or info.file_size > MAX_DISTRIBUTION_MEMBER_BYTES:
+                    raise GenerationReceiptRefused(
+                        "GENERATION_EXECUTION_DISTRIBUTION",
+                        "installed_wheel",
+                        "wheel distribution member is not a bounded regular payload",
+                    )
+                total_bytes += info.file_size
+                total_compressed_bytes += info.compress_size
+                selected_infos.append(info)
+            if (
+                total_bytes > MAX_DISTRIBUTION_TOTAL_BYTES
+                or total_compressed_bytes > MAX_DISTRIBUTION_COMPRESSED_BYTES
+                or total_bytes
+                > max(
+                    ARCHIVE_EXPANSION_FLOOR_BYTES,
+                    total_compressed_bytes * ARCHIVE_EXPANSION_RATIO,
+                )
+            ):
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_DISTRIBUTION",
+                    "installed_wheel",
+                    "wheel distribution exceeds its aggregate expansion budget",
+                )
+            selected = [
+                {"path": info.filename, "sha256": sha256_bytes(archive.read(info))}
+                for info in selected_infos
+            ]
+            if expected_product_sha256s is not None:
+                actual_product_sha256s = {
+                    info.filename: sha256_bytes(archive.read(info))
+                    for info in selected_infos
+                    if info.filename.startswith("mostlyright/")
+                }
+                if not expected_product_sha256s or actual_product_sha256s != dict(
+                    expected_product_sha256s
+                ):
+                    raise GenerationReceiptRefused(
+                        "GENERATION_EXECUTION_SOURCE",
+                        "installed_wheel",
+                        "wheel product bytes differ from the committed source coordinate",
+                    )
+    except GenerationReceiptRefused:
+        raise
+    except (OSError, zipfile.BadZipFile, UnicodeError) as error:
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_DISTRIBUTION",
+            "installed_wheel",
+            "wheel is not a readable installed distribution",
+        ) from error
+    return {
+        "wheel_sha256": hashlib.sha256(wheel_raw).hexdigest(),
+        **_distribution_coordinate(selected, version),
+    }
+
+
+def installed_distribution_coordinate() -> dict[str, Any]:
+    """Fingerprint the wheel-owned bytes and refuse an editable/source-tree import."""
+
+    try:
+        distribution = metadata.distribution("mostlyright-data")
+        root = Path(distribution.locate_file("")).resolve(strict=True)
+        origin = Path(__file__).resolve(strict=True)
+        origin.relative_to(root)
+        if not ({"site-packages", "dist-packages"} & set(root.parts)):
+            raise ValueError
+        paths = [item.as_posix() for item in distribution.files or ()]
+        records = [path for path in paths if path.endswith(".dist-info/RECORD")]
+        if len(records) != 1:
+            raise ValueError
+        dist_info = records[0].split("/", 1)[0]
+        selected: list[dict[str, str]] = []
+        total_bytes = 0
+        for name in paths:
+            if not _distribution_member(name, dist_info):
+                continue
+            member = Path(distribution.locate_file(name))
+            try:
+                member.resolve(strict=True).relative_to(root)
+            except (OSError, ValueError):
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_DISTRIBUTION",
+                    "installed_runtime.distribution",
+                    "installed distribution member escapes its package root",
+                ) from None
+            raw = _read_installed_distribution_member(
+                member,
+                maximum=MAX_DISTRIBUTION_MEMBER_BYTES,
+                label="installed_distribution.member",
+            )
+            total_bytes += len(raw)
+            if total_bytes > MAX_DISTRIBUTION_TOTAL_BYTES:
+                raise GenerationReceiptRefused(
+                    "GENERATION_EXECUTION_DISTRIBUTION",
+                    "installed_runtime.distribution",
+                    "installed distribution exceeds its aggregate byte budget",
+                )
+            selected.append({"path": name, "sha256": sha256_bytes(raw)})
+    except (OSError, ValueError, metadata.PackageNotFoundError) as error:
+        raise GenerationReceiptRefused(
+            "GENERATION_EXECUTION_DISTRIBUTION",
+            "installed_runtime.distribution",
+            "catalog execution must originate from one installed wheel distribution",
+        ) from error
+    return _distribution_coordinate(selected, distribution.version)
+
+
+def root_coordinate(root: Path) -> str:
+    """One output root's coordinate: the digest of its resolved name, never the name itself.
+
+    A receipt binds the root it describes so that a resume cannot be pointed at another one, and a
+    digest binds it without writing an executor-local absolute path into durable evidence.
+    """
+
+    return canonical_sha256({"output_root": str(_absolute_path(root))})
+
+
+# ------------------------------------------------------------------------------------------------
+# Installing a receipt, and replacing exactly one typed-incomplete predecessor
+# ------------------------------------------------------------------------------------------------
+
+
+def install_receipt(
+    path: Path,
+    payload: Mapping[str, Any],
+    *,
+    maximum: int,
+    label: str,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+    replaces: Mapping[str, Any] | None = None,
+    installation: ReceiptInstallation | None = None,
+    commit_guard: Callable[[], None] | None = None,
+) -> bytes:
+    """Install one complete receipt with append-only failure handling.
+
+    Every invocation first fsyncs the complete bytes under a unique private name. Publication is
+    one atomic no-replace rename, so the authoritative name is absent or complete. Replacement
+    first moves the exact authorized predecessor into immutable history. A failed post-install
+    guard moves the visible bytes to a unique quarantine and restores the predecessor without
+    overwriting or deleting any name. Private remnants are never authoritative and never block a
+    retry. The final descriptor/name identity check is the last filesystem action before success.
+    """
+
+    destination = _absolute_path(path)
+    if installation is None:
+        installation = next(
+            (
+                active
+                for active in reversed(_ACTIVE_RECEIPT_INSTALLATIONS.get())
+                if active.destination == destination
+            ),
+            None,
+        )
+    if installation is None:
+        with receipt_installation_lock(
+            destination, label=label, code_prefix=code_prefix, refusal=refusal
+        ) as retained_parent:
+            return install_receipt(
+                destination,
+                payload,
+                maximum=maximum,
+                label=label,
+                code_prefix=code_prefix,
+                refusal=refusal,
+                replaces=replaces,
+                installation=retained_parent,
+                commit_guard=commit_guard,
+            )
+    if installation.destination != destination:
+        raise refusal(
+            f"{code_prefix}_RECEIPT_DESTINATION",
+            label,
+            "receipt installation does not own this destination",
+        )
+
+    raw = canonical_json_bytes(payload)
+    if len(raw) > maximum:
+        raise refusal(f"{code_prefix}_RECEIPT_LIMIT", label, "receipt exceeds its byte bound")
+    parent_descriptor = installation.parent_descriptor
+    name = installation.name
+    staged = _private_receipt_name(name, "staging", sha256_bytes(raw))
+    retained_name: str | None = None
+    predecessor_source: str | None = None
+    predecessor_claimed = False
+    published = False
+    installed_identity: os.stat_result | None = None
+    try:
+        _require_receipt_parent_identity(
+            installation, label=label, code_prefix=code_prefix, refusal=refusal
+        )
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+        descriptor = os.open(staged, flags, 0o600, dir_fd=parent_descriptor)
+        _write_all(descriptor, raw)
+        staged_raw, staged_identity = _read_bounded_at(parent_descriptor, staged, maximum=maximum)
+        staged_named_identity = os.stat(staged, dir_fd=parent_descriptor, follow_symlinks=False)
+        if staged_raw != raw or not _same_identity(staged_identity, staged_named_identity):
+            raise refusal(
+                f"{code_prefix}_RECEIPT_READBACK",
+                label,
+                "private receipt staging changed before publication",
+            )
+        if commit_guard is not None:
+            commit_guard()
+        if replaces is not None:
+            expected = replaces.get("receipt_sha256")
+            if not is_digest(expected):
+                raise refusal(
+                    f"{code_prefix}_RESUME_RECEIPT",
+                    label,
+                    "the retained receipt has no exact fingerprint",
+                )
+            retained_name = f".{name}.retained.{expected}"
+            current, current_identity = _read_bounded_at(parent_descriptor, name, maximum=maximum)
+            if sha256_bytes(current) != expected:
+                raise refusal(
+                    f"{code_prefix}_RESUME_RECEIPT",
+                    label,
+                    "the retained receipt changed before replacement",
+                )
+            named_identity = os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+            if not _same_identity(current_identity, named_identity):
+                raise refusal(
+                    f"{code_prefix}_RESUME_RECEIPT",
+                    label,
+                    "the retained receipt changed before replacement",
+                )
+            _require_receipt_parent_identity(
+                installation, label=label, code_prefix=code_prefix, refusal=refusal
+            )
+            claim_name = _private_receipt_name(name, "predecessor", expected)
+            _rename_noreplace(parent_descriptor, name, claim_name)
+            predecessor_claimed = True
+            predecessor_source = claim_name
+            os.fsync(parent_descriptor)
+            claimed, claimed_identity = _read_bounded_at(
+                parent_descriptor, claim_name, maximum=maximum
+            )
+            claimed_named_identity = os.stat(
+                claim_name, dir_fd=parent_descriptor, follow_symlinks=False
+            )
+            if (
+                claimed != current
+                or sha256_bytes(claimed) != expected
+                or (current_identity.st_dev, current_identity.st_ino)
+                != (claimed_identity.st_dev, claimed_identity.st_ino)
+                or not _same_identity(claimed_identity, claimed_named_identity)
+            ):
+                raise refusal(
+                    f"{code_prefix}_RESUME_RECEIPT",
+                    label,
+                    "the retained receipt changed before replacement",
+                )
+            try:
+                _rename_noreplace(parent_descriptor, claim_name, retained_name)
+                predecessor_source = retained_name
+                os.fsync(parent_descriptor)
+            except OSError as error:
+                if error.errno != errno.EEXIST:
+                    raise
+            archived, archived_identity = _read_bounded_at(
+                parent_descriptor, retained_name, maximum=maximum
+            )
+            archived_named_identity = os.stat(
+                retained_name, dir_fd=parent_descriptor, follow_symlinks=False
+            )
+            if (
+                archived != current
+                or sha256_bytes(archived) != expected
+                or not _same_identity(archived_identity, archived_named_identity)
+            ):
+                raise refusal(
+                    f"{code_prefix}_RESUME_RECEIPT",
+                    label,
+                    "the retained receipt archive differs from the authorized predecessor",
+                )
+        _require_receipt_parent_identity(
+            installation, label=label, code_prefix=code_prefix, refusal=refusal
+        )
+        _rename_noreplace(parent_descriptor, staged, name)
+        published = True
+        os.fsync(parent_descriptor)
+        installed, installed_identity = _read_bounded_at(parent_descriptor, name, maximum=maximum)
+        if installed != raw:
+            raise refusal(
+                f"{code_prefix}_RECEIPT_READBACK", label, "installed receipt readback differs"
+            )
+        _require_receipt_parent_identity(
+            installation, label=label, code_prefix=code_prefix, refusal=refusal
+        )
+        if commit_guard is not None:
+            commit_guard()
+        final, final_identity = _read_bounded_at(parent_descriptor, name, maximum=maximum)
+        if (
+            final != raw
+            or installed_identity is None
+            or not _same_identity(installed_identity, final_identity)
+        ):
+            raise refusal(
+                f"{code_prefix}_RECEIPT_READBACK",
+                label,
+                "installed receipt changed before commit completed",
+            )
+        final_named_identity = os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+        if not _same_identity(final_identity, final_named_identity):
+            raise refusal(
+                f"{code_prefix}_RECEIPT_READBACK",
+                label,
+                "installed receipt changed before commit completed",
+            )
+        _require_receipt_parent_identity(
+            installation, label=label, code_prefix=code_prefix, refusal=refusal
+        )
+        return raw
+    except (OSError, SourceContractError) as error:
+        try:
+            if published:
+                _quarantine_receipt(
+                    parent_descriptor,
+                    name,
+                    maximum=maximum,
+                )
+            if predecessor_claimed:
+                assert predecessor_source is not None
+                _restore_receipt_from_history(
+                    parent_descriptor,
+                    predecessor_source,
+                    name,
+                    maximum=maximum,
+                )
+        except OSError as recovery_error:
+            code = (
+                f"{code_prefix}_RESUME_RECEIPT"
+                if replaces is not None
+                else f"{code_prefix}_RECEIPT_DESTINATION"
+            )
+            raise refusal(
+                code,
+                label,
+                "receipt publication failed and its prior visible state could not be restored",
+            ) from recovery_error
+        if isinstance(error, SourceContractError):
+            raise
+        code = (
+            f"{code_prefix}_RESUME_RECEIPT"
+            if replaces is not None
+            else f"{code_prefix}_RECEIPT_DESTINATION"
+        )
+        detail = (
+            "the retained receipt changed before replacement"
+            if replaces is not None
+            else "receipt destination must be an absent no-follow path"
+        )
+        raise refusal(code, label, detail) from error
+
+
+def _private_receipt_name(destination: str, role: str, digest: str) -> str:
+    """Return an invocation-private, non-authoritative member name."""
+
+    return f".{destination}.{role}.{digest}.{os.urandom(16).hex()}"
+
+
+def _quarantine_receipt(parent: int, destination: str, *, maximum: int) -> str | None:
+    """Move the current public name into append-only quarantine without deleting its bytes."""
+
+    quarantine = _private_receipt_name(destination, "quarantine", os.urandom(32).hex())
+    try:
+        _rename_noreplace(parent, destination, quarantine)
+    except FileNotFoundError:
+        return None
+    os.fsync(parent)
+    _raw, identity = _read_bounded_at(parent, quarantine, maximum=maximum)
+    named_identity = os.stat(quarantine, dir_fd=parent, follow_symlinks=False)
+    if not _same_identity(identity, named_identity):
+        raise OSError(errno.EIO, "quarantined receipt changed")
+    return quarantine
+
+
+def _restore_receipt_from_history(
+    parent: int,
+    source: str,
+    destination: str,
+    *,
+    maximum: int,
+) -> None:
+    """Copy immutable predecessor bytes through a private stage and restore them no-replace."""
+
+    raw, source_identity = _read_bounded_at(parent, source, maximum=maximum)
+    source_named_identity = os.stat(source, dir_fd=parent, follow_symlinks=False)
+    if not _same_identity(source_identity, source_named_identity):
+        raise OSError(errno.EIO, "receipt history changed")
+    staged = _private_receipt_name(destination, "restoring", sha256_bytes(raw))
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(staged, flags, 0o600, dir_fd=parent)
+    _write_all(descriptor, raw)
+    staged_raw, staged_identity = _read_bounded_at(parent, staged, maximum=maximum)
+    staged_named_identity = os.stat(staged, dir_fd=parent, follow_symlinks=False)
+    if staged_raw != raw or not _same_identity(staged_identity, staged_named_identity):
+        raise OSError(errno.EIO, "receipt restoration stage changed")
+    _rename_noreplace(parent, staged, destination)
+    os.fsync(parent)
+    restored, restored_identity = _read_bounded_at(parent, destination, maximum=maximum)
+    restored_named_identity = os.stat(destination, dir_fd=parent, follow_symlinks=False)
+    if restored != raw or not _same_identity(restored_identity, restored_named_identity):
+        raise OSError(errno.EIO, "restored receipt changed")
+
+
+def _rename_noreplace(parent: int, source: str, destination: str) -> None:
+    """Rename one regular member only when the destination is absent."""
+
+    library = ctypes.CDLL(None, use_errno=True)
+    source_bytes = os.fsencode(source)
+    destination_bytes = os.fsencode(destination)
+    if hasattr(library, "renameat2"):
+        rename = library.renameat2
+        rename.argtypes = [
+            ctypes.c_int,
+            ctypes.c_char_p,
+            ctypes.c_int,
+            ctypes.c_char_p,
+            ctypes.c_uint,
+        ]
+        rename.restype = ctypes.c_int
+        result = rename(parent, source_bytes, parent, destination_bytes, 1)
+    elif hasattr(library, "renameatx_np"):
+        rename = library.renameatx_np
+        rename.argtypes = [
+            ctypes.c_int,
+            ctypes.c_char_p,
+            ctypes.c_int,
+            ctypes.c_char_p,
+            ctypes.c_uint,
+        ]
+        rename.restype = ctypes.c_int
+        result = rename(parent, source_bytes, parent, destination_bytes, 4)
+    else:
+        raise OSError(errno.ENOTSUP, "atomic no-replace rename is unavailable")
+    if result != 0:
+        value = ctypes.get_errno()
+        raise OSError(value, os.strerror(value), destination)
+
+
+def _read_bounded_at(parent: int, name: str, *, maximum: int) -> tuple[bytes, os.stat_result]:
+    descriptor = os.open(name, _OPEN_MEMBER, dir_fd=parent)
+    try:
+        before = os.fstat(descriptor)
+        if not stat.S_ISREG(before.st_mode) or before.st_nlink != 1 or before.st_size > maximum:
+            raise OSError
+        chunks: list[bytes] = []
+        remaining = maximum + 1
+        while remaining > 0:
+            chunk = os.read(descriptor, min(remaining, 1 << 16))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        after = os.fstat(descriptor)
+        if not _same_identity(before, after):
+            raise OSError
+        raw = b"".join(chunks)
+        if len(raw) > maximum:
+            raise OSError
+        return raw, after
+    finally:
+        os.close(descriptor)
+
+
+def _write_all(descriptor: int, raw: bytes) -> None:
+    try:
+        written = 0
+        while written < len(raw):
+            count = os.write(descriptor, raw[written:])
+            if count <= 0:
+                raise OSError(errno.EIO, "receipt write made no progress")
+            written += count
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def retained_incomplete_receipt(
+    path: Path,
+    *,
+    maximum: int,
+    label: str,
+    schema: str,
+    incomplete_status: str,
+    output_root: Path,
+    code_prefix: str,
+    refusal: type[SourceContractError] = GenerationReceiptRefused,
+) -> dict[str, Any] | None:
+    """The typed-incomplete receipt a resume is allowed to replace, or ``None`` if there is none.
+
+    A resume that finds nothing at the destination is an ordinary first write.  A resume that
+    finds a receipt which is complete, written under another schema, or bound to another output
+    root is refused rather than overwritten: replacing evidence is only ever allowed to continue
+    the exact interrupted invocation that wrote it.
+    """
+
+    try:
+        raw = read_bounded_document(Path(path), maximum=maximum, label=label)
+    except GenerationReceiptRefused as error:
+        if error.code == "GENERATION_INPUT_PATH" and not Path(path).exists():
+            return None
+        raise
+    try:
+        payload = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise refusal(
+            f"{code_prefix}_RESUME_RECEIPT", label, "retained receipt is not canonical JSON"
+        ) from error
+    if (
+        not isinstance(payload, dict)
+        or payload.get("schema_version") != schema
+        or payload.get("status") != incomplete_status
+    ):
+        raise refusal(
+            f"{code_prefix}_RECEIPT_DESTINATION",
+            label,
+            "only this stage's own typed-incomplete receipt may be replaced",
+        )
+    if payload.get("output_root_sha256") != root_coordinate(output_root):
+        raise refusal(
+            f"{code_prefix}_RESUME_RECEIPT",
+            label,
+            "the retained typed-incomplete receipt describes another output root",
+        )
+    return {**payload, "receipt_sha256": sha256_bytes(raw)}
+
+
+# ------------------------------------------------------------------------------------------------
+# The composite receipt
+# ------------------------------------------------------------------------------------------------
+
+
+def compose_generation_receipt(body: Mapping[str, Any]) -> dict[str, Any]:
+    """Seal one composite receipt: shape-check it, then bind it under its own coordinate."""
+
+    payload = {key: value for key, value in body.items() if key != "coordinate_sha256"}
+    enforce_shape(
+        payload,
+        label="generation_receipt",
+        max_depth=MAX_COMPOSITE_RECEIPT_DEPTH,
+        max_members=MAX_COMPOSITE_ARRAY_ITEMS,
+        max_items=MAX_COMPOSITE_ARRAY_ITEMS,
+        code="GENERATION_RECEIPT_SHAPE",
+    )
+    receipt = {**payload, "coordinate_sha256": canonical_sha256(payload)}
+    raw = canonical_json_bytes(receipt)
+    if len(raw) > MAX_COMPOSITE_RECEIPT_BYTES:
+        raise GenerationReceiptRefused(
+            "GENERATION_RECEIPT_LIMIT",
+            "generation_receipt",
+            f"the composite receipt is at most {MAX_COMPOSITE_RECEIPT_BYTES} bytes",
+        )
+    return receipt
+
+
+def verify_generation_receipt(receipt: Mapping[str, Any]) -> None:
+    """Re-derive one composite receipt against itself: schema, shape, and its own coordinate.
+
+    This is the check that costs no I/O.  It says the document in front of you is a whole
+    composite receipt that reproduces its own fingerprint -- not that the generation it describes
+    is still installed, which is what the readback block inside it is for.
+    """
+
+    if not isinstance(receipt, Mapping):
+        raise GenerationReceiptRefused(
+            "GENERATION_RECEIPT_SCHEMA", "generation_receipt", "must be one object"
+        )
+    if receipt.get("schema_version") != GENERATION_RECEIPT_SCHEMA:
+        raise GenerationReceiptRefused(
+            "GENERATION_RECEIPT_SCHEMA", "generation_receipt", "receipt names another schema"
+        )
+    for member in (
+        "status",
+        "components",
+        "execution",
+        "staging",
+        "policy",
+        "author",
+        "classification",
+        "publication",
+        "readback",
+        "limits",
+        "coordinate_sha256",
+    ):
+        if member not in receipt:
+            raise GenerationReceiptRefused(
+                "GENERATION_RECEIPT_SCHEMA",
+                f"generation_receipt.{member}",
+                "a composite receipt states every one of its blocks",
+            )
+    body = {key: value for key, value in receipt.items() if key != "coordinate_sha256"}
+    enforce_shape(
+        body,
+        label="generation_receipt",
+        max_depth=MAX_COMPOSITE_RECEIPT_DEPTH,
+        max_members=MAX_COMPOSITE_ARRAY_ITEMS,
+        max_items=MAX_COMPOSITE_ARRAY_ITEMS,
+        code="GENERATION_RECEIPT_SHAPE",
+    )
+    components = receipt["components"]
+    for stage in ("harvest", "author"):
+        embedded = components.get(f"{stage}_receipt")
+        stated = components.get(f"{stage}_receipt_sha256")
+        if not isinstance(embedded, Mapping) or not is_digest(stated):
+            raise GenerationReceiptRefused(
+                "GENERATION_RECEIPT_COMPONENT",
+                f"generation_receipt.components.{stage}_receipt",
+                "a composite receipt carries each component receipt and its exact fingerprint",
+            )
+        if sha256_bytes(canonical_json_bytes(embedded)) != stated:
+            raise GenerationReceiptRefused(
+                "GENERATION_RECEIPT_COMPONENT",
+                f"generation_receipt.components.{stage}_receipt",
+                "the carried receipt is not the bytes its fingerprint names",
+            )
+    ranges = receipt["publication"].get("range_manifest_sha256s", ())
+    if not isinstance(ranges, list) or len(ranges) > MAX_COMPOSITE_RANGE_DESCRIPTORS:
+        raise GenerationReceiptRefused(
+            "GENERATION_RECEIPT_SHAPE",
+            "generation_receipt.publication.range_manifest_sha256s",
+            f"a generation states at most {MAX_COMPOSITE_RANGE_DESCRIPTORS} ranges",
+        )
+    if receipt["coordinate_sha256"] != canonical_sha256(body):
+        raise GenerationReceiptRefused(
+            "GENERATION_RECEIPT_COORDINATE",
+            "generation_receipt.coordinate_sha256",
+            "the receipt does not reproduce its own coordinate",
+        )