mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/deployment_evidence.py

@@ -0,0 +1,1067 @@
+"""Content-addressed source authority prepared beside one immutable Recipe Build.
+
+The Recipe candidate already seals the authoritative acquisition document. This module projects
+each static source's acquired snapshot, receipt, and observation into content-addressed objects for
+Studio source staging without inventing Studio artifact identifiers. Connector-backed sources bind
+their exact executable adapter coordinate instead. A closed bundle manifest matches Studio's
+reviewed-Build contract and binds the inventory to the candidate, Recipe, and execution.
+
+Publication is manifest-last.  Object files may exist without granting closure after an interrupted
+write; only the digest-named bundle is a complete result.  Every install is create-only and an
+exact repeat converges on the existing bytes.  Existing bytes, names, or file kinds that disagree
+fail closed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import stat
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness import pipeline, recipe
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    parse_canonical_json,
+)
+
+ACQUISITION_BUNDLE_SCHEMA = "mostlyright-deployment-acquisition-bundle.v2"
+PERSISTED_ACQUISITION_BUNDLE_SCHEMA = "mostlyright-persisted-acquisition-bundle.v1"
+ACQUISITION_STORE_RELATIVE = Path("evidence") / "acquisition"
+MAX_OBJECT_BYTES = 4 * 1024 * 1024
+MAX_SOURCE_OBJECT_BYTES = pipeline.MAX_SOURCE_BYTES
+MAX_BUNDLE_BYTES = 4 * 1024 * 1024
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+_SEMVER = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
+
+
+class DeploymentEvidenceError(RuntimeError):
+    """The local acquisition-evidence projection is absent, changed, or unsafe."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        self.detail = detail
+        super().__init__(f"{code}: {detail}")
+
+
+@dataclass(frozen=True)
+class PersistedAcquisitionBundle:
+    bundle_digest: str
+    bundle_path: Path
+    candidate_digest: str
+    recipe_digest: str
+    execution_digest: str
+    source_count: int
+    object_count: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": PERSISTED_ACQUISITION_BUNDLE_SCHEMA,
+            "bundle_digest": self.bundle_digest,
+            "bundle_path": str(self.bundle_path),
+            "candidate_digest": self.candidate_digest,
+            "recipe_digest": self.recipe_digest,
+            "execution_digest": self.execution_digest,
+            "source_count": self.source_count,
+            "object_count": self.object_count,
+        }
+
+
+@dataclass(frozen=True)
+class AcquisitionSourcePayload:
+    """One exact static source triplet retained from the authenticated local bundle."""
+
+    source: dict[str, Any]
+    source_data: bytes
+    acquisition_receipt: bytes
+    source_observation: bytes
+
+
+def persist_acquisition_bundle(
+    run_dir: Path,
+    *,
+    previous_run_dir: Path | None = None,
+) -> PersistedAcquisitionBundle:
+    """Project exact receipt/observation evidence and publish its closed bundle last."""
+
+    run = _safe_run_dir(run_dir)
+    handle = _open_run_handle(run)
+    store: _StoreDirectories | None = None
+    try:
+        store = _store_directories(run, handle.run_fd)
+
+        def validate_transaction() -> None:
+            _validate_run_handle(handle)
+            store.validate()
+
+        with pipeline.open_verified_snapshot(
+            run,
+            _run_fd=handle.run_fd,
+            _ancestor_validator=validate_transaction,
+        ) as snapshot:
+            inspection, embedded = recipe.verify_recipe_candidate(
+                run,
+                previous_run_dir=None if previous_run_dir is None else Path(previous_run_dir),
+                _snapshot=snapshot,
+            )
+            acquisition = embedded["acquisition"]
+            document = _bundle_document(inspection, embedded, snapshot=snapshot)
+            raw_bundle = canonical_json_bytes(document)
+            bundle_digest = _sha256(raw_bundle)
+
+            acquisition_by_id = {source["source_id"]: source for source in acquisition["sources"]}
+            execution_by_id = {source.source_id: source for source in embedded["execution"].sources}
+            for source in document["sources"]:
+                if source["authority_kind"] != "sealed_artifact":
+                    continue
+                source_id = source["source_id"]
+                sealed = acquisition_by_id[source_id]
+                if execution_by_id[source_id].artifact_input is None:
+                    raise DeploymentEvidenceError(
+                        "DEPLOYMENT_EVIDENCE_BINDING",
+                        "a sealed source bundle entry has no artifact execution authority",
+                    )
+                objects = {
+                    "source_data": snapshot.member_bytes(f"raw/{source_id}.csv"),
+                    "acquisition_receipt": canonical_json_bytes(sealed["acquisition_receipt"]),
+                    "source_observation": canonical_json_bytes(sealed["observation"]),
+                }
+                for role, raw in objects.items():
+                    validate_transaction()
+                    digest = _sha256(raw)
+                    suffix = ".bin" if role == "source_data" else ".json"
+                    _install_exact(
+                        store.objects / f"{digest}{suffix}",
+                        raw,
+                        maximum=(
+                            MAX_SOURCE_OBJECT_BYTES if role == "source_data" else MAX_OBJECT_BYTES
+                        ),
+                        directory_fd=store.objects_fd,
+                        bindings=store.files,
+                    )
+                    validate_transaction()
+
+            bundle_path = store.bundles / f"{bundle_digest}.json"
+            validate_transaction()
+            _install_exact(
+                bundle_path,
+                raw_bundle,
+                maximum=MAX_BUNDLE_BYTES,
+                directory_fd=store.bundles_fd,
+                bindings=store.files,
+            )
+            validate_transaction()
+            snapshot.validate()
+            validate_transaction()
+
+        persisted = _parse_acquisition_bundle_bound(
+            run,
+            bundle_digest,
+            handle=handle,
+            store=store,
+            previous_run_dir=previous_run_dir,
+        )
+        if persisted.bundle_path != bundle_path:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_PATH",
+                "the published bundle resolved to a different content-addressed path",
+            )
+        validate_transaction()
+        return persisted
+    finally:
+        try:
+            if store is not None:
+                store.close()
+        finally:
+            handle.close()
+
+
+def parse_acquisition_bundle(
+    run_dir: Path,
+    bundle_digest: str,
+    *,
+    previous_run_dir: Path | None = None,
+) -> PersistedAcquisitionBundle:
+    """Authenticate one published bundle against the exact sealed Recipe candidate."""
+
+    run = _safe_run_dir(run_dir)
+    handle = _open_run_handle(run)
+    store: _StoreDirectories | None = None
+    try:
+        store = _existing_store(run, handle.run_fd)
+        return _parse_acquisition_bundle_bound(
+            run,
+            bundle_digest,
+            handle=handle,
+            store=store,
+            previous_run_dir=previous_run_dir,
+        )
+    finally:
+        try:
+            if store is not None:
+                store.close()
+        finally:
+            handle.close()
+
+
+def load_acquisition_bundle_document(
+    run_dir: Path,
+    bundle_digest: str,
+    *,
+    previous_run_dir: Path | None = None,
+) -> dict[str, Any]:
+    """Return the exact canonical bundle after authenticating it to the reviewed Build."""
+
+    run = _safe_run_dir(run_dir)
+    handle = _open_run_handle(run)
+    store: _StoreDirectories | None = None
+    try:
+        store = _existing_store(run, handle.run_fd)
+        persisted = _parse_acquisition_bundle_bound(
+            run,
+            bundle_digest,
+            handle=handle,
+            store=store,
+            previous_run_dir=previous_run_dir,
+        )
+        raw = _read_exact(
+            store.bundles / f"{persisted.bundle_digest}.json",
+            maximum=MAX_BUNDLE_BYTES,
+            directory_fd=store.bundles_fd,
+            bindings=store.files,
+        )
+        store.validate()
+        value = parse_canonical_json(raw)
+        if not isinstance(value, dict):  # already guaranteed above; keep the public seam typed
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle must be one object"
+            )
+        return dict(value)
+    finally:
+        try:
+            if store is not None:
+                store.close()
+        finally:
+            handle.close()
+
+
+def load_acquisition_source_payload(
+    run_dir: Path,
+    bundle_digest: str,
+    source_id: str,
+    *,
+    previous_run_dir: Path | None = None,
+) -> AcquisitionSourcePayload:
+    """Return one static source triplet without releasing its bound store during reads."""
+
+    run = _safe_run_dir(run_dir)
+    handle = _open_run_handle(run)
+    store: _StoreDirectories | None = None
+    try:
+        store = _existing_store(run, handle.run_fd)
+        persisted = _parse_acquisition_bundle_bound(
+            run,
+            bundle_digest,
+            handle=handle,
+            store=store,
+            previous_run_dir=previous_run_dir,
+        )
+        raw_bundle = _read_exact(
+            store.bundles / f"{persisted.bundle_digest}.json",
+            maximum=MAX_BUNDLE_BYTES,
+            directory_fd=store.bundles_fd,
+            bindings=store.files,
+        )
+        value = parse_canonical_json(raw_bundle)
+        if not isinstance(value, dict) or not isinstance(value.get("sources"), list):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle source inventory is invalid"
+            )
+        matches = [
+            item
+            for item in value["sources"]
+            if isinstance(item, dict) and item.get("source_id") == source_id
+        ]
+        if len(matches) != 1 or matches[0].get("authority_kind") != "sealed_artifact":
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_SOURCE",
+                f"the acquisition bundle does not contain one static source named {source_id}",
+            )
+        source = matches[0]
+        objects: dict[str, bytes] = {}
+        for role in ("source_data", "acquisition_receipt", "source_observation"):
+            reference = source[role]
+            digest = reference["content_sha256"]
+            suffix = ".bin" if role == "source_data" else ".json"
+            raw = _read_exact(
+                store.objects / f"{digest}{suffix}",
+                maximum=MAX_SOURCE_OBJECT_BYTES if role == "source_data" else MAX_OBJECT_BYTES,
+                directory_fd=store.objects_fd,
+                bindings=store.files,
+            )
+            if _sha256(raw) != digest or len(raw) != reference["size_bytes"]:
+                raise DeploymentEvidenceError(
+                    "DEPLOYMENT_EVIDENCE_DIGEST",
+                    f"the {role} object for {source_id} differs from its closed reference",
+                )
+            objects[role] = raw
+        store.validate()
+        return AcquisitionSourcePayload(
+            source=dict(source),
+            source_data=objects["source_data"],
+            acquisition_receipt=objects["acquisition_receipt"],
+            source_observation=objects["source_observation"],
+        )
+    finally:
+        try:
+            if store is not None:
+                store.close()
+        finally:
+            handle.close()
+
+
+def _parse_acquisition_bundle_bound(
+    run: Path,
+    bundle_digest: str,
+    *,
+    handle: Any,
+    store: _StoreDirectories,
+    previous_run_dir: Path | None,
+) -> PersistedAcquisitionBundle:
+    digest = _digest(bundle_digest, "bundle digest")
+    bundle_path = store.bundles / f"{digest}.json"
+    store.validate()
+    raw = _read_exact(
+        bundle_path,
+        maximum=MAX_BUNDLE_BYTES,
+        directory_fd=store.bundles_fd,
+        bindings=store.files,
+    )
+    store.validate()
+    if _sha256(raw) != digest:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_DIGEST",
+            "the acquisition bundle bytes do not match their content-addressed name",
+        )
+    try:
+        value = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_CANONICAL",
+            "the acquisition bundle is not canonical JSON",
+        ) from error
+    if not isinstance(value, dict):
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle must be one object"
+        )
+
+    def validate_transaction() -> None:
+        _validate_run_handle(handle)
+        store.validate()
+
+    with pipeline.open_verified_snapshot(
+        run,
+        _run_fd=handle.run_fd,
+        _ancestor_validator=validate_transaction,
+    ) as snapshot:
+        inspection, embedded = recipe.verify_recipe_candidate(
+            run,
+            previous_run_dir=None if previous_run_dir is None else Path(previous_run_dir),
+            _snapshot=snapshot,
+        )
+        expected = _bundle_document(inspection, embedded, snapshot=snapshot)
+        _parse_bundle_shape(value)
+        if value != expected:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_BINDING",
+                "the acquisition bundle does not match the exact sealed candidate evidence",
+            )
+
+        object_digests: set[str] = set()
+        expected_sources = {item["source_id"]: item for item in embedded["acquisition"]["sources"]}
+        for source in value["sources"]:
+            if source["authority_kind"] != "sealed_artifact":
+                continue
+            sealed = expected_sources[source["source_id"]]
+            expected_objects = {
+                "source_data": snapshot.member_bytes(f"raw/{source['source_id']}.csv"),
+                "acquisition_receipt": canonical_json_bytes(sealed["acquisition_receipt"]),
+                "source_observation": canonical_json_bytes(sealed["observation"]),
+            }
+            for role, expected_object in expected_objects.items():
+                validate_transaction()
+                reference = source[role]
+                object_digest = reference["content_sha256"]
+                suffix = ".bin" if role == "source_data" else ".json"
+                raw_object = _read_exact(
+                    store.objects / f"{object_digest}{suffix}",
+                    maximum=(
+                        MAX_SOURCE_OBJECT_BYTES if role == "source_data" else MAX_OBJECT_BYTES
+                    ),
+                    directory_fd=store.objects_fd,
+                    bindings=store.files,
+                )
+                validate_transaction()
+                if _sha256(raw_object) != object_digest:
+                    raise DeploymentEvidenceError(
+                        "DEPLOYMENT_EVIDENCE_DIGEST",
+                        f"the {role} object for {source['source_id']} mismatches its digest",
+                    )
+                if raw_object != expected_object:
+                    raise DeploymentEvidenceError(
+                        "DEPLOYMENT_EVIDENCE_BINDING",
+                        f"the {role} object for {source['source_id']} was spliced from "
+                        "another source",
+                    )
+                object_digests.add(object_digest)
+        snapshot.validate()
+        validate_transaction()
+
+    return PersistedAcquisitionBundle(
+        bundle_digest=digest,
+        bundle_path=bundle_path,
+        candidate_digest=value["candidate_digest"],
+        recipe_digest=value["recipe_digest"],
+        execution_digest=value["execution_digest"],
+        source_count=len(value["sources"]),
+        object_count=len(object_digests),
+    )
+
+
+@dataclass
+class _FileBinding:
+    directory_fd: int
+    name: str
+    descriptor: int
+    identity: tuple[int, int, int, int, int, int, int]
+
+    def validate(self) -> None:
+        try:
+            opened = os.fstat(self.descriptor)
+            named = os.stat(self.name, dir_fd=self.directory_fd, follow_symlinks=False)
+        except OSError as error:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_RACE",
+                f"evidence object {self.name} changed during evidence handling",
+            ) from error
+        if (
+            not _safe_regular_file(opened)
+            or not _safe_regular_file(named)
+            or _file_identity(opened) != self.identity
+            or _file_identity(named) != self.identity
+        ):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_RACE",
+                f"evidence object {self.name} changed during evidence handling",
+            )
+
+
+@dataclass
+class _DirectoryBinding:
+    parent_fd: int
+    name: str
+    descriptor: int
+    device: int
+    inode: int
+
+    @classmethod
+    def capture(cls, parent_fd: int, name: str, descriptor: int) -> _DirectoryBinding:
+        opened = os.fstat(descriptor)
+        return cls(
+            parent_fd=parent_fd,
+            name=name,
+            descriptor=descriptor,
+            device=opened.st_dev,
+            inode=opened.st_ino,
+        )
+
+    def validate(self) -> None:
+        try:
+            opened = os.fstat(self.descriptor)
+            named = os.stat(self.name, dir_fd=self.parent_fd, follow_symlinks=False)
+        except OSError as error:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_RACE",
+                f"evidence directory {self.name} changed during evidence handling",
+            ) from error
+        expected = (self.device, self.inode)
+        if (
+            not stat.S_ISDIR(opened.st_mode)
+            or not stat.S_ISDIR(named.st_mode)
+            or (opened.st_dev, opened.st_ino) != expected
+            or (named.st_dev, named.st_ino) != expected
+        ):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_RACE",
+                f"evidence directory {self.name} changed during evidence handling",
+            )
+
+
+@dataclass
+class _StoreDirectories:
+    root: Path
+    objects: Path
+    bundles: Path
+    objects_fd: int
+    bundles_fd: int
+    descriptors: list[int]
+    bindings: list[_DirectoryBinding]
+    files: list[_FileBinding]
+
+    def validate(self) -> None:
+        for binding in self.bindings:
+            binding.validate()
+        for file in self.files:
+            file.validate()
+
+    def close(self) -> None:
+        descriptors = list(reversed(self.descriptors))
+        self.descriptors.clear()
+        file_descriptors = [file.descriptor for file in reversed(self.files)]
+        self.files.clear()
+        first_error: OSError | None = None
+        for descriptor in file_descriptors + descriptors:
+            try:
+                os.close(descriptor)
+            except OSError as error:
+                if first_error is None:
+                    first_error = error
+        if first_error is not None:
+            raise first_error
+
+
+def _bundle_document(
+    inspection: pipeline.CandidateInspection,
+    embedded: Mapping[str, Any],
+    *,
+    snapshot: pipeline.VerifiedSnapshot,
+) -> dict[str, Any]:
+    acquisition = embedded["acquisition"]
+    acquisition_by_id = {source["source_id"]: source for source in acquisition["sources"]}
+    recipe_by_id = {source.source_id: source for source in embedded["recipe"].sources}
+    execution_by_id = {source.source_id: source for source in embedded["execution"].sources}
+    source_ids = sorted(recipe_by_id)
+    if (
+        set(acquisition_by_id) != set(source_ids)
+        or set(execution_by_id) != set(source_ids)
+        or len(source_ids) != len(embedded["recipe"].sources)
+    ):
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_BINDING",
+            "the Recipe, execution, and acquisition source inventories differ",
+        )
+    sources: list[dict[str, Any]] = []
+    for source_id in source_ids:
+        acquired = acquisition_by_id[source_id]
+        recipe_source = recipe_by_id[source_id]
+        execution_source = execution_by_id[source_id]
+        if execution_source.artifact_input is None:
+            sources.append(
+                {
+                    "source_id": source_id,
+                    "authority_kind": "connector",
+                    "adapter_id": recipe_source.adapter_id,
+                    "adapter_version": recipe_source.adapter_version,
+                }
+            )
+            continue
+        source_raw = snapshot.member_bytes(f"raw/{source_id}.csv")
+        receipt_raw = canonical_json_bytes(acquired["acquisition_receipt"])
+        observation_raw = canonical_json_bytes(acquired["observation"])
+        receipt = acquired["acquisition_receipt"]
+        receipt_snapshot = receipt.get("snapshot")
+        if receipt_snapshot is None and receipt.get("schema_version") == (
+            "recorded-artifact-receipt.v1"
+        ):
+            # A sealed local artifact carries the flat recorded-artifact receipt the
+            # recipe executor writes, not a network acquisition's snapshot record.
+            # The binding it offers is the same one this bundle needs — the exact
+            # content digest of the sealed raw member — so verify that digest and
+            # take the media type from the sealed Recipe source, which is the
+            # authority that declared it. Every other shape still fails closed.
+            recipe_media_type = recipe_source.query_template.get("media_type")
+            if (
+                set(receipt) != {"schema_version", "source_id", "content_sha256"}
+                or receipt.get("source_id") != source_id
+                or receipt.get("content_sha256") != _sha256(source_raw)
+                or not isinstance(recipe_media_type, str)
+                or not recipe_media_type
+            ):
+                raise DeploymentEvidenceError(
+                    "DEPLOYMENT_EVIDENCE_BINDING",
+                    f"the acquired snapshot for {source_id} differs from its receipt",
+                )
+            receipt_snapshot = {
+                "media_type": recipe_media_type,
+                "content_sha256": receipt["content_sha256"],
+                "size_bytes": len(source_raw),
+            }
+        if (
+            not isinstance(receipt_snapshot, dict)
+            or receipt_snapshot.get("content_sha256") != _sha256(source_raw)
+            or receipt_snapshot.get("size_bytes") != len(source_raw)
+            or not isinstance(receipt_snapshot.get("media_type"), str)
+        ):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_BINDING",
+                f"the acquired snapshot for {source_id} differs from its receipt",
+            )
+        sources.append(
+            {
+                "source_id": source_id,
+                "authority_kind": "sealed_artifact",
+                "source_data": {
+                    "media_type": receipt_snapshot["media_type"],
+                    "content_sha256": _sha256(source_raw),
+                    "size_bytes": len(source_raw),
+                },
+                "acquisition_receipt": {
+                    "media_type": "application/json",
+                    "content_sha256": _sha256(receipt_raw),
+                    "size_bytes": len(receipt_raw),
+                },
+                "source_observation": {
+                    "media_type": "application/json",
+                    "content_sha256": _sha256(observation_raw),
+                    "size_bytes": len(observation_raw),
+                },
+            }
+        )
+    return {
+        "schema_version": ACQUISITION_BUNDLE_SCHEMA,
+        "candidate_digest": inspection.candidate_digest,
+        "recipe_digest": embedded["recipe"].digest,
+        "execution_digest": embedded["execution"].digest,
+        "source_count": len(sources),
+        "sources": sources,
+    }
+
+
+def _parse_bundle_shape(value: Mapping[str, Any]) -> None:
+    expected = {
+        "schema_version",
+        "candidate_digest",
+        "recipe_digest",
+        "execution_digest",
+        "source_count",
+        "sources",
+    }
+    if set(value) != expected or value.get("schema_version") != ACQUISITION_BUNDLE_SCHEMA:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle fields are not exact"
+        )
+    for field in (
+        "candidate_digest",
+        "recipe_digest",
+        "execution_digest",
+    ):
+        _digest(value.get(field), field)
+    sources = value.get("sources")
+    if not isinstance(sources, list) or not sources:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle source inventory is invalid"
+        )
+    if value.get("source_count") != len(sources):
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle source count is invalid"
+        )
+    source_ids: list[str] = []
+    for source in sources:
+        if not isinstance(source, dict):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_FIELDS", "an acquisition bundle source entry is invalid"
+            )
+        source_id = source.get("source_id")
+        if not isinstance(source_id, str) or _IDENTIFIER.fullmatch(source_id) is None:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_FIELDS", "an acquisition bundle source id is invalid"
+            )
+        source_ids.append(source_id)
+        authority_kind = source.get("authority_kind")
+        if authority_kind == "connector":
+            if set(source) != {
+                "source_id",
+                "authority_kind",
+                "adapter_id",
+                "adapter_version",
+            } or any(
+                not isinstance(source.get(field), str) or pattern.fullmatch(source[field]) is None
+                for field, pattern in (("adapter_id", _IDENTIFIER), ("adapter_version", _SEMVER))
+            ):
+                raise DeploymentEvidenceError(
+                    "DEPLOYMENT_EVIDENCE_FIELDS",
+                    "a connector acquisition bundle source entry is invalid",
+                )
+            continue
+        if authority_kind != "sealed_artifact" or set(source) != {
+            "source_id",
+            "authority_kind",
+            "source_data",
+            "acquisition_receipt",
+            "source_observation",
+        }:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_FIELDS",
+                "a static acquisition bundle source entry is invalid",
+            )
+        for role in ("source_data", "acquisition_receipt", "source_observation"):
+            reference = source.get(role)
+            if not isinstance(reference, dict) or set(reference) != {
+                "media_type",
+                "content_sha256",
+                "size_bytes",
+            }:
+                raise DeploymentEvidenceError(
+                    "DEPLOYMENT_EVIDENCE_FIELDS", f"the {role} object reference is invalid"
+                )
+            if role != "source_data" and reference.get("media_type") != "application/json":
+                raise DeploymentEvidenceError(
+                    "DEPLOYMENT_EVIDENCE_FIELDS", f"the {role} media type is invalid"
+                )
+            _digest(reference.get("content_sha256"), f"{role} digest")
+            size = reference.get("size_bytes")
+            maximum = MAX_SOURCE_OBJECT_BYTES if role == "source_data" else MAX_OBJECT_BYTES
+            if type(size) is not int or not 1 <= size <= maximum:
+                raise DeploymentEvidenceError(
+                    "DEPLOYMENT_EVIDENCE_FIELDS", f"the {role} size is invalid"
+                )
+    if source_ids != sorted(set(source_ids)):
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_FIELDS", "the acquisition bundle source ids are not sorted unique"
+        )
+
+
+def _safe_run_dir(run_dir: Path) -> Path:
+    run = Path(run_dir).absolute()
+    if run == Path(run.anchor) or not run.name:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_PATH", "the Recipe run path must name one non-root directory"
+        )
+    return run
+
+
+def _open_run_handle(run_dir: Path) -> Any:
+    try:
+        return pipeline._open_candidate_run_handle(run_dir)
+    except pipeline.BuildError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_PATH", "the Recipe run directory is unavailable or unsafe"
+        ) from error
+
+
+def _validate_run_handle(handle: Any) -> None:
+    try:
+        pipeline._validate_candidate_run_handle(handle)
+    except pipeline.BuildError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_RACE", "the Recipe run path changed during evidence handling"
+        ) from error
+
+
+def _store_directories(run_dir: Path, run_fd: int) -> _StoreDirectories:
+    root = run_dir / ACQUISITION_STORE_RELATIVE
+    objects = root / "objects" / "sha256"
+    bundles = root / "bundles" / "sha256"
+    descriptors: list[int] = []
+    try:
+        evidence_fd = _open_directory_at(run_fd, "evidence", create=True)
+        descriptors.append(evidence_fd)
+        root_fd = _open_directory_at(evidence_fd, "acquisition", create=True)
+        descriptors.append(root_fd)
+        objects_parent_fd = _open_directory_at(root_fd, "objects", create=True)
+        descriptors.append(objects_parent_fd)
+        objects_fd = _open_directory_at(objects_parent_fd, "sha256", create=True)
+        descriptors.append(objects_fd)
+        bundles_parent_fd = _open_directory_at(root_fd, "bundles", create=True)
+        descriptors.append(bundles_parent_fd)
+        bundles_fd = _open_directory_at(bundles_parent_fd, "sha256", create=True)
+        descriptors.append(bundles_fd)
+        return _StoreDirectories(
+            root=root,
+            objects=objects,
+            bundles=bundles,
+            objects_fd=objects_fd,
+            bundles_fd=bundles_fd,
+            descriptors=descriptors,
+            bindings=_directory_bindings(run_fd, descriptors),
+            files=[],
+        )
+    except BaseException:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+        raise
+
+
+def _existing_store(run_dir: Path, run_fd: int) -> _StoreDirectories:
+    root = run_dir / ACQUISITION_STORE_RELATIVE
+    descriptors: list[int] = []
+    try:
+        evidence_fd = _open_directory_at(run_fd, "evidence", create=False)
+        descriptors.append(evidence_fd)
+        root_fd = _open_directory_at(evidence_fd, "acquisition", create=False)
+        descriptors.append(root_fd)
+        objects_parent_fd = _open_directory_at(root_fd, "objects", create=False)
+        descriptors.append(objects_parent_fd)
+        objects_fd = _open_directory_at(objects_parent_fd, "sha256", create=False)
+        descriptors.append(objects_fd)
+        bundles_parent_fd = _open_directory_at(root_fd, "bundles", create=False)
+        descriptors.append(bundles_parent_fd)
+        bundles_fd = _open_directory_at(bundles_parent_fd, "sha256", create=False)
+        descriptors.append(bundles_fd)
+        return _StoreDirectories(
+            root=root,
+            objects=root / "objects" / "sha256",
+            bundles=root / "bundles" / "sha256",
+            objects_fd=objects_fd,
+            bundles_fd=bundles_fd,
+            descriptors=descriptors,
+            bindings=_directory_bindings(run_fd, descriptors),
+            files=[],
+        )
+    except BaseException:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+        raise
+
+
+def _open_directory_at(parent_fd: int, name: str, *, create: bool) -> int:
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    if create:
+        try:
+            os.mkdir(name, mode=0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            pass
+        except OSError as error:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_PATH", f"could not create evidence directory {name}"
+            ) from error
+        else:
+            os.fsync(parent_fd)
+    try:
+        descriptor = os.open(name, flags, dir_fd=parent_fd)
+    except OSError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_PATH", f"evidence directory {name} is unavailable or unsafe"
+        ) from error
+    opened = os.fstat(descriptor)
+    if not stat.S_ISDIR(opened.st_mode):
+        os.close(descriptor)
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_PATH", f"evidence path {name} is not a real directory"
+        )
+    return descriptor
+
+
+def _directory_bindings(run_fd: int, descriptors: list[int]) -> list[_DirectoryBinding]:
+    evidence_fd, root_fd, objects_parent_fd, objects_fd, bundles_parent_fd, bundles_fd = descriptors
+    return [
+        _DirectoryBinding.capture(run_fd, "evidence", evidence_fd),
+        _DirectoryBinding.capture(evidence_fd, "acquisition", root_fd),
+        _DirectoryBinding.capture(root_fd, "objects", objects_parent_fd),
+        _DirectoryBinding.capture(objects_parent_fd, "sha256", objects_fd),
+        _DirectoryBinding.capture(root_fd, "bundles", bundles_parent_fd),
+        _DirectoryBinding.capture(bundles_parent_fd, "sha256", bundles_fd),
+    ]
+
+
+def _install_exact(
+    path: Path,
+    raw: bytes,
+    *,
+    maximum: int,
+    directory_fd: int,
+    bindings: list[_FileBinding],
+) -> bool:
+    if not 1 <= len(raw) <= maximum:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_SIZE", f"evidence object {path.name} exceeds its byte limit"
+        )
+    try:
+        existing = _read_exact(
+            path,
+            maximum=maximum,
+            directory_fd=directory_fd,
+            bindings=bindings,
+        )
+    except DeploymentEvidenceError as error:
+        if error.code != "DEPLOYMENT_EVIDENCE_PATH":
+            raise
+    else:
+        if existing != raw:
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_CONFLICT",
+                f"existing content-addressed evidence {path.name} has different bytes",
+            )
+        return False
+    temporary = f".{path.name}.tmp-{uuid.uuid4().hex}"
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = -1
+    try:
+        descriptor = os.open(temporary, flags, 0o600, dir_fd=directory_fd)
+        offset = 0
+        while offset < len(raw):
+            offset += os.write(descriptor, raw[offset:])
+        os.fsync(descriptor)
+        os.close(descriptor)
+        descriptor = -1
+        try:
+            os.link(
+                temporary,
+                path.name,
+                src_dir_fd=directory_fd,
+                dst_dir_fd=directory_fd,
+                follow_symlinks=False,
+            )
+            installed = True
+        except FileExistsError:
+            installed = False
+        if installed:
+            os.unlink(temporary, dir_fd=directory_fd)
+        if (
+            _read_exact(
+                path,
+                maximum=maximum,
+                directory_fd=directory_fd,
+                bindings=bindings,
+            )
+            != raw
+        ):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_CONFLICT",
+                f"content-addressed evidence {path.name} did not converge on exact bytes",
+            )
+        os.fsync(directory_fd)
+        return installed
+    except DeploymentEvidenceError:
+        raise
+    except OSError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_WRITE", f"could not publish evidence object {path.name}"
+        ) from error
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        try:
+            os.unlink(temporary, dir_fd=directory_fd)
+        except FileNotFoundError:
+            pass
+
+
+def _read_exact(
+    path: Path,
+    *,
+    maximum: int,
+    directory_fd: int,
+    bindings: list[_FileBinding],
+) -> bytes:
+    flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path.name, flags, dir_fd=directory_fd)
+    except OSError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_PATH", f"evidence object {path.name} is unavailable"
+        ) from error
+    try:
+        before = os.fstat(descriptor)
+        named_before = _stat_named_file(path.name, directory_fd)
+        identity = _file_identity(before)
+        if (
+            not _safe_regular_file(before)
+            or not _safe_regular_file(named_before)
+            or _file_identity(named_before) != identity
+            or before.st_size > maximum
+        ):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_PATH", f"evidence object {path.name} is not a safe file"
+            )
+        raw = bytearray()
+        while len(raw) <= maximum:
+            chunk = os.read(descriptor, min(64 * 1024, maximum + 1 - len(raw)))
+            if not chunk:
+                break
+            raw.extend(chunk)
+        after = os.fstat(descriptor)
+        named_after = _stat_named_file(path.name, directory_fd)
+        if (
+            len(raw) > maximum
+            or not _safe_regular_file(after)
+            or not _safe_regular_file(named_after)
+            or _file_identity(after) != identity
+            or _file_identity(named_after) != identity
+            or len(raw) != before.st_size
+        ):
+            raise DeploymentEvidenceError(
+                "DEPLOYMENT_EVIDENCE_RACE", f"evidence object {path.name} changed while read"
+            )
+        bindings.append(
+            _FileBinding(
+                directory_fd=directory_fd,
+                name=path.name,
+                descriptor=descriptor,
+                identity=identity,
+            )
+        )
+        descriptor = -1
+        return bytes(raw)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+
+def _safe_regular_file(value: os.stat_result) -> bool:
+    return stat.S_ISREG(value.st_mode) and value.st_nlink == 1
+
+
+def _stat_named_file(name: str, directory_fd: int) -> os.stat_result:
+    try:
+        return os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
+    except OSError as error:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_RACE",
+            f"evidence object {name} changed during evidence handling",
+        ) from error
+
+
+def _file_identity(value: os.stat_result) -> tuple[int, int, int, int, int, int, int]:
+    return (
+        value.st_dev,
+        value.st_ino,
+        value.st_mode,
+        value.st_nlink,
+        value.st_size,
+        value.st_mtime_ns,
+        value.st_ctime_ns,
+    )
+
+
+def _digest(value: Any, label: str) -> str:
+    if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+        raise DeploymentEvidenceError(
+            "DEPLOYMENT_EVIDENCE_FIELDS", f"the {label} is not a lowercase SHA-256 digest"
+        )
+    return value
+
+
+def _sha256(raw: bytes) -> str:
+    return hashlib.sha256(raw).hexdigest()
+
+
+__all__ = [
+    "ACQUISITION_BUNDLE_SCHEMA",
+    "ACQUISITION_STORE_RELATIVE",
+    "PERSISTED_ACQUISITION_BUNDLE_SCHEMA",
+    "AcquisitionSourcePayload",
+    "DeploymentEvidenceError",
+    "PersistedAcquisitionBundle",
+    "load_acquisition_bundle_document",
+    "load_acquisition_source_payload",
+    "parse_acquisition_bundle",
+    "persist_acquisition_bundle",
+]