mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/deletion.py

@@ -0,0 +1,761 @@
+"""Crash-recoverable retention and immutable deletion-status projection."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import stat
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.acquisition.http import (
+    exclusive_content_addressed_name,
+    seal_content_addressed_snapshot,
+)
+from mostlyright.data_harness.acquisition.retention_admission import retention_evidence_root
+from mostlyright.data_harness.canonical import (
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_json,
+)
+from mostlyright.data_harness.formats import SNAPSHOT_SUFFIX_PATTERN
+from mostlyright.data_harness.sources.contracts import (
+    RETENTION_KINDS,
+    DeletedReference,
+    DeletionTombstone,
+    RetentionPolicy,
+    SourceContractError,
+)
+
+# Compiled once at import time, as before, but built from the single closed table so a
+# newly admitted format cannot become parseable while staying invisible to deletion.
+_SNAPSHOT_NAME = re.compile(r"^(?P<digest>[0-9a-f]{64})\.(?:" + SNAPSHOT_SUFFIX_PATTERN + r")$")
+_DELETION_STATUS_VERSION = "harness-source-deletion-status.v1"
+_AUDIT_VERSION = "harness-source-deletion-audit.v1"
+_STATUS_VERSION = "harness-source-availability.v1"
+_KIND_DAYS = {
+    "raw": "raw_days",
+    "derived": "derived_days",
+    "logs": "log_days",
+    "review_evidence": "review_evidence_days",
+}
+assert set(_KIND_DAYS) == set(RETENTION_KINDS), (
+    "retention kinds and their policy day fields must stay in step"
+)
+
+
+@dataclass(frozen=True)
+class RetentionDecision:
+    """Expiry of one evidence kind under a retention policy; derived by retention_decision."""
+
+    evidence_kind: str
+    retained_until: str
+    expired: bool
+    policy_digest: str
+
+
+@dataclass(frozen=True)
+class DeletionOutcome:
+    """Evidence sealed by DeletionCoordinator.delete for one removed snapshot.
+
+    ``status_envelope_path`` names the sealed ``status-<digest>.json`` deletion-status envelope.
+    """
+
+    status_envelope_path: Path
+    tombstone_path: Path
+    audit_path: Path
+    tombstone: DeletionTombstone
+    status: dict[str, Any]
+
+
+class DeletionCoordinator:
+    """Remove only exact content-addressed snapshots after sealing complete references."""
+
+    def __init__(
+        self,
+        *,
+        snapshot_root: Path,
+        evidence_root: Path,
+        failure_injector: Callable[[str], None] | None = None,
+    ) -> None:
+        for name, root in (("snapshot_root", snapshot_root), ("evidence_root", evidence_root)):
+            if not root.is_absolute() or root.is_symlink() or not root.is_dir():
+                raise SourceContractError(
+                    "DELETION_ROOT",
+                    name,
+                    "must be an existing absolute non-symlink directory",
+                )
+        expected_evidence_root = retention_evidence_root(snapshot_root)
+        if evidence_root != expected_evidence_root:
+            raise SourceContractError(
+                "DELETION_ROOT",
+                "evidence_root",
+                "must be the deterministic sibling authority root for snapshot_root",
+            )
+        self._snapshot_root = snapshot_root
+        self._evidence_root = evidence_root
+        self._failure_injector = failure_injector
+
+    def delete(
+        self,
+        *,
+        storage_name: str,
+        content_sha256: str,
+        removed_at: str,
+        reason_code: str,
+        policy: RetentionPolicy,
+        references: tuple[DeletedReference, ...],
+    ) -> DeletionOutcome:
+        match = _SNAPSHOT_NAME.fullmatch(storage_name)
+        if match is None or match.group("digest") != content_sha256:
+            raise SourceContractError(
+                "DELETION_TARGET",
+                "storage_name",
+                "target must be the exact content-addressed snapshot name",
+            )
+        ordered = _complete_reference_set(references)
+        reference_digest = canonical_sha256([item.to_dict() for item in ordered])
+        tombstone = DeletionTombstone(
+            tombstone_id=f"delete.{content_sha256[:24]}",
+            removed_content_sha256=content_sha256,
+            removed_at=removed_at,
+            reason_code=reason_code,
+            policy_digest=policy.digest,
+            complete_reference_set_digest=reference_digest,
+            references=ordered,
+            byte_removal_confirmed=True,
+        )
+        deletion_status = {
+            "schema_version": _DELETION_STATUS_VERSION,
+            "content_sha256": content_sha256,
+            "status": "deletion-pending",
+            "source_access_allowed": False,
+            "refetch_allowed": False,
+            "replay": "unavailable-by-deletion",
+            "removed_at": removed_at,
+            "reason_code": reason_code,
+            "policy_digest": policy.digest,
+            "complete_reference_set_digest": reference_digest,
+            "references": [item.to_dict() for item in ordered],
+            "planned_tombstone_digest": tombstone.digest,
+        }
+        deletion_status_bytes = canonical_json_bytes(deletion_status)
+        deletion_status_name = f"status-{content_sha256}.json"
+        # Held from before the target is opened until after its name is gone. A sealer of this
+        # same name is validating bytes it has open, and an unlink landing between two of its
+        # observations moves st_nlink from 1 to 0 under its descriptor -- the exact refusal issue
+        # #209 reported. Taking the sealer's own per-name lock is what stops the harness racing
+        # itself, in this process and in any other. The evidence envelopes sealed inside this
+        # block take a lock of their own, under the separate evidence root the constructor
+        # requires; that direction is the only nesting in the tree, so nothing waits on a cycle.
+        with exclusive_content_addressed_name(self._snapshot_root, storage_name):
+            target = self._open_validated_snapshot(
+                storage_name=storage_name,
+                content_sha256=content_sha256,
+            )
+            if target is None:
+                if not _keyed_envelope_matches(
+                    self._evidence_root,
+                    content=deletion_status_bytes,
+                    index_name=deletion_status_name,
+                ):
+                    raise SourceContractError(
+                        "DELETION_TARGET",
+                        "snapshot",
+                        "snapshot is absent without exact recoverable deletion-pending evidence",
+                    )
+                status_envelope_path = self._evidence_root / deletion_status_name
+            else:
+                root_fd, descriptor, identity = target
+                try:
+                    self._checkpoint("before_deletion_status")
+                    status_envelope_path = _seal_keyed_envelope(
+                        self._evidence_root,
+                        content=deletion_status_bytes,
+                        index_name=deletion_status_name,
+                    )
+                    self._checkpoint("after_deletion_status")
+                    self._checkpoint("before_unlink")
+                    self._unlink_validated_snapshot(
+                        root_fd=root_fd,
+                        descriptor=descriptor,
+                        storage_name=storage_name,
+                        identity=identity,
+                    )
+                    self._checkpoint("after_unlink")
+                    self._checkpoint("before_snapshot_fsync")
+                    os.fsync(root_fd)
+                    self._checkpoint("after_snapshot_fsync")
+                finally:
+                    os.close(descriptor)
+                    os.close(root_fd)
+
+        self._checkpoint("before_tombstone")
+        tombstone_path = _seal_keyed_envelope(
+            self._evidence_root,
+            content=tombstone.canonical_bytes,
+            index_name=f"tombstone-{content_sha256}.json",
+        )
+        self._checkpoint("after_tombstone")
+        audit = {
+            "schema_version": _AUDIT_VERSION,
+            "event": "source_bytes_deleted",
+            "removed_content_sha256": content_sha256,
+            "removed_at": removed_at,
+            "reason_code": reason_code,
+            "policy_digest": policy.digest,
+            "complete_reference_set_digest": reference_digest,
+            "deletion_status_digest": _path_digest(status_envelope_path),
+            "tombstone_digest": tombstone.digest,
+        }
+        self._checkpoint("before_audit")
+        audit_path = _seal_keyed_envelope(
+            self._evidence_root,
+            content=canonical_json_bytes(audit),
+            index_name=f"audit-{content_sha256}.json",
+        )
+        self._checkpoint("after_audit")
+        status = project_availability(
+            content_sha256=content_sha256,
+            tombstone=tombstone,
+            deletion_status=deletion_status,
+        )
+        return DeletionOutcome(
+            status_envelope_path=status_envelope_path,
+            tombstone_path=tombstone_path,
+            audit_path=audit_path,
+            tombstone=tombstone,
+            status=status,
+        )
+
+    def _checkpoint(self, name: str) -> None:
+        if self._failure_injector is not None:
+            self._failure_injector(name)
+
+    def _open_validated_snapshot(
+        self,
+        *,
+        storage_name: str,
+        content_sha256: str,
+    ) -> tuple[int, int, os.stat_result] | None:
+        directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+        root_fd = os.open(self._snapshot_root, directory_flags)
+        try:
+            try:
+                descriptor = os.open(
+                    storage_name,
+                    os.O_RDONLY
+                    | getattr(os, "O_NOFOLLOW", 0)
+                    | getattr(os, "O_NONBLOCK", 0)
+                    | getattr(os, "O_CLOEXEC", 0),
+                    dir_fd=root_fd,
+                )
+            except FileNotFoundError:
+                os.close(root_fd)
+                return None
+            try:
+                before = os.fstat(descriptor)
+                if not stat.S_ISREG(before.st_mode) or before.st_nlink != 1:
+                    raise SourceContractError(
+                        "DELETION_TARGET",
+                        "snapshot",
+                        "deletion target must be one non-hardlinked regular file",
+                    )
+                observed = _hash_descriptor(descriptor)
+                after = os.fstat(descriptor)
+                if (
+                    observed != content_sha256
+                    or before.st_dev != after.st_dev
+                    or before.st_ino != after.st_ino
+                    or before.st_size != after.st_size
+                    or before.st_mtime_ns != after.st_mtime_ns
+                ):
+                    raise SourceContractError(
+                        "DELETION_TARGET_CHANGED",
+                        "snapshot",
+                        "snapshot identity, bytes, or metadata changed during deletion validation",
+                    )
+                return root_fd, descriptor, before
+            except Exception:
+                os.close(descriptor)
+                raise
+        except Exception:
+            os.close(root_fd)
+            raise
+
+    @staticmethod
+    def _unlink_validated_snapshot(
+        *,
+        root_fd: int,
+        descriptor: int,
+        storage_name: str,
+        identity: os.stat_result,
+    ) -> None:
+        after = os.fstat(descriptor)
+        if (
+            identity.st_dev != after.st_dev
+            or identity.st_ino != after.st_ino
+            or identity.st_size != after.st_size
+            or identity.st_mtime_ns != after.st_mtime_ns
+        ):
+            raise SourceContractError(
+                "DELETION_TARGET_CHANGED",
+                "snapshot",
+                "snapshot identity or metadata changed after deletion evidence was sealed",
+            )
+        try:
+            current = os.stat(storage_name, dir_fd=root_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            raise SourceContractError(
+                "DELETION_TARGET_CHANGED",
+                "snapshot",
+                "snapshot path disappeared after deletion evidence was sealed",
+            ) from None
+        if current.st_dev != identity.st_dev or current.st_ino != identity.st_ino:
+            raise SourceContractError(
+                "DELETION_TARGET_CHANGED",
+                "snapshot",
+                "snapshot path no longer names the validated file",
+            )
+        os.unlink(storage_name, dir_fd=root_fd)
+
+
+def retention_decision(
+    *,
+    evidence_kind: str,
+    ingested_at: str,
+    as_of: str,
+    policy: RetentionPolicy,
+) -> RetentionDecision:
+    """Derive expiry from exact UTC instants and the immutable policy."""
+
+    if evidence_kind not in _KIND_DAYS:
+        raise SourceContractError(
+            "RETENTION_KIND",
+            "evidence_kind",
+            f"must be one of {sorted(_KIND_DAYS)}",
+        )
+    ingested = _utc(ingested_at, "ingested_at")
+    observed = _utc(as_of, "as_of")
+    days = getattr(policy, _KIND_DAYS[evidence_kind])
+    retained_until = ingested + timedelta(days=days)
+    return RetentionDecision(
+        evidence_kind=evidence_kind,
+        retained_until=_format_utc(retained_until),
+        expired=observed >= retained_until,
+        policy_digest=policy.digest,
+    )
+
+
+def project_availability(
+    *,
+    content_sha256: str,
+    tombstone: DeletionTombstone | None,
+    deletion_status: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Join immutable source identity with separate immutable deletion evidence."""
+
+    if deletion_status is not None:
+        _validate_deletion_status(deletion_status, content_sha256=content_sha256)
+    if tombstone is None and deletion_status is None:
+        status = "available"
+        tombstone_digest = None
+        replay = "exact-bytes-required"
+    elif tombstone is None:
+        status = "deletion-pending"
+        tombstone_digest = deletion_status["planned_tombstone_digest"]
+        replay = "unavailable-by-deletion"
+    else:
+        if tombstone.removed_content_sha256 != content_sha256:
+            raise SourceContractError(
+                "TOMBSTONE_BINDING",
+                "tombstone.removed_content_sha256",
+                "tombstone does not bind the requested source digest",
+            )
+        if (
+            deletion_status is not None
+            and deletion_status["planned_tombstone_digest"] != tombstone.digest
+        ):
+            raise SourceContractError(
+                "TOMBSTONE_BINDING",
+                "deletion_status.planned_tombstone_digest",
+                "deletion status does not bind the confirmed tombstone",
+            )
+        status = "unavailable-by-deletion"
+        tombstone_digest = tombstone.digest
+        replay = "unavailable-by-deletion"
+    return {
+        "schema_version": _STATUS_VERSION,
+        "content_sha256": content_sha256,
+        "status": status,
+        "source_access_allowed": tombstone is None and deletion_status is None,
+        "refetch_allowed": False if tombstone is not None or deletion_status is not None else None,
+        "replay": replay,
+        "tombstone_digest": tombstone_digest,
+    }
+
+
+def require_source_available(
+    *,
+    content_sha256: str,
+    tombstone: DeletionTombstone | None,
+    deletion_status: dict[str, Any] | None = None,
+) -> None:
+    status = project_availability(
+        content_sha256=content_sha256,
+        tombstone=tombstone,
+        deletion_status=deletion_status,
+    )
+    if status["status"] != "available":
+        raise SourceContractError(
+            "SOURCE_UNAVAILABLE_BY_DELETION",
+            "source",
+            "source bytes were deleted; replay, resume, and refetch must not substitute them",
+        )
+
+
+def load_sealed_deletion_status(path: Path) -> dict[str, Any]:
+    """Load strict immutable deletion-pending evidence for recovery and access denial."""
+
+    value = parse_json(path.read_bytes())
+    if not isinstance(value, dict):
+        raise SourceContractError("DELETION_STATUS", "deletion_status", "must be an object")
+    _validate_deletion_status(value, content_sha256=value.get("content_sha256"))
+    return value
+
+
+def load_sealed_tombstone(path: Path) -> DeletionTombstone:
+    """Load and validate a sealed tombstone without accepting unknown fields."""
+
+    value = parse_json(path.read_bytes())
+    if not isinstance(value, dict):
+        raise SourceContractError("TOMBSTONE", "tombstone", "must be an object")
+    expected = {
+        "schema_version",
+        "tombstone_id",
+        "removed_content_sha256",
+        "removed_at",
+        "reason_code",
+        "policy_digest",
+        "complete_reference_set_digest",
+        "references",
+        "byte_removal_confirmed",
+    }
+    if set(value) != expected or not isinstance(value["references"], list):
+        raise SourceContractError(
+            "TOMBSTONE",
+            "tombstone",
+            "contains missing or unknown fields",
+        )
+    references: list[DeletedReference] = []
+    for item in value["references"]:
+        if not isinstance(item, dict) or set(item) != {"reference_kind", "reference_digest"}:
+            raise SourceContractError("TOMBSTONE", "references", "reference shape is invalid")
+        references.append(DeletedReference(**item))
+    copied = dict(value)
+    copied["references"] = tuple(references)
+    return DeletionTombstone(**copied)
+
+
+def _validate_deletion_status(
+    value: dict[str, Any],
+    *,
+    content_sha256: Any,
+) -> None:
+    expected = {
+        "schema_version",
+        "content_sha256",
+        "status",
+        "source_access_allowed",
+        "refetch_allowed",
+        "replay",
+        "removed_at",
+        "reason_code",
+        "policy_digest",
+        "complete_reference_set_digest",
+        "references",
+        "planned_tombstone_digest",
+    }
+    if (
+        set(value) != expected
+        or value["schema_version"] != _DELETION_STATUS_VERSION
+        or value["content_sha256"] != content_sha256
+        or value["status"] != "deletion-pending"
+        or value["source_access_allowed"] is not False
+        or value["refetch_allowed"] is not False
+        or value["replay"] != "unavailable-by-deletion"
+        or not isinstance(value["references"], list)
+    ):
+        raise SourceContractError(
+            "DELETION_STATUS",
+            "deletion_status",
+            "shape or immutable availability state is invalid",
+        )
+    references: list[DeletedReference] = []
+    for item in value["references"]:
+        if not isinstance(item, dict) or set(item) != {"reference_kind", "reference_digest"}:
+            raise SourceContractError(
+                "DELETION_STATUS",
+                "deletion_status.references",
+                "reference shape is invalid",
+            )
+        references.append(DeletedReference(**item))
+    ordered = _complete_reference_set(tuple(references))
+    if (
+        canonical_sha256([item.to_dict() for item in ordered])
+        != value["complete_reference_set_digest"]
+    ):
+        raise SourceContractError(
+            "DELETION_STATUS",
+            "deletion_status.complete_reference_set_digest",
+            "does not match the exact reference set",
+        )
+    planned = DeletionTombstone(
+        tombstone_id=f"delete.{value['content_sha256'][:24]}",
+        removed_content_sha256=value["content_sha256"],
+        removed_at=value["removed_at"],
+        reason_code=value["reason_code"],
+        policy_digest=value["policy_digest"],
+        complete_reference_set_digest=value["complete_reference_set_digest"],
+        references=ordered,
+        byte_removal_confirmed=True,
+    )
+    if planned.digest != value["planned_tombstone_digest"]:
+        raise SourceContractError(
+            "DELETION_STATUS",
+            "deletion_status.planned_tombstone_digest",
+            "does not bind the exact confirmed tombstone",
+        )
+
+
+def _complete_reference_set(
+    references: tuple[DeletedReference, ...],
+) -> tuple[DeletedReference, ...]:
+    if not references:
+        raise SourceContractError(
+            "REFERENCE_SET_EMPTY",
+            "references",
+            "deletion requires the complete non-empty reference set",
+        )
+    ordered = tuple(
+        sorted(references, key=lambda item: (item.reference_kind, item.reference_digest))
+    )
+    if ordered != references:
+        raise SourceContractError(
+            "REFERENCE_SET_ORDER",
+            "references",
+            "complete reference set must be canonically ordered",
+        )
+    coordinates = {(item.reference_kind, item.reference_digest) for item in ordered}
+    if len(coordinates) != len(ordered):
+        raise SourceContractError(
+            "REFERENCE_SET_DUPLICATE",
+            "references",
+            "complete reference set must not contain duplicates",
+        )
+    return ordered
+
+
+def _hash_descriptor(descriptor: int) -> str:
+    digest = hashlib.sha256()
+    os.lseek(descriptor, 0, os.SEEK_SET)
+    while True:
+        chunk = os.read(descriptor, 64 * 1024)
+        if not chunk:
+            break
+        digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _path_digest(path: Path) -> str:
+    """Digest one evidence file through the same bound open its validating reads use.
+
+    A bare ``Path.read_bytes`` follows links and waits forever on a FIFO, and this digest lands
+    in the sealed audit envelope -- so the name is opened exactly as the evidence reads open it,
+    and the kind is bound before a byte is hashed.
+    """
+
+    descriptor = os.open(
+        path,
+        os.O_RDONLY
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_NONBLOCK", 0)
+        | getattr(os, "O_CLOEXEC", 0),
+    )
+    try:
+        _require_readable_evidence_kind(descriptor, path.name)
+        return _hash_descriptor(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _seal_keyed_envelope(root: Path, *, content: bytes, index_name: str) -> Path:
+    """Seal immutable bytes and atomically bind one removed-source index to them."""
+
+    seal_content_addressed_snapshot(root, content=content, suffix="json")
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    root_fd = os.open(root, directory_flags)
+    temporary_name = f".stage-index-{os.getpid()}-{threading.get_ident()}-{time.monotonic_ns()}"
+    temporary_fd: int | None = None
+    try:
+        temporary_fd = os.open(
+            temporary_name,
+            os.O_WRONLY
+            | os.O_CREAT
+            | os.O_EXCL
+            | getattr(os, "O_NOFOLLOW", 0)
+            | getattr(os, "O_CLOEXEC", 0),
+            0o600,
+            dir_fd=root_fd,
+        )
+        view = memoryview(content)
+        written = 0
+        while written < len(view):
+            count = os.write(temporary_fd, view[written:])
+            if count <= 0:
+                raise SourceContractError(
+                    "DELETION_EVIDENCE_WRITE",
+                    index_name,
+                    "removed-source evidence write made no progress",
+                )
+            written += count
+        os.fchmod(temporary_fd, 0o444)
+        os.fsync(temporary_fd)
+        os.close(temporary_fd)
+        temporary_fd = None
+        try:
+            os.link(
+                temporary_name,
+                index_name,
+                src_dir_fd=root_fd,
+                dst_dir_fd=root_fd,
+                follow_symlinks=False,
+            )
+        except FileExistsError:
+            existing_fd = os.open(
+                index_name,
+                os.O_RDONLY
+                | getattr(os, "O_NOFOLLOW", 0)
+                | getattr(os, "O_NONBLOCK", 0)
+                | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=root_fd,
+            )
+            try:
+                _require_readable_evidence_kind(existing_fd, index_name)
+                existing = _read_exact_descriptor(existing_fd, len(content))
+            finally:
+                os.close(existing_fd)
+            if existing != content:
+                raise SourceContractError(
+                    "DELETION_EVIDENCE_CONFLICT",
+                    index_name,
+                    "removed-source evidence index already binds different immutable bytes",
+                ) from None
+        os.unlink(temporary_name, dir_fd=root_fd)
+        os.fsync(root_fd)
+    finally:
+        if temporary_fd is not None:
+            os.close(temporary_fd)
+        try:
+            os.unlink(temporary_name, dir_fd=root_fd)
+        except FileNotFoundError:
+            pass
+        os.close(root_fd)
+    return root / index_name
+
+
+def _keyed_envelope_matches(root: Path, *, content: bytes, index_name: str) -> bool:
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    root_fd = os.open(root, directory_flags)
+    try:
+        try:
+            descriptor = os.open(
+                index_name,
+                os.O_RDONLY
+                | getattr(os, "O_NOFOLLOW", 0)
+                | getattr(os, "O_NONBLOCK", 0)
+                | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=root_fd,
+            )
+        except FileNotFoundError:
+            return False
+        try:
+            _require_readable_evidence_kind(descriptor, index_name)
+            existing = _read_exact_descriptor(descriptor, len(content))
+        finally:
+            os.close(descriptor)
+        if existing != content:
+            raise SourceContractError(
+                "DELETION_EVIDENCE_CONFLICT",
+                index_name,
+                "removed-source evidence index binds different immutable bytes",
+            )
+        return True
+    finally:
+        os.close(root_fd)
+
+
+def _require_readable_evidence_kind(descriptor: int, index_name: str) -> None:
+    """Refuse an evidence index that is not a plain file, before a byte of it is read.
+
+    These descriptors are opened ``O_NONBLOCK``, because opening a FIFO without it waits in the
+    kernel for a writer that never comes.  The status-envelope open runs while this coordinator
+    holds a snapshot name's cross-process lock, where the wait would take every sealer of that
+    digest with it; the tombstone and audit opens run after release, where the wait would still
+    park this deletion forever. The flag makes the open return; it also means ``read`` can answer
+    ``EAGAIN`` on anything that is not a regular file, which would leave this module through an
+    untyped ``BlockingIOError`` instead of a refusal that names the evidence it declined.
+
+    So the kind is bound first, exactly as :meth:`DeletionCoordinator._open_validated_snapshot`
+    binds it before hashing. ``O_NONBLOCK`` has no effect on ``read`` for a regular file, which is
+    the only kind that gets past this line.
+    """
+
+    info = os.fstat(descriptor)
+    if not stat.S_ISREG(info.st_mode):
+        raise SourceContractError(
+            "DELETION_EVIDENCE_CONFLICT",
+            index_name,
+            f"removed-source evidence index is kind {stat.S_IFMT(info.st_mode):#o},"
+            " not a regular file",
+        )
+
+
+def _read_exact_descriptor(descriptor: int, expected_size: int) -> bytes:
+    chunks: list[bytes] = []
+    total = 0
+    while total <= expected_size:
+        chunk = os.read(descriptor, min(64 * 1024, expected_size + 1 - total))
+        if not chunk:
+            break
+        chunks.append(chunk)
+        total += len(chunk)
+    if total != expected_size:
+        raise SourceContractError(
+            "DELETION_EVIDENCE_CONFLICT",
+            "evidence",
+            "existing evidence length differs from the immutable envelope",
+        )
+    return b"".join(chunks)
+
+
+def _utc(value: str, path: str) -> datetime:
+    if not isinstance(value, str) or not value.endswith("Z"):
+        raise SourceContractError("TIMESTAMP", path, "must be an RFC 3339 UTC timestamp")
+    try:
+        parsed = datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError:
+        raise SourceContractError("TIMESTAMP", path, "must be a valid UTC timestamp") from None
+    if parsed.tzinfo != UTC:
+        raise SourceContractError("TIMESTAMP", path, "must use UTC")
+    return parsed
+
+
+def _format_utc(value: datetime) -> str:
+    return value.astimezone(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")