mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/contracts.py

@@ -0,0 +1,2223 @@
+"""Strict Harness-private source and acquisition contracts.
+
+These contracts describe deterministic worker evidence.  They are not Studio wire models and
+never grant acquisition, legal, human-review, or release authority.
+
+Vocabulary map
+--------------
+
+Three modules carry overlapping enum sets and this one is canonical.  The layers are
+agent_runtime.py (untrusted model input and output), local_contracts.py (local proposals and
+plans), and this module (deterministic adapter, observation, and fitness evidence).  Where two
+layers name the same concept they use the same spelling.  Where the sets differ they differ
+because the stage differs, and they are deliberately not merged.
+
+source class
+    agent_runtime    external, user
+    local_contracts  external_adapter, user_file, user_url, user_api,
+                     database_extract, webhook, stream (_SOURCE_CLASSES)
+    sources          external_adapter, user_file, user_url, user_api, stream
+                     (SOURCE_CLASSES)
+    A model names a family and the local contract narrows it: external to external_adapter, user
+    to whichever of user_file, user_url, or user_api the locator turns out to be.
+    database_extract and webhook have no adapter contract, so this module rejects them. Catalog
+    providers are a separate Harness-owned discovery boundary and never become acquisition
+    adapters merely because their metadata was indexed.
+
+rights status
+    agent_runtime    approved, conditional, unclear, prohibited
+    local_contracts  approved, conditional, unclear, prohibited (_PROPOSAL_RIGHTS)
+    sources          approved, conditional, unclear, prohibited (RIGHTS_STATUSES)
+    One concept, one spelling, all three layers.  local_contracts._RIGHTS_STATUSES is a
+    different concept despite its name: it is the basis a build reads a file under
+    (project_owned, public_domain, permissive_license, authorized_internal, user_authorized,
+    unknown, prohibited), so its unknown is not this unclear.
+
+fitness decision
+    agent_runtime    fit, conditional, reject (assessment.fitness)
+    local_contracts  selected, eligible, rejected (_FITNESS_DECISIONS)
+    sources          selected, rejected, human_escalation_required (FITNESS_DECISIONS)
+    Three stages, not three spellings of one stage.  The model judges a candidate, the local
+    proposal records whether it was chosen (selected) or only admissible (eligible), and the
+    fitness report adjudicates deterministically and escalates instead of guessing.  fit reads
+    as eligible then selected, conditional as eligible then human_escalation_required, reject
+    as rejected.
+
+liveness
+    agent_runtime    live, delayed, dead, unknown (liveness.status)
+    local_contracts  live, degraded, delayed, dead, not_applicable (_LIVE_ENDPOINTS)
+    sources          none; CAPABILITIES.live is an adapter capability, not an endpoint state
+    A model may report unknown because a probe was inconclusive.  A proposal may not: it states
+    a definite state or not_applicable.  degraded has no model counterpart.
+
+data format
+    agent_runtime    none
+    local_contracts  PLAN_DATA_FORMATS, re-exported as _DATA_FORMATS
+    sources          DATA_FORMATS, re-exported from the same table
+    Not the same axis, and neither set is written here.  Both live in
+    mostlyright.data_harness.formats, which is the single authority for format membership;
+    this module re-exports the wire-format set under the name its callers already use.
+    This module's set lists payload encodings an adapter emits.  local_contracts mixes
+    encodings with access shapes (api, stream) that are locator-ish rather than encodings,
+    so the two sets are not shared.  local_contracts.SourceSpec.format is narrower still:
+    the build reads csv only.
+
+data classification
+    agent_runtime    public, internal, confidential, restricted
+    local_contracts  none
+    sources          public, internal, confidential, restricted, rejected (CLASSIFICATIONS)
+    rejected is a terminal adapter state and has no model counterpart.
+
+retention kinds
+    agent_runtime    raw_days, derived_days, tombstone_required (assessment.retention)
+    local_contracts  none
+    sources          raw, derived, logs, review_evidence (RETENTION_KINDS)
+    RETENTION_KINDS names every evidence kind a retention policy covers; deletion.py keys its
+    policy-field lookup by the same strings.  A model assessment proposes only the raw and
+    derived horizons.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from datetime import UTC, datetime
+from typing import Any, ClassVar
+from urllib.parse import urlsplit
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, canonical_sha256
+from mostlyright.data_harness.formats import DATA_FORMATS as _DATA_FORMATS
+
+# ``readers`` is a leaf: it imports ``formats``, ``canonical``, and the standard library and
+# nothing else, and a test walks the package to keep it that way.  So this direction --
+# sources depending on readers -- is the acyclic one.  Only the closed flag vocabulary is
+# imported, deliberately not ``ReaderPin``: the pin arrives here as a sealed mapping off a
+# recipe document, and modelling it as the Toolbox's object would couple the evidence layer
+# to the decoder implementation for no gain.
+from mostlyright.data_harness.readers.contracts import DECODE_FLAGS
+
+SOURCE_CONTRACT_VERSION = "harness-source-contract.v1"
+ADAPTER_CONTRACT_VERSION = "harness-source-adapter.v2"
+OBSERVATION_CONTRACT_VERSION = "harness-source-observation.v1"
+RECEIPT_CONTRACT_VERSION = "harness-acquisition-receipt.v1"
+RECEIPT_CONTRACT_VERSION_V2 = "harness-acquisition-receipt.v2"
+RECEIPT_CONTRACT_VERSION_V3 = "harness-acquisition-receipt.v3"
+FITNESS_CONTRACT_VERSION = "harness-source-fitness.v1"
+TOMBSTONE_CONTRACT_VERSION = "harness-source-deletion-tombstone.v1"
+
+MAX_SAFE_INTEGER = (1 << 53) - 1
+MAX_QUERY_BYTES = 16_384
+MAX_TEXT = 4_096
+MAX_EVIDENCE = 32
+MAX_OBLIGATIONS = 32
+MAX_REFERENCES = 10_000
+
+_IDENTIFIER = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+_SEMVER = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_SECRET_REF = re.compile(r"^shr_[A-Za-z0-9_-]{24,120}$")
+_MEDIA_TYPE = re.compile(r"^[a-z0-9][a-z0-9.+-]{0,126}/[a-z0-9][a-z0-9.+-]{0,126}$")
+
+SOURCE_CLASSES = frozenset(
+    {
+        "external_adapter",
+        "user_file",
+        "user_url",
+        "user_api",
+        "stream",
+    }
+)
+DATA_FORMATS = _DATA_FORMATS
+CAPABILITIES = frozenset({"snapshot", "historical", "live", "refresh", "backfill", "stream"})
+RIGHTS_STATUSES = frozenset({"approved", "conditional", "unclear", "prohibited"})
+CLASSIFICATIONS = frozenset({"public", "internal", "confidential", "restricted", "rejected"})
+FITNESS_DECISIONS = frozenset({"selected", "rejected", "human_escalation_required"})
+PEER_ATTEMPT_OUTCOMES = frozenset({"transport_failure", "response", "response_failure"})
+FITNESS_DIMENSIONS = frozenset(
+    {
+        "question_relevance",
+        "output_grain",
+        "historical_coverage",
+        "gaps",
+        "liveness",
+        "publication_delay",
+        "update_frequency",
+        "granularity",
+        "geographic_entity_coverage",
+        "revision_behavior",
+        "schema_stability",
+        "authentication_rate_limits",
+        "rights",
+        "cost_maintenance",
+        "refresh_backfill_live_fit",
+    }
+)
+OBLIGATION_LIFECYCLES = frozenset({"candidate", "derivative", "redistribution", "publication"})
+# The exact three fields a Reader pin carries, spelled the way the recipe seals them.  An
+# exact key set rather than a minimum, so a fourth field cannot ride into the request digest
+# unnoticed and mean nothing to the adapter that reads it.
+READER_PIN_KEYS = frozenset({"family_id", "family_version", "decode_options"})
+# Canonical retention-evidence kinds; deletion.py keys its policy-field lookup by these strings.
+RETENTION_KINDS = ("raw", "derived", "logs", "review_evidence")
+
+
+class SourceContractError(ValueError):
+    """Stable fail-closed source-contract error."""
+
+    def __init__(self, code: str, path: str, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{path}: {detail} [{code}]")
+
+
+def decode_options_digest(options: Mapping[str, Any]) -> str:
+    """Digest over an exact set of Reader decode settings.
+
+    One formula with one home.  The recipe seals a source's ``decode_options`` and the
+    adapter records the digest of the settings a decode actually ran with; if those two
+    were computed by two textually separate rules, a drift in either would read as a
+    decoder impersonation rather than as the bug it is.  ``RecipeSource`` and
+    ``_adapter_steps`` both call this.
+    """
+
+    return canonical_sha256(dict(options))
+
+
+def require_canonical_timestamp(value: Any, path: str) -> str:
+    """The public spelling of the strict timestamp rule every temporal field obeys.
+
+    Exported so a document outside this module -- a rights decision's ``decided_at`` -- is
+    held to exactly the rule ``observed_at`` fields are held to, without a second validator
+    drifting from this one.
+    """
+
+    return _timestamp(value, path)
+
+
+class _CanonicalContract:
+    schema_version: ClassVar[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    @property
+    def canonical_bytes(self) -> bytes:
+        return canonical_json_bytes(self.to_dict())
+
+
+@dataclass(frozen=True)
+class EvidenceReference(_CanonicalContract):
+    """Immutable citation or recorded probe/document evidence."""
+
+    uri: str
+    observed_at: str
+    content_sha256: str
+    media_type: str
+
+    def __post_init__(self) -> None:
+        _https_uri(self.uri, "evidence.uri")
+        _timestamp(self.observed_at, "evidence.observed_at")
+        _digest(self.content_sha256, "evidence.content_sha256")
+        _media_type(self.media_type, "evidence.media_type")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "uri": self.uri,
+            "observed_at": self.observed_at,
+            "content_sha256": self.content_sha256,
+            "media_type": self.media_type,
+        }
+
+
+@dataclass(frozen=True)
+class LicenseObligation(_CanonicalContract):
+    """Machine-enforced source-license obligation."""
+
+    obligation_id: str
+    applies_at: tuple[str, ...]
+    permitted_uses: tuple[str, ...]
+    prohibited_uses: tuple[str, ...]
+    required_artifact_digests: tuple[str, ...]
+    escalation_when_ambiguous: bool
+
+    def __post_init__(self) -> None:
+        _identifier(self.obligation_id, "obligation.obligation_id")
+        _choices(
+            self.applies_at,
+            OBLIGATION_LIFECYCLES,
+            "obligation.applies_at",
+            nonempty=True,
+            # Derived for the same reason as ``adapter.data_formats`` below: the literal 4
+            # was this table's cardinality restated, so admitting a fifth lifecycle would
+            # have refused an obligation that named them all.
+            maximum=len(OBLIGATION_LIFECYCLES),
+        )
+        _texts(
+            self.permitted_uses,
+            "obligation.permitted_uses",
+            nonempty=False,
+            maximum=32,
+            item_maximum=200,
+        )
+        _texts(
+            self.prohibited_uses,
+            "obligation.prohibited_uses",
+            nonempty=False,
+            maximum=32,
+            item_maximum=200,
+        )
+        _digests(
+            self.required_artifact_digests,
+            "obligation.required_artifact_digests",
+            maximum=32,
+        )
+        if not self.permitted_uses and not self.prohibited_uses:
+            raise SourceContractError(
+                "OBLIGATION_EMPTY",
+                "obligation",
+                "an obligation must constrain at least one permitted or prohibited use",
+            )
+
+    def applies(self, lifecycle: str, intended_use: str) -> bool:
+        _choice(lifecycle, OBLIGATION_LIFECYCLES, "lifecycle")
+        _text(intended_use, "intended_use", maximum=200)
+        if lifecycle not in self.applies_at:
+            return False
+        return not self.permitted_uses or intended_use in self.permitted_uses
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "obligation_id": self.obligation_id,
+            "applies_at": list(self.applies_at),
+            "permitted_uses": list(self.permitted_uses),
+            "prohibited_uses": list(self.prohibited_uses),
+            "required_artifact_digests": list(self.required_artifact_digests),
+            "escalation_when_ambiguous": self.escalation_when_ambiguous,
+        }
+
+
+@dataclass(frozen=True)
+class RightsEvidence(_CanonicalContract):
+    """Rights claim plus immutable evidence; never a human decision by itself."""
+
+    status: str
+    lawful_basis: str
+    allowed_uses: tuple[str, ...]
+    evidence: tuple[EvidenceReference, ...]
+    obligations: tuple[LicenseObligation, ...]
+    human_decision_reference: str | None = None
+
+    def __post_init__(self) -> None:
+        _choice(self.status, RIGHTS_STATUSES, "rights.status")
+        _text(self.lawful_basis, "rights.lawful_basis", maximum=1_000)
+        _texts(
+            self.allowed_uses,
+            "rights.allowed_uses",
+            nonempty=self.status in {"approved", "conditional"},
+            maximum=32,
+            item_maximum=200,
+        )
+        _typed_tuple(
+            self.evidence,
+            EvidenceReference,
+            "rights.evidence",
+            nonempty=True,
+            maximum=MAX_EVIDENCE,
+        )
+        _typed_tuple(
+            self.obligations,
+            LicenseObligation,
+            "rights.obligations",
+            nonempty=False,
+            maximum=MAX_OBLIGATIONS,
+        )
+        if self.human_decision_reference is not None:
+            _text(
+                self.human_decision_reference,
+                "rights.human_decision_reference",
+                maximum=200,
+            )
+        if self.status == "conditional" and not self.obligations:
+            raise SourceContractError(
+                "CONDITIONAL_WITHOUT_OBLIGATION",
+                "rights.obligations",
+                "conditional rights require at least one machine-readable obligation",
+            )
+        if self.status in {"unclear", "prohibited"} and self.human_decision_reference is not None:
+            raise SourceContractError(
+                "RIGHTS_AUTHORITY_CONFLICT",
+                "rights.human_decision_reference",
+                "unclear or prohibited source evidence cannot embed approval authority",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "lawful_basis": self.lawful_basis,
+            "allowed_uses": list(self.allowed_uses),
+            "evidence": [item.to_dict() for item in self.evidence],
+            "obligations": [item.to_dict() for item in self.obligations],
+            "human_decision_reference": self.human_decision_reference,
+        }
+
+
+@dataclass(frozen=True)
+class RetentionPolicy(_CanonicalContract):
+    """Coordinator-owned retention policy in whole days."""
+
+    raw_days: int
+    derived_days: int
+    log_days: int
+    review_evidence_days: int
+    tombstone_required: bool = True
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("raw_days", self.raw_days),
+            ("derived_days", self.derived_days),
+            ("log_days", self.log_days),
+            ("review_evidence_days", self.review_evidence_days),
+        ):
+            _integer(value, f"retention.{name}", minimum=0, maximum=3_650)
+        if self.tombstone_required is not True:
+            raise SourceContractError(
+                "TOMBSTONE_REQUIRED",
+                "retention.tombstone_required",
+                "V1 deletion must retain an immutable tombstone",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "raw_days": self.raw_days,
+            "derived_days": self.derived_days,
+            "log_days": self.log_days,
+            "review_evidence_days": self.review_evidence_days,
+            "tombstone_required": self.tombstone_required,
+        }
+
+
+@dataclass(frozen=True)
+class AdapterDescriptor(_CanonicalContract):
+    """One allowlisted source adapter identity and capability set."""
+
+    adapter_id: str
+    adapter_version: str
+    source_class: str
+    data_formats: tuple[str, ...]
+    capabilities: tuple[str, ...]
+    schema_version: str = ADAPTER_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, ADAPTER_CONTRACT_VERSION, "adapter.schema_version")
+        _identifier(self.adapter_id, "adapter.adapter_id")
+        _semver(self.adapter_version, "adapter.adapter_version")
+        _choice(self.source_class, SOURCE_CLASSES, "adapter.source_class")
+        _choices(
+            self.data_formats,
+            DATA_FORMATS,
+            "adapter.data_formats",
+            nonempty=True,
+            # Derive the bound from the allowlist so table changes cannot leave a stale literal.
+            maximum=len(DATA_FORMATS),
+        )
+        _choices(
+            self.capabilities,
+            CAPABILITIES,
+            "adapter.capabilities",
+            nonempty=True,
+            maximum=8,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "adapter_id": self.adapter_id,
+            "adapter_version": self.adapter_version,
+            "source_class": self.source_class,
+            "data_formats": list(self.data_formats),
+            "capabilities": list(self.capabilities),
+        }
+
+
+@dataclass(frozen=True)
+class AcquisitionRequest(_CanonicalContract):
+    """Coordinator-authorized source request.
+
+    ``reader_pin`` is authority, not a locator: it names which decoder the coordinator
+    entitles this acquisition to run, exactly as the recipe sealed it.  It rides the
+    request rather than the adapter query because the query is the address of the bytes
+    and each adapter pins its own exact query key set; a decoder entitlement is neither.
+
+    The pin is inside ``to_dict`` and therefore inside ``digest``, which the receipt binds
+    as ``request_digest``.  A pin swapped after authorization changes the digest and fails
+    that binding, so the entitlement cannot be edited in transit without leaving a trace.
+    """
+
+    request_id: str
+    source_id: str
+    adapter_id: str
+    adapter_version: str
+    intended_use: str
+    output_grain: tuple[str, ...]
+    query: Mapping[str, Any]
+    credential_reference_id: str | None
+    requested_at: str
+    schema_version: str = SOURCE_CONTRACT_VERSION
+    reader_pin: Mapping[str, Any] | None = None
+    # The recipe's own decode budgets, carried to the clean room the same way the pin is.
+    # They are authority in the narrowing direction only -- ``ReaderBudgets.narrowed_by`` takes
+    # a per-field minimum -- so a request can tighten what the family allows and can never buy
+    # more room than it allows.  ``None`` for a source that stated none, which is every source
+    # a direct fetch serves.
+    resource_caps: Mapping[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, SOURCE_CONTRACT_VERSION, "request.schema_version")
+        _identifier(self.request_id, "request.request_id")
+        _identifier(self.source_id, "request.source_id")
+        _identifier(self.adapter_id, "request.adapter_id")
+        _semver(self.adapter_version, "request.adapter_version")
+        _text(self.intended_use, "request.intended_use", maximum=200)
+        _texts(
+            self.output_grain,
+            "request.output_grain",
+            nonempty=True,
+            maximum=16,
+            item_maximum=128,
+        )
+        _query(self.query, "request.query")
+        if self.credential_reference_id is not None and not _SECRET_REF.fullmatch(
+            self.credential_reference_id
+        ):
+            raise SourceContractError(
+                "SECRET_REFERENCE",
+                "request.credential_reference_id",
+                "must be an opaque server-issued shr_ reference",
+            )
+        _timestamp(self.requested_at, "request.requested_at")
+        if self.reader_pin is not None:
+            _reader_pin(self.reader_pin, "request.reader_pin")
+        if self.resource_caps is not None:
+            _resource_caps(self.resource_caps, "request.resource_caps")
+        if self.resource_caps is not None and self.reader_pin is None:
+            raise SourceContractError(
+                "DECODE_CAPS",
+                "request.resource_caps",
+                "decode budgets without a Reader pin name a decode that will not happen",
+            )
+
+    @property
+    def query_digest(self) -> str:
+        return canonical_sha256(dict(self.query))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "request_id": self.request_id,
+            "source_id": self.source_id,
+            "adapter_id": self.adapter_id,
+            "adapter_version": self.adapter_version,
+            "intended_use": self.intended_use,
+            "output_grain": list(self.output_grain),
+            "query": dict(self.query),
+            "credential_reference_id": self.credential_reference_id,
+            "requested_at": self.requested_at,
+            "reader_pin": None if self.reader_pin is None else dict(self.reader_pin),
+            # Present only when stated, unlike ``reader_pin``, which spells its absence as a
+            # null.  The difference is deliberate and it is about evidence already written: a
+            # null here would change the canonical bytes -- and therefore ``request_digest``,
+            # which every receipt binds -- for every request in existence, including the ones
+            # that decode nothing.  Omission keeps an unchanged request byte-identical to what
+            # it was, and a stated cap is inside the digest exactly as the pin is, so it cannot
+            # be edited in transit without failing the receipt's binding.
+            **({} if self.resource_caps is None else {"resource_caps": dict(self.resource_caps)}),
+        }
+
+
+@dataclass(frozen=True)
+class SourceObservation(_CanonicalContract):
+    """Time-bound source liveness and temporal fitness evidence."""
+
+    source_id: str
+    observed_at: str
+    event_time_field: str | None
+    available_at_field: str | None
+    historical_start: str
+    historical_end: str
+    live_status: str
+    publication_delay_seconds: int
+    update_frequency_seconds: int
+    response_status: int | None
+    evidence: tuple[EvidenceReference, ...]
+    schema_version: str = OBSERVATION_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, OBSERVATION_CONTRACT_VERSION, "observation.schema_version")
+        _identifier(self.source_id, "observation.source_id")
+        _timestamp(self.observed_at, "observation.observed_at")
+        for name, value in (
+            ("event_time_field", self.event_time_field),
+            ("available_at_field", self.available_at_field),
+        ):
+            if value is not None:
+                _text(value, f"observation.{name}", maximum=128)
+        start = _timestamp(self.historical_start, "observation.historical_start")
+        end = _timestamp(self.historical_end, "observation.historical_end")
+        if start > end:
+            raise SourceContractError(
+                "TEMPORAL_ORDER",
+                "observation.historical_end",
+                "historical_end must not precede historical_start",
+            )
+        _choice(
+            self.live_status,
+            {"live", "delayed", "dead", "not_applicable"},
+            "observation.live_status",
+        )
+        _integer(
+            self.publication_delay_seconds,
+            "observation.publication_delay_seconds",
+            minimum=0,
+            maximum=10 * 365 * 24 * 60 * 60,
+        )
+        _integer(
+            self.update_frequency_seconds,
+            "observation.update_frequency_seconds",
+            minimum=0,
+            maximum=10 * 365 * 24 * 60 * 60,
+        )
+        if self.response_status is not None:
+            _integer(self.response_status, "observation.response_status", minimum=100, maximum=599)
+        _typed_tuple(
+            self.evidence,
+            EvidenceReference,
+            "observation.evidence",
+            nonempty=True,
+            maximum=MAX_EVIDENCE,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "source_id": self.source_id,
+            "observed_at": self.observed_at,
+            "event_time_field": self.event_time_field,
+            "available_at_field": self.available_at_field,
+            "historical_start": self.historical_start,
+            "historical_end": self.historical_end,
+            "live_status": self.live_status,
+            "publication_delay_seconds": self.publication_delay_seconds,
+            "update_frequency_seconds": self.update_frequency_seconds,
+            "response_status": self.response_status,
+            "evidence": [item.to_dict() for item in self.evidence],
+        }
+
+
+@dataclass(frozen=True)
+class SnapshotReference(_CanonicalContract):
+    """Immutable exact-byte snapshot reference."""
+
+    content_sha256: str
+    size_bytes: int
+    media_type: str
+    data_format: str
+    storage_name: str
+
+    def __post_init__(self) -> None:
+        _digest(self.content_sha256, "snapshot.content_sha256")
+        _integer(self.size_bytes, "snapshot.size_bytes", minimum=0, maximum=1 << 34)
+        _media_type(self.media_type, "snapshot.media_type")
+        _choice(self.data_format, DATA_FORMATS, "snapshot.data_format")
+        _safe_storage_name(self.storage_name, "snapshot.storage_name")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "content_sha256": self.content_sha256,
+            "size_bytes": self.size_bytes,
+            "media_type": self.media_type,
+            "data_format": self.data_format,
+            "storage_name": self.storage_name,
+        }
+
+
+@dataclass(frozen=True)
+class AcquisitionReceipt(_CanonicalContract):
+    """Digest-bound acquisition outcome, including how the bytes were decoded.
+
+    The identity chain has three links and each keeps its own name.  ``fetched`` is the
+    bytes as they arrived from the source, recorded here as ``fetched_content_sha256``.
+    ``acquired`` is the sealed snapshot, which under normalize-once is derived from the
+    fetched bytes rather than identical to them; its hash is ``snapshot.content_sha256``.
+    ``materialized`` is the post-merge artifact the recipe layer records separately as
+    ``acquired_content_sha256``.  Collapsing any two of these names would let one link of
+    the chain impersonate another, so the distinction is deliberate.
+
+    Recording both hashes is what makes a derived snapshot auditable: without the fetched
+    hash, a normalized artifact has no link back to the bytes that produced it.
+
+    Decode identity -- ``family_id``, ``family_version``, ``decode_options_digest`` -- is
+    all-present or all-absent.  A receipt can never claim a Reader family without pinning
+    its settings, nor settings without a family.  All three are absent for an acquisition
+    that performed no decode, which is a direct fetch.
+
+    ``decode_flags`` is a different kind of thing and is kept separate for that reason.
+    Decode identity records the settings a decode was *given*; a flag records a fact the
+    decode *found* -- "this spreadsheet held formulas and the values read were the ones the
+    authoring application had cached" is provenance a reader of the dataset is owed, and it
+    is not derivable from the settings.  The vocabulary is closed and shared with
+    ``readers.contracts.DECODE_FLAGS``, and flags are empty when nothing decoded, because a
+    flag without a decode describes nothing.
+
+    Known property, stated rather than buried: on a **Reader-decoded** acquisition,
+    classification and the rights gate scan the acquired (normalized) artifact rather than the
+    raw fetched bytes.  The decode runs first and the scan reads what it produced, so a secret
+    living in a container member the Reader discards never reaches classification, and one the
+    Reader emits does.  That is accepted because the normalized artifact is the data a build
+    reads, but it means a rights decision on a decoded source describes the derived form.  On a
+    **direct fetch** nothing is derived and the fetched bytes are the scanned bytes, which is why
+    the two hashes above coincide there and diverge here.
+    """
+
+    receipt_id: str
+    request_digest: str
+    source_id: str
+    adapter: AdapterDescriptor
+    query_digest: str
+    snapshot: SnapshotReference
+    fetched_content_sha256: str
+    family_id: str | None
+    family_version: str | None
+    decode_options_digest: str | None
+    source_uri: str
+    final_uri: str
+    event_time_field: str | None
+    observed_at: str
+    available_at: str
+    ingested_at: str
+    classification: str
+    rights_digest: str
+    retention_digest: str
+    observation_digest: str
+    transport_evidence_digest: str
+    schema_version: str = RECEIPT_CONTRACT_VERSION
+    decode_flags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, RECEIPT_CONTRACT_VERSION, "receipt.schema_version")
+        _identifier(self.receipt_id, "receipt.receipt_id")
+        _digest(self.request_digest, "receipt.request_digest")
+        _identifier(self.source_id, "receipt.source_id")
+        if not isinstance(self.adapter, AdapterDescriptor):
+            raise SourceContractError("TYPE", "receipt.adapter", "must be an AdapterDescriptor")
+        _digest(self.query_digest, "receipt.query_digest")
+        if not isinstance(self.snapshot, SnapshotReference):
+            raise SourceContractError("TYPE", "receipt.snapshot", "must be a SnapshotReference")
+        _digest(self.fetched_content_sha256, "receipt.fetched_content_sha256")
+        decode_identity = (self.family_id, self.family_version, self.decode_options_digest)
+        present = tuple(item is not None for item in decode_identity)
+        if any(present) and not all(present):
+            raise SourceContractError(
+                "DECODE_IDENTITY",
+                "receipt.family_id",
+                "family_id, family_version, and decode_options_digest "
+                "are all present or all absent",
+            )
+        if all(present):
+            _identifier(self.family_id, "receipt.family_id")
+            _semver(self.family_version, "receipt.family_version")
+            _digest(self.decode_options_digest, "receipt.decode_options_digest")
+        _decode_flags(self.decode_flags, "receipt.decode_flags", family_id=self.family_id)
+        _acquisition_uri(
+            self.source_uri,
+            "receipt.source_uri",
+            source_class=self.adapter.source_class,
+        )
+        _acquisition_uri(
+            self.final_uri,
+            "receipt.final_uri",
+            source_class=self.adapter.source_class,
+        )
+        if self.event_time_field is not None:
+            _text(self.event_time_field, "receipt.event_time_field", maximum=128)
+        observed = _timestamp(self.observed_at, "receipt.observed_at")
+        available = _timestamp(self.available_at, "receipt.available_at")
+        ingested = _timestamp(self.ingested_at, "receipt.ingested_at")
+        if observed > ingested or available > ingested:
+            raise SourceContractError(
+                "TEMPORAL_ORDER",
+                "receipt.ingested_at",
+                "ingested_at must not precede observed_at or available_at",
+            )
+        _choice(self.classification, CLASSIFICATIONS, "receipt.classification")
+        if self.classification == "rejected":
+            raise SourceContractError(
+                "REJECTED_NOT_RECEIPT",
+                "receipt.classification",
+                "rejected content cannot receive an admitted acquisition receipt",
+            )
+        _digest(self.rights_digest, "receipt.rights_digest")
+        _digest(self.retention_digest, "receipt.retention_digest")
+        _digest(self.observation_digest, "receipt.observation_digest")
+        _digest(self.transport_evidence_digest, "receipt.transport_evidence_digest")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "receipt_id": self.receipt_id,
+            "request_digest": self.request_digest,
+            "source_id": self.source_id,
+            "adapter": self.adapter.to_dict(),
+            "query_digest": self.query_digest,
+            "snapshot": self.snapshot.to_dict(),
+            "fetched_content_sha256": self.fetched_content_sha256,
+            "family_id": self.family_id,
+            "family_version": self.family_version,
+            "decode_options_digest": self.decode_options_digest,
+            "decode_flags": list(self.decode_flags),
+            "source_uri": self.source_uri,
+            "final_uri": self.final_uri,
+            "event_time_field": self.event_time_field,
+            "observed_at": self.observed_at,
+            "available_at": self.available_at,
+            "ingested_at": self.ingested_at,
+            "classification": self.classification,
+            "rights_digest": self.rights_digest,
+            "retention_digest": self.retention_digest,
+            "observation_digest": self.observation_digest,
+            "transport_evidence_digest": self.transport_evidence_digest,
+        }
+
+
+# Exact keys written by ``AcquisitionReceipt.to_dict``. Read paths validate this shape because the
+# schema label alone does not distinguish older key sets. Derivation prevents drift from the
+# dataclass.
+RECEIPT_DOCUMENT_KEYS: frozenset[str] = frozenset(
+    field.name for field in fields(AcquisitionReceipt)
+)
+
+
+@dataclass(frozen=True)
+class PeerAttempt(_CanonicalContract):
+    """One canonical attempt against a resolver-approved public address."""
+
+    approved_ip: str
+    outcome: str
+    failure_code: str | None
+
+    def __post_init__(self) -> None:
+        _text(self.approved_ip, "peer_attempt.approved_ip", maximum=64)
+        try:
+            address = ipaddress.ip_address(self.approved_ip)
+        except ValueError as error:
+            raise SourceContractError(
+                "VALUE", "peer_attempt.approved_ip", "must be an IP address"
+            ) from error
+        if str(address) != self.approved_ip or not address.is_global:
+            raise SourceContractError(
+                "VALUE",
+                "peer_attempt.approved_ip",
+                "must be a canonical public IP address",
+            )
+        _choice(self.outcome, PEER_ATTEMPT_OUTCOMES, "peer_attempt.outcome")
+        if self.outcome == "response":
+            if self.failure_code is not None:
+                raise SourceContractError(
+                    "VALUE", "peer_attempt.failure_code", "must be null for a response"
+                )
+        else:
+            _text(self.failure_code, "peer_attempt.failure_code", maximum=128)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "approved_ip": self.approved_ip,
+            "outcome": self.outcome,
+            "failure_code": self.failure_code,
+        }
+
+
+@dataclass(frozen=True)
+class FetchedMember(_CanonicalContract):
+    """One measured response body in a v2 multi-member acquisition."""
+
+    role: str
+    sequence: int
+    url: str
+    resolution_digest: str
+    connected_peer: str
+    status: int
+    response_headers_digest: str
+    response_body_size_bytes: int
+    response_body_sha256: str
+    requested_range: str | None
+    observed_content_range: str | None
+    etag: str | None
+    last_modified: str | None
+    peer_attempts: tuple[PeerAttempt, ...]
+
+    def __post_init__(self) -> None:
+        if isinstance(self.peer_attempts, list):
+            parsed_attempts: list[PeerAttempt] = []
+            for index, raw_attempt in enumerate(self.peer_attempts):
+                attempt = _object(raw_attempt, f"fetched_member.peer_attempts[{index}]")
+                _exact(
+                    attempt,
+                    {"approved_ip", "outcome", "failure_code"},
+                    f"fetched_member.peer_attempts[{index}]",
+                )
+                parsed_attempts.append(PeerAttempt(**attempt))
+            object.__setattr__(self, "peer_attempts", tuple(parsed_attempts))
+        _choice(
+            self.role,
+            {"cycle_probe", "sidecar_initial", "selected_slice", "sidecar_final"},
+            "fetched_member.role",
+        )
+        _integer(self.sequence, "fetched_member.sequence", minimum=0, maximum=255)
+        _text(self.url, "fetched_member.url", maximum=2_048)
+        _digest(self.resolution_digest, "fetched_member.resolution_digest")
+        _text(self.connected_peer, "fetched_member.connected_peer", maximum=64)
+        _integer(self.status, "fetched_member.status", minimum=100, maximum=599)
+        _digest(self.response_headers_digest, "fetched_member.response_headers_digest")
+        _integer(
+            self.response_body_size_bytes,
+            "fetched_member.response_body_size_bytes",
+            minimum=0,
+            maximum=1 << 34,
+        )
+        _digest(self.response_body_sha256, "fetched_member.response_body_sha256")
+        for name, value, maximum in (
+            ("requested_range", self.requested_range, 128),
+            ("observed_content_range", self.observed_content_range, 128),
+            ("etag", self.etag, 1_024),
+            ("last_modified", self.last_modified, 1_024),
+        ):
+            if value is not None:
+                _text(value, f"fetched_member.{name}", maximum=maximum)
+        if (
+            not isinstance(self.peer_attempts, tuple)
+            or not 1 <= len(self.peer_attempts) <= 32
+            or any(not isinstance(attempt, PeerAttempt) for attempt in self.peer_attempts)
+        ):
+            raise SourceContractError(
+                "TYPE",
+                "fetched_member.peer_attempts",
+                "must be a non-empty bounded tuple of typed attempts",
+            )
+        if any(attempt.outcome != "transport_failure" for attempt in self.peer_attempts[:-1]):
+            raise SourceContractError(
+                "VALUE",
+                "fetched_member.peer_attempts",
+                "only transport failures may precede the terminal attempt",
+            )
+        if self.peer_attempts[-1].outcome != "response":
+            raise SourceContractError(
+                "VALUE",
+                "fetched_member.peer_attempts",
+                "a retained response must terminate with a successful response attempt",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        document = {field.name: getattr(self, field.name) for field in fields(self)}
+        document["peer_attempts"] = [attempt.to_dict() for attempt in self.peer_attempts]
+        return document
+
+    def hop_document(self) -> dict[str, Any]:
+        return {
+            key: value for key, value in self.to_dict().items() if key not in {"role", "sequence"}
+        }
+
+
+def fetched_source_revision_digest(
+    cycle: str,
+    full_object_size_bytes: int,
+    members: tuple[FetchedMember, ...],
+) -> str:
+    """Derive the sealed source revision solely from measured member evidence."""
+
+    return canonical_sha256(
+        {
+            "cycle": cycle,
+            "full_object_size_bytes": full_object_size_bytes,
+            "members": [
+                {
+                    "role": member.role,
+                    "url": member.url,
+                    "response_body_size_bytes": member.response_body_size_bytes,
+                    "response_body_sha256": member.response_body_sha256,
+                    "requested_range": member.requested_range,
+                    "observed_content_range": member.observed_content_range,
+                    "etag": member.etag,
+                    "last_modified": member.last_modified,
+                }
+                for member in members
+            ],
+        }
+    )
+
+
+@dataclass(frozen=True)
+class AcquisitionReceiptV2(_CanonicalContract):
+    """Strict multi-response receipt used by range-fetch plus Reader composition.
+
+    Version 1 remains unchanged.  Version 2 retains every response body, validator and range
+    in order, so its transport digest and efficiency result are recomputable from the sealed
+    document rather than supplied as summary testimony.
+    """
+
+    receipt_id: str
+    request_digest: str
+    source_id: str
+    adapter: AdapterDescriptor
+    query_digest: str
+    snapshot: SnapshotReference
+    fetched_content_sha256: str
+    family_id: str
+    family_version: str
+    decode_options_digest: str
+    source_uri: str
+    final_uri: str
+    event_time_field: str | None
+    observed_at: str
+    available_at: str
+    ingested_at: str
+    classification: str
+    rights_digest: str
+    retention_digest: str
+    observation_digest: str
+    transport_evidence_digest: str
+    fetched_members: tuple[FetchedMember, ...]
+    cycle: str
+    revision_lock_digest: str
+    source_revision_digest: str
+    full_object_size_bytes: int
+    efficiency_numerator: int
+    efficiency_denominator: int
+    fetch_policy_digest: str
+    decode_policy_digest: str
+    parsed_schema_digest: str
+    schema_version: str = RECEIPT_CONTRACT_VERSION_V2
+    decode_flags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, RECEIPT_CONTRACT_VERSION_V2, "receipt.schema_version")
+        _identifier(self.receipt_id, "receipt.receipt_id")
+        _digest(self.request_digest, "receipt.request_digest")
+        _identifier(self.source_id, "receipt.source_id")
+        if not isinstance(self.adapter, AdapterDescriptor):
+            raise SourceContractError("TYPE", "receipt.adapter", "must be an AdapterDescriptor")
+        _digest(self.query_digest, "receipt.query_digest")
+        if not isinstance(self.snapshot, SnapshotReference):
+            raise SourceContractError("TYPE", "receipt.snapshot", "must be a SnapshotReference")
+        for path, value in (
+            ("receipt.fetched_content_sha256", self.fetched_content_sha256),
+            ("receipt.decode_options_digest", self.decode_options_digest),
+            ("receipt.rights_digest", self.rights_digest),
+            ("receipt.retention_digest", self.retention_digest),
+            ("receipt.observation_digest", self.observation_digest),
+            ("receipt.transport_evidence_digest", self.transport_evidence_digest),
+            ("receipt.revision_lock_digest", self.revision_lock_digest),
+            ("receipt.source_revision_digest", self.source_revision_digest),
+            ("receipt.fetch_policy_digest", self.fetch_policy_digest),
+            ("receipt.decode_policy_digest", self.decode_policy_digest),
+            ("receipt.parsed_schema_digest", self.parsed_schema_digest),
+        ):
+            _digest(value, path)
+        _identifier(self.family_id, "receipt.family_id")
+        _semver(self.family_version, "receipt.family_version")
+        _decode_flags(self.decode_flags, "receipt.decode_flags", family_id=self.family_id)
+        _acquisition_uri(
+            self.source_uri, "receipt.source_uri", source_class=self.adapter.source_class
+        )
+        _acquisition_uri(
+            self.final_uri, "receipt.final_uri", source_class=self.adapter.source_class
+        )
+        if self.event_time_field is not None:
+            _text(self.event_time_field, "receipt.event_time_field", maximum=128)
+        observed = _timestamp(self.observed_at, "receipt.observed_at")
+        available = _timestamp(self.available_at, "receipt.available_at")
+        ingested = _timestamp(self.ingested_at, "receipt.ingested_at")
+        if observed > ingested or available > ingested:
+            raise SourceContractError(
+                "TEMPORAL_ORDER",
+                "receipt.ingested_at",
+                "ingested_at must not precede observed_at or available_at",
+            )
+        _choice(self.classification, CLASSIFICATIONS - {"rejected"}, "receipt.classification")
+        _text(self.cycle, "receipt.cycle", maximum=128)
+        _integer(
+            self.full_object_size_bytes,
+            "receipt.full_object_size_bytes",
+            minimum=1,
+            maximum=1 << 44,
+        )
+        _integer(
+            self.efficiency_numerator,
+            "receipt.efficiency_numerator",
+            minimum=1,
+            maximum=1 << 44,
+        )
+        _integer(
+            self.efficiency_denominator,
+            "receipt.efficiency_denominator",
+            minimum=1,
+            maximum=1 << 44,
+        )
+        if self.efficiency_denominator != self.full_object_size_bytes:
+            raise SourceContractError(
+                "RECEIPT_ACCOUNTING",
+                "receipt.efficiency_denominator",
+                "must equal the complete source-object size",
+            )
+        if not isinstance(self.fetched_members, tuple) or not 4 <= len(self.fetched_members) <= 256:
+            raise SourceContractError(
+                "RECEIPT_MEMBERS", "receipt.fetched_members", "must be a bounded typed tuple"
+            )
+        if any(not isinstance(member, FetchedMember) for member in self.fetched_members):
+            raise SourceContractError(
+                "RECEIPT_MEMBERS", "receipt.fetched_members", "contains an untyped member"
+            )
+        if tuple(member.sequence for member in self.fetched_members) != tuple(
+            range(len(self.fetched_members))
+        ):
+            raise SourceContractError(
+                "RECEIPT_MEMBERS", "receipt.fetched_members", "sequence is not contiguous"
+            )
+        roles = tuple(member.role for member in self.fetched_members)
+        collapsed = tuple(
+            role for index, role in enumerate(roles) if index == 0 or role != roles[index - 1]
+        )
+        if collapsed != ("sidecar_initial", "cycle_probe", "selected_slice", "sidecar_final"):
+            raise SourceContractError(
+                "RECEIPT_MEMBERS", "receipt.fetched_members", "acquisition stages are incomplete"
+            )
+        terminal_by_role = {
+            role: self.fetched_members[
+                max(index for index, value in enumerate(roles) if value == role)
+            ]
+            for role in collapsed
+        }
+        if any(
+            member.etag is None and member.last_modified is None
+            for member in terminal_by_role.values()
+        ):
+            raise SourceContractError(
+                "RECEIPT_VALIDATOR",
+                "receipt.fetched_members",
+                "each fetched resource must carry ETag or Last-Modified evidence",
+            )
+        initial = terminal_by_role["sidecar_initial"]
+        final = terminal_by_role["sidecar_final"]
+        if (
+            initial.url != final.url
+            or initial.response_body_size_bytes != final.response_body_size_bytes
+            or initial.response_body_sha256 != final.response_body_sha256
+            or (initial.etag, initial.last_modified) != (final.etag, final.last_modified)
+        ):
+            raise SourceContractError(
+                "RECEIPT_REVISION",
+                "receipt.fetched_members",
+                "terminal sidecar evidence differs from the initial sidecar",
+            )
+        probe = terminal_by_role["cycle_probe"]
+        selected = terminal_by_role["selected_slice"]
+        if (probe.etag, probe.last_modified) != (selected.etag, selected.last_modified):
+            raise SourceContractError(
+                "RECEIPT_REVISION",
+                "receipt.fetched_members",
+                "cycle probe and selected object member name different revisions",
+            )
+        measured = sum(member.response_body_size_bytes for member in self.fetched_members)
+        if measured != self.efficiency_numerator or measured * 100 > self.efficiency_denominator:
+            raise SourceContractError(
+                "RECEIPT_ACCOUNTING",
+                "receipt.efficiency_numerator",
+                "does not equal all response bodies or exceeds one percent",
+            )
+        if (
+            fetched_source_revision_digest(
+                self.cycle, self.full_object_size_bytes, self.fetched_members
+            )
+            != self.source_revision_digest
+        ):
+            raise SourceContractError(
+                "RECEIPT_REVISION",
+                "receipt.source_revision_digest",
+                "does not rederive from the measured member evidence",
+            )
+        if (
+            canonical_sha256([member.hop_document() for member in self.fetched_members])
+            != self.transport_evidence_digest
+        ):
+            raise SourceContractError(
+                "RECEIPT_TRANSPORT",
+                "receipt.transport_evidence_digest",
+                "does not bind the complete fetched-member sequence",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        document = {field.name: getattr(self, field.name) for field in fields(self)}
+        document["adapter"] = self.adapter.to_dict()
+        document["snapshot"] = self.snapshot.to_dict()
+        document["fetched_members"] = [member.to_dict() for member in self.fetched_members]
+        document["decode_flags"] = list(self.decode_flags)
+        return document
+
+
+RECEIPT_DOCUMENT_KEYS_V2: frozenset[str] = frozenset(
+    field.name for field in fields(AcquisitionReceiptV2)
+)
+
+
+def parse_acquisition_receipt_v2(value: Any) -> AcquisitionReceiptV2:
+    """Parse and rederive every v2 receipt invariant from its sealed JSON document."""
+
+    data = _object(value, "receipt")
+    _exact(data, set(RECEIPT_DOCUMENT_KEYS_V2), "receipt")
+    snapshot_data = _object(data["snapshot"], "receipt.snapshot")
+    _exact(
+        snapshot_data,
+        {"content_sha256", "size_bytes", "media_type", "data_format", "storage_name"},
+        "receipt.snapshot",
+    )
+    raw_members = data["fetched_members"]
+    if not isinstance(raw_members, list):
+        raise SourceContractError("TYPE", "receipt.fetched_members", "must be an array")
+    member_keys = {field.name for field in fields(FetchedMember)}
+    members: list[FetchedMember] = []
+    for index, raw_member in enumerate(raw_members):
+        member_data = _object(raw_member, f"receipt.fetched_members[{index}]")
+        _exact(member_data, member_keys, f"receipt.fetched_members[{index}]")
+        members.append(FetchedMember(**member_data))
+    kwargs = dict(data)
+    kwargs["adapter"] = parse_adapter_descriptor(data["adapter"])
+    kwargs["snapshot"] = SnapshotReference(**snapshot_data)
+    kwargs["fetched_members"] = tuple(members)
+    kwargs["decode_flags"] = tuple(data["decode_flags"])
+    return AcquisitionReceiptV2(**kwargs)
+
+
+@dataclass(frozen=True)
+class CollectionMemberEvidence(_CanonicalContract):
+    """One exact, ordered input to a v3 collection acquisition.
+
+    A collection receipt names both the bytes that arrived and the canonical bytes the
+    collection assembler consumed.  Keeping those hashes separate preserves the same
+    fetched-versus-normalized identity chain as a v1 receipt while making the chain explicit
+    for every member rather than collapsing it into aggregate testimony.
+    """
+
+    member_id: str
+    sequence: int
+    source_uri: str
+    final_uri: str
+    fetched_content_sha256: str
+    fetched_size_bytes: int
+    normalized_content_sha256: str
+    normalized_size_bytes: int
+    request_count: int
+    row_count: int
+    column_count: int
+    declared_cell_count: int
+    parsed_schema_digest: str
+    transport_evidence_digest: str
+    decode_flags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _identifier(self.member_id, "collection_member.member_id")
+        _integer(self.sequence, "collection_member.sequence", minimum=0, maximum=255)
+        _https_uri(self.source_uri, "collection_member.source_uri")
+        _https_uri(self.final_uri, "collection_member.final_uri")
+        _digest(
+            self.fetched_content_sha256,
+            "collection_member.fetched_content_sha256",
+        )
+        _integer(
+            self.fetched_size_bytes,
+            "collection_member.fetched_size_bytes",
+            minimum=1,
+            maximum=1 << 34,
+        )
+        _digest(
+            self.normalized_content_sha256,
+            "collection_member.normalized_content_sha256",
+        )
+        _integer(
+            self.normalized_size_bytes,
+            "collection_member.normalized_size_bytes",
+            minimum=1,
+            maximum=1 << 34,
+        )
+        _integer(
+            self.request_count,
+            "collection_member.request_count",
+            minimum=1,
+            maximum=16,
+        )
+        _integer(
+            self.row_count,
+            "collection_member.row_count",
+            minimum=0,
+            maximum=10_000_000,
+        )
+        _integer(
+            self.column_count,
+            "collection_member.column_count",
+            minimum=1,
+            maximum=10_000,
+        )
+        _integer(
+            self.declared_cell_count,
+            "collection_member.declared_cell_count",
+            minimum=0,
+            maximum=(1 << 63) - 1,
+        )
+        if self.declared_cell_count != self.row_count * self.column_count:
+            raise SourceContractError(
+                "COLLECTION_CELL_LIMIT",
+                "collection_member.declared_cell_count",
+                "must equal the authenticated normalized table geometry",
+            )
+        _digest(self.parsed_schema_digest, "collection_member.parsed_schema_digest")
+        _digest(
+            self.transport_evidence_digest,
+            "collection_member.transport_evidence_digest",
+        )
+        # A member cannot decide which family ran, but any stated flag still has to be a real,
+        # canonical Reader flag.  The enclosing receipt separately proves that a family was
+        # pinned whenever any member reported one.
+        _decode_flags(
+            self.decode_flags,
+            "collection_member.decode_flags",
+            family_id="collection.member",
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "member_id": self.member_id,
+            "sequence": self.sequence,
+            "source_uri": self.source_uri,
+            "final_uri": self.final_uri,
+            "fetched_content_sha256": self.fetched_content_sha256,
+            "fetched_size_bytes": self.fetched_size_bytes,
+            "normalized_content_sha256": self.normalized_content_sha256,
+            "normalized_size_bytes": self.normalized_size_bytes,
+            "request_count": self.request_count,
+            "row_count": self.row_count,
+            "column_count": self.column_count,
+            "declared_cell_count": self.declared_cell_count,
+            "parsed_schema_digest": self.parsed_schema_digest,
+            "transport_evidence_digest": self.transport_evidence_digest,
+            "decode_flags": list(self.decode_flags),
+        }
+
+
+def collection_member_manifest_digest(members: tuple[CollectionMemberEvidence, ...]) -> str:
+    """Digest the complete ordered member evidence with the contract's one formula."""
+
+    return canonical_sha256([member.to_dict() for member in members])
+
+
+def collection_fetched_content_sha256(
+    members: tuple[CollectionMemberEvidence, ...],
+) -> str:
+    """Derive the collection's fetched-byte identity without claiming bytes were concatenated."""
+
+    return canonical_sha256(
+        [
+            {
+                "member_id": member.member_id,
+                "fetched_content_sha256": member.fetched_content_sha256,
+                "fetched_size_bytes": member.fetched_size_bytes,
+            }
+            for member in members
+        ]
+    )
+
+
+def collection_transport_evidence_digest(
+    members: tuple[CollectionMemberEvidence, ...],
+) -> str:
+    """Bind transport evidence to member identity and order."""
+
+    return canonical_sha256(
+        [
+            {
+                "member_id": member.member_id,
+                "transport_evidence_digest": member.transport_evidence_digest,
+            }
+            for member in members
+        ]
+    )
+
+
+@dataclass(frozen=True)
+class AcquisitionReceiptV3(_CanonicalContract):
+    """Strict ordered receipt for one bounded homogeneous public-source collection."""
+
+    receipt_id: str
+    request_digest: str
+    source_id: str
+    adapter: AdapterDescriptor
+    query_digest: str
+    snapshot: SnapshotReference
+    fetched_content_sha256: str
+    family_id: str
+    family_version: str
+    decode_options_digest: str
+    event_time_field: str | None
+    observed_at: str
+    available_at: str
+    ingested_at: str
+    classification: str
+    rights_digest: str
+    retention_digest: str
+    observation_digest: str
+    transport_evidence_digest: str
+    members: tuple[CollectionMemberEvidence, ...]
+    member_manifest_digest: str
+    parsed_schema_digest: str
+    schema_version: str = RECEIPT_CONTRACT_VERSION_V3
+    decode_flags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, RECEIPT_CONTRACT_VERSION_V3, "receipt.schema_version")
+        _identifier(self.receipt_id, "receipt.receipt_id")
+        _digest(self.request_digest, "receipt.request_digest")
+        _identifier(self.source_id, "receipt.source_id")
+        if not isinstance(self.adapter, AdapterDescriptor):
+            raise SourceContractError("TYPE", "receipt.adapter", "must be an AdapterDescriptor")
+        if (
+            self.adapter.adapter_id,
+            self.adapter.adapter_version,
+            self.adapter.source_class,
+            self.adapter.data_formats,
+            self.adapter.capabilities,
+        ) != (
+            "public.https.collection",
+            "1.0.0",
+            "external_adapter",
+            ("csv",),
+            ("snapshot", "refresh", "backfill"),
+        ):
+            raise SourceContractError(
+                "COLLECTION_ADAPTER",
+                "receipt.adapter",
+                "a v3 receipt requires the exact public HTTPS collection adapter",
+            )
+        _digest(self.query_digest, "receipt.query_digest")
+        if not isinstance(self.snapshot, SnapshotReference):
+            raise SourceContractError("TYPE", "receipt.snapshot", "must be a SnapshotReference")
+        if self.snapshot.data_format != "csv" or self.snapshot.media_type != "text/csv":
+            raise SourceContractError(
+                "COLLECTION_SNAPSHOT",
+                "receipt.snapshot",
+                "a collection snapshot must be canonical CSV",
+            )
+        for path, value in (
+            ("receipt.fetched_content_sha256", self.fetched_content_sha256),
+            ("receipt.rights_digest", self.rights_digest),
+            ("receipt.retention_digest", self.retention_digest),
+            ("receipt.observation_digest", self.observation_digest),
+            ("receipt.transport_evidence_digest", self.transport_evidence_digest),
+            ("receipt.member_manifest_digest", self.member_manifest_digest),
+            ("receipt.parsed_schema_digest", self.parsed_schema_digest),
+        ):
+            _digest(value, path)
+        _identifier(self.family_id, "receipt.family_id")
+        _semver(self.family_version, "receipt.family_version")
+        _digest(self.decode_options_digest, "receipt.decode_options_digest")
+        _decode_flags(self.decode_flags, "receipt.decode_flags", family_id=self.family_id)
+        if self.event_time_field is not None:
+            _text(self.event_time_field, "receipt.event_time_field", maximum=128)
+        observed = _timestamp(self.observed_at, "receipt.observed_at")
+        available = _timestamp(self.available_at, "receipt.available_at")
+        ingested = _timestamp(self.ingested_at, "receipt.ingested_at")
+        if observed > ingested or available > ingested:
+            raise SourceContractError(
+                "TEMPORAL_ORDER",
+                "receipt.ingested_at",
+                "ingested_at must not precede observed_at or available_at",
+            )
+        _choice(self.classification, CLASSIFICATIONS - {"rejected"}, "receipt.classification")
+        _typed_tuple(
+            self.members,
+            CollectionMemberEvidence,
+            "receipt.members",
+            nonempty=True,
+            maximum=16,
+        )
+        if tuple(member.sequence for member in self.members) != tuple(range(len(self.members))):
+            raise SourceContractError(
+                "COLLECTION_SEQUENCE",
+                "receipt.members",
+                "member sequence must be contiguous and start at zero",
+            )
+        member_ids = tuple(member.member_id for member in self.members)
+        if len(set(member_ids)) != len(member_ids):
+            raise SourceContractError(
+                "COLLECTION_MEMBER_ID",
+                "receipt.members",
+                "member IDs must be unique",
+            )
+        if sum(member.request_count for member in self.members) > 16:
+            raise SourceContractError(
+                "COLLECTION_REQUEST_LIMIT",
+                "receipt.members",
+                "aggregate member requests exceed the collection ceiling",
+            )
+        if any(member.parsed_schema_digest != self.parsed_schema_digest for member in self.members):
+            raise SourceContractError(
+                "COLLECTION_SCHEMA",
+                "receipt.members",
+                "every member must have the aggregate parsed schema",
+            )
+        member_flags = tuple(
+            sorted({flag for member in self.members for flag in member.decode_flags})
+        )
+        if member_flags != self.decode_flags:
+            raise SourceContractError(
+                "COLLECTION_DECODE_FLAGS",
+                "receipt.decode_flags",
+                "must equal the sorted union of member decode flags",
+            )
+        if collection_member_manifest_digest(self.members) != self.member_manifest_digest:
+            raise SourceContractError(
+                "COLLECTION_MANIFEST",
+                "receipt.member_manifest_digest",
+                "does not rederive from the ordered member evidence",
+            )
+        if collection_fetched_content_sha256(self.members) != self.fetched_content_sha256:
+            raise SourceContractError(
+                "COLLECTION_FETCHED_CONTENT",
+                "receipt.fetched_content_sha256",
+                "does not rederive from the ordered fetched-member evidence",
+            )
+        if collection_transport_evidence_digest(self.members) != self.transport_evidence_digest:
+            raise SourceContractError(
+                "COLLECTION_TRANSPORT",
+                "receipt.transport_evidence_digest",
+                "does not rederive from the ordered member transport evidence",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        document = {field.name: getattr(self, field.name) for field in fields(self)}
+        document["adapter"] = self.adapter.to_dict()
+        document["snapshot"] = self.snapshot.to_dict()
+        document["members"] = [member.to_dict() for member in self.members]
+        document["decode_flags"] = list(self.decode_flags)
+        return document
+
+
+RECEIPT_DOCUMENT_KEYS_V3: frozenset[str] = frozenset(
+    field.name for field in fields(AcquisitionReceiptV3)
+)
+
+
+def parse_acquisition_receipt_v3(value: Any) -> AcquisitionReceiptV3:
+    """Parse and rederive every v3 collection receipt invariant."""
+
+    data = _object(value, "receipt")
+    _exact(data, set(RECEIPT_DOCUMENT_KEYS_V3), "receipt")
+    snapshot_data = _object(data["snapshot"], "receipt.snapshot")
+    _exact(
+        snapshot_data,
+        {"content_sha256", "size_bytes", "media_type", "data_format", "storage_name"},
+        "receipt.snapshot",
+    )
+    raw_members = _array(data["members"], "receipt.members")
+    member_keys = {field.name for field in fields(CollectionMemberEvidence)}
+    members: list[CollectionMemberEvidence] = []
+    for index, raw_member in enumerate(raw_members):
+        member_data = _object(raw_member, f"receipt.members[{index}]")
+        _exact(member_data, member_keys, f"receipt.members[{index}]")
+        member_kwargs = dict(member_data)
+        member_kwargs["decode_flags"] = tuple(
+            _array(member_data["decode_flags"], f"receipt.members[{index}].decode_flags")
+        )
+        members.append(CollectionMemberEvidence(**member_kwargs))
+    kwargs = dict(data)
+    kwargs["adapter"] = parse_adapter_descriptor(data["adapter"])
+    kwargs["snapshot"] = SnapshotReference(**snapshot_data)
+    kwargs["members"] = tuple(members)
+    kwargs["decode_flags"] = tuple(_array(data["decode_flags"], "receipt.decode_flags"))
+    return AcquisitionReceiptV3(**kwargs)
+
+
+@dataclass(frozen=True)
+class FitnessEvidence(_CanonicalContract):
+    """One fitness dimension's outcome and the evidence digests cited for it."""
+
+    dimension: str
+    outcome: str
+    summary: str
+    evidence_digests: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        _choice(self.dimension, FITNESS_DIMENSIONS, "fitness_evidence.dimension")
+        _choice(self.outcome, {"pass", "fail", "unknown"}, "fitness_evidence.outcome")
+        _text(self.summary, "fitness_evidence.summary", maximum=1_000)
+        _digests(
+            self.evidence_digests,
+            "fitness_evidence.evidence_digests",
+            nonempty=True,
+            maximum=MAX_EVIDENCE,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "dimension": self.dimension,
+            "outcome": self.outcome,
+            "summary": self.summary,
+            "evidence_digests": list(self.evidence_digests),
+        }
+
+
+@dataclass(frozen=True)
+class FitnessReport(_CanonicalContract):
+    """One source's cited decision over every fitness dimension; built by build_fitness_report."""
+
+    report_id: str
+    question_id: str
+    source_id: str
+    observed_at: str
+    intended_use: str
+    dimensions: tuple[FitnessEvidence, ...]
+    decision: str
+    decision_reason: str
+    rights_digest: str
+    observation_digest: str
+    schema_version: str = FITNESS_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, FITNESS_CONTRACT_VERSION, "fitness.schema_version")
+        _identifier(self.report_id, "fitness.report_id")
+        _identifier(self.question_id, "fitness.question_id")
+        _identifier(self.source_id, "fitness.source_id")
+        _timestamp(self.observed_at, "fitness.observed_at")
+        _text(self.intended_use, "fitness.intended_use", maximum=200)
+        _typed_tuple(
+            self.dimensions,
+            FitnessEvidence,
+            "fitness.dimensions",
+            nonempty=True,
+            maximum=len(FITNESS_DIMENSIONS),
+        )
+        seen = {item.dimension for item in self.dimensions}
+        if seen != FITNESS_DIMENSIONS:
+            missing = sorted(FITNESS_DIMENSIONS - seen)
+            extra = sorted(seen - FITNESS_DIMENSIONS)
+            raise SourceContractError(
+                "FITNESS_DIMENSIONS",
+                "fitness.dimensions",
+                f"must contain every dimension exactly once; missing={missing}, extra={extra}",
+            )
+        if len(seen) != len(self.dimensions):
+            raise SourceContractError(
+                "DUPLICATE",
+                "fitness.dimensions",
+                "fitness dimensions must be unique",
+            )
+        _choice(self.decision, FITNESS_DECISIONS, "fitness.decision")
+        _text(self.decision_reason, "fitness.decision_reason", maximum=1_000)
+        _digest(self.rights_digest, "fitness.rights_digest")
+        _digest(self.observation_digest, "fitness.observation_digest")
+        outcomes = {item.outcome for item in self.dimensions}
+        if self.decision == "selected" and outcomes != {"pass"}:
+            raise SourceContractError(
+                "UNFIT_SELECTED",
+                "fitness.decision",
+                "selected sources require every fitness dimension to pass",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "report_id": self.report_id,
+            "question_id": self.question_id,
+            "source_id": self.source_id,
+            "observed_at": self.observed_at,
+            "intended_use": self.intended_use,
+            "dimensions": [item.to_dict() for item in self.dimensions],
+            "decision": self.decision,
+            "decision_reason": self.decision_reason,
+            "rights_digest": self.rights_digest,
+            "observation_digest": self.observation_digest,
+        }
+
+
+@dataclass(frozen=True)
+class DeletedReference(_CanonicalContract):
+    """One artifact covered by a deletion, named by kind and digest, listed in the tombstone."""
+
+    reference_kind: str
+    reference_digest: str
+
+    def __post_init__(self) -> None:
+        _choice(
+            self.reference_kind,
+            {"candidate", "manifest", "receipt", "derived_artifact", "review"},
+            "deleted_reference.reference_kind",
+        )
+        _digest(self.reference_digest, "deleted_reference.reference_digest")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "reference_kind": self.reference_kind,
+            "reference_digest": self.reference_digest,
+        }
+
+
+@dataclass(frozen=True)
+class DeletionTombstone(_CanonicalContract):
+    """Separate immutable status envelope; referenced sealed bytes are never rewritten."""
+
+    tombstone_id: str
+    removed_content_sha256: str
+    removed_at: str
+    reason_code: str
+    policy_digest: str
+    complete_reference_set_digest: str
+    references: tuple[DeletedReference, ...]
+    byte_removal_confirmed: bool
+    schema_version: str = TOMBSTONE_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        _constant(self.schema_version, TOMBSTONE_CONTRACT_VERSION, "tombstone.schema_version")
+        _identifier(self.tombstone_id, "tombstone.tombstone_id")
+        _digest(self.removed_content_sha256, "tombstone.removed_content_sha256")
+        _timestamp(self.removed_at, "tombstone.removed_at")
+        _identifier(self.reason_code, "tombstone.reason_code")
+        _digest(self.policy_digest, "tombstone.policy_digest")
+        _digest(
+            self.complete_reference_set_digest,
+            "tombstone.complete_reference_set_digest",
+        )
+        _typed_tuple(
+            self.references,
+            DeletedReference,
+            "tombstone.references",
+            nonempty=True,
+            maximum=MAX_REFERENCES,
+        )
+        actual = canonical_sha256([item.to_dict() for item in self.references])
+        if actual != self.complete_reference_set_digest:
+            raise SourceContractError(
+                "REFERENCE_SET_DIGEST",
+                "tombstone.complete_reference_set_digest",
+                "does not match the canonical ordered reference set",
+            )
+        if self.byte_removal_confirmed is not True:
+            raise SourceContractError(
+                "REMOVAL_UNCONFIRMED",
+                "tombstone.byte_removal_confirmed",
+                "a sealed tombstone requires confirmed byte removal",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "tombstone_id": self.tombstone_id,
+            "removed_content_sha256": self.removed_content_sha256,
+            "removed_at": self.removed_at,
+            "reason_code": self.reason_code,
+            "policy_digest": self.policy_digest,
+            "complete_reference_set_digest": self.complete_reference_set_digest,
+            "references": [item.to_dict() for item in self.references],
+            "byte_removal_confirmed": self.byte_removal_confirmed,
+        }
+
+
+def parse_adapter_descriptor(value: Any) -> AdapterDescriptor:
+    """Parse the strict public adapter descriptor shape."""
+
+    data = _object(value, "adapter")
+    _exact(
+        data,
+        {
+            "schema_version",
+            "adapter_id",
+            "adapter_version",
+            "source_class",
+            "data_formats",
+            "capabilities",
+        },
+        "adapter",
+    )
+    return AdapterDescriptor(
+        schema_version=data["schema_version"],
+        adapter_id=data["adapter_id"],
+        adapter_version=data["adapter_version"],
+        source_class=data["source_class"],
+        data_formats=tuple(_array(data["data_formats"], "adapter.data_formats")),
+        capabilities=tuple(_array(data["capabilities"], "adapter.capabilities")),
+    )
+
+
+def evaluate_obligations(
+    *,
+    rights: RightsEvidence,
+    lifecycle: str,
+    intended_use: str,
+    attached_artifact_digests: tuple[str, ...],
+) -> tuple[LicenseObligation, ...]:
+    """Return applicable obligations or fail closed when their evidence is incomplete."""
+
+    _choice(lifecycle, OBLIGATION_LIFECYCLES, "lifecycle")
+    _text(intended_use, "intended_use", maximum=200)
+    _digests(attached_artifact_digests, "attached_artifact_digests", maximum=128)
+    if rights.status not in {"approved", "conditional"}:
+        raise SourceContractError(
+            "RIGHTS_NOT_SELECTABLE",
+            "rights.status",
+            "unclear or prohibited rights require escalation and cannot advance",
+        )
+    if intended_use not in rights.allowed_uses:
+        raise SourceContractError(
+            "USE_NOT_ALLOWED",
+            "intended_use",
+            "the intended use is not covered by the rights evidence",
+        )
+    attached = set(attached_artifact_digests)
+    applicable: list[LicenseObligation] = []
+    for obligation in rights.obligations:
+        if lifecycle not in obligation.applies_at:
+            continue
+        if intended_use in obligation.prohibited_uses:
+            raise SourceContractError(
+                "USE_PROHIBITED",
+                f"obligation.{obligation.obligation_id}",
+                "the intended use is explicitly prohibited",
+            )
+        if obligation.permitted_uses and intended_use not in obligation.permitted_uses:
+            if obligation.escalation_when_ambiguous:
+                raise SourceContractError(
+                    "RIGHTS_ESCALATION_REQUIRED",
+                    f"obligation.{obligation.obligation_id}",
+                    "obligation applicability is ambiguous for this intended use",
+                )
+            continue
+        missing = sorted(set(obligation.required_artifact_digests) - attached)
+        if missing:
+            raise SourceContractError(
+                "LICENSE_ARTIFACT_MISSING",
+                f"obligation.{obligation.obligation_id}.required_artifact_digests",
+                f"missing required attached artifacts: {missing}",
+            )
+        applicable.append(obligation)
+    return tuple(applicable)
+
+
+def _object(value: Any, path: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise SourceContractError("TYPE", path, "must be an object")
+    return value
+
+
+def _array(value: Any, path: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise SourceContractError("TYPE", path, "must be an array")
+    return value
+
+
+def _exact(data: dict[str, Any], expected: set[str], path: str) -> None:
+    actual = set(data)
+    if actual != expected:
+        raise SourceContractError(
+            "FIELDS",
+            path,
+            f"must contain exactly {sorted(expected)}; missing={sorted(expected - actual)}, "
+            f"extra={sorted(actual - expected)}",
+        )
+
+
+def _constant(value: Any, expected: str, path: str) -> None:
+    if value != expected:
+        raise SourceContractError("VERSION", path, f"must equal {expected!r}")
+
+
+def _text(value: Any, path: str, *, maximum: int = MAX_TEXT) -> str:
+    if not isinstance(value, str) or not value or len(value) > maximum:
+        raise SourceContractError(
+            "TEXT",
+            path,
+            f"must be a non-empty string no longer than {maximum} characters",
+        )
+    for index, char in enumerate(value):
+        if 0xD800 <= ord(char) <= 0xDFFF:
+            raise SourceContractError(
+                "UNICODE",
+                path,
+                f"contains an unpaired surrogate at character {index}",
+            )
+    return value
+
+
+def _texts(
+    values: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+    item_maximum: int,
+) -> None:
+    if not isinstance(values, tuple):
+        raise SourceContractError("TYPE", path, "must be an immutable tuple")
+    if nonempty and not values:
+        raise SourceContractError("EMPTY", path, "must not be empty")
+    if len(values) > maximum:
+        raise SourceContractError("LIMIT", path, f"must contain at most {maximum} values")
+    for index, value in enumerate(values):
+        _text(value, f"{path}[{index}]", maximum=item_maximum)
+    if len(set(values)) != len(values):
+        raise SourceContractError("DUPLICATE", path, "values must be unique")
+
+
+def _identifier(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=128)
+    if not _IDENTIFIER.fullmatch(text):
+        raise SourceContractError(
+            "IDENTIFIER",
+            path,
+            "must be a lowercase dotted/dashed/underscored identifier",
+        )
+    return text
+
+
+def _semver(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=64)
+    if not _SEMVER.fullmatch(text):
+        raise SourceContractError("SEMVER", path, "must be a positive-major semantic version")
+    return text
+
+
+def _commit(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=64)
+    if not re.fullmatch(r"[0-9a-f]{40,64}", text):
+        raise SourceContractError("COMMIT", path, "must be a lowercase full commit hash")
+    return text
+
+
+def _dotted_name(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=256)
+    if not re.fullmatch(r"[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)+", text):
+        raise SourceContractError("DOTTED_NAME", path, "must be a dotted public Python name")
+    return text
+
+
+def _digest(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=64)
+    if not _SHA256.fullmatch(text):
+        raise SourceContractError("SHA256", path, "must be a lowercase 64-character SHA-256")
+    return text
+
+
+def _digests(
+    values: Any,
+    path: str,
+    *,
+    nonempty: bool = False,
+    maximum: int,
+) -> None:
+    if not isinstance(values, tuple):
+        raise SourceContractError("TYPE", path, "must be an immutable tuple")
+    if nonempty and not values:
+        raise SourceContractError("EMPTY", path, "must not be empty")
+    if len(values) > maximum:
+        raise SourceContractError("LIMIT", path, f"must contain at most {maximum} values")
+    for index, value in enumerate(values):
+        _digest(value, f"{path}[{index}]")
+    if len(set(values)) != len(values):
+        raise SourceContractError("DUPLICATE", path, "digests must be unique")
+
+
+def _choice(value: Any, allowed: set[str] | frozenset[str], path: str) -> str:
+    text = _text(value, path, maximum=128)
+    if text not in allowed:
+        raise SourceContractError("ENUM", path, f"must be one of {sorted(allowed)}")
+    return text
+
+
+def _choices(
+    values: Any,
+    allowed: set[str] | frozenset[str],
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+) -> None:
+    if not isinstance(values, tuple):
+        raise SourceContractError("TYPE", path, "must be an immutable tuple")
+    if nonempty and not values:
+        raise SourceContractError("EMPTY", path, "must not be empty")
+    if len(values) > maximum:
+        raise SourceContractError("LIMIT", path, f"must contain at most {maximum} values")
+    for index, value in enumerate(values):
+        _choice(value, allowed, f"{path}[{index}]")
+    if len(set(values)) != len(values):
+        raise SourceContractError("DUPLICATE", path, "values must be unique")
+
+
+def _typed_tuple(
+    values: Any,
+    expected_type: type[Any],
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+) -> None:
+    if not isinstance(values, tuple):
+        raise SourceContractError("TYPE", path, "must be an immutable tuple")
+    if nonempty and not values:
+        raise SourceContractError("EMPTY", path, "must not be empty")
+    if len(values) > maximum:
+        raise SourceContractError("LIMIT", path, f"must contain at most {maximum} values")
+    for index, value in enumerate(values):
+        if not isinstance(value, expected_type):
+            raise SourceContractError(
+                "TYPE",
+                f"{path}[{index}]",
+                f"must be a {expected_type.__name__}",
+            )
+
+
+def _integer(value: Any, path: str, *, minimum: int, maximum: int) -> int:
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise SourceContractError(
+            "INTEGER",
+            path,
+            f"must be an integer in [{minimum}, {maximum}]",
+        )
+    if abs(value) > MAX_SAFE_INTEGER:
+        raise SourceContractError(
+            "SAFE_INTEGER",
+            path,
+            "integer exceeds the exact Python/JavaScript JSON domain",
+        )
+    return value
+
+
+def _timestamp(value: Any, path: str) -> datetime:
+    text = _text(value, path, maximum=32)
+    if not re.fullmatch(
+        r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,9})?Z",
+        text,
+    ):
+        raise SourceContractError("TIMESTAMP", path, "must be a canonical RFC 3339 UTC timestamp")
+    try:
+        parsed = datetime.fromisoformat(text[:-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 _media_type(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=255)
+    if not _MEDIA_TYPE.fullmatch(text):
+        raise SourceContractError("MEDIA_TYPE", path, "must be a lowercase type/subtype")
+    return text
+
+
+def _https_uri(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=2_048)
+    parsed = urlsplit(text)
+    if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
+        raise SourceContractError(
+            "HTTPS_URI",
+            path,
+            "must be an HTTPS URI without user information",
+        )
+    if parsed.fragment:
+        raise SourceContractError("HTTPS_URI", path, "URI fragments are forbidden")
+    return text
+
+
+def _acquisition_uri(value: Any, path: str, *, source_class: str) -> str:
+    if source_class in {"user_file", "stream"}:
+        text = _text(value, path, maximum=2_048)
+        if not re.fullmatch(r"urn:sha256:[0-9a-f]{64}", text):
+            raise SourceContractError(
+                "CONTENT_URN",
+                path,
+                "local-file and stream receipts must expose only an exact content SHA-256 URN",
+            )
+        return text
+    return _https_uri(value, path)
+
+
+def _safe_storage_name(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=255)
+    if "/" in text or "\\" in text or text in {".", ".."} or text.startswith("."):
+        raise SourceContractError(
+            "STORAGE_NAME",
+            path,
+            "must be one non-hidden relative filename",
+        )
+    return text
+
+
+def _reader_pin(value: Any, path: str) -> None:
+    """Admit a Reader pin as an exact three-key object, never half-stated.
+
+    The three fields are all present or all absent as a unit, and the unit's absence is
+    spelled by the whole pin being ``None``.  A pin that names a decoder without pinning
+    its settings, or settings without a decoder, could not be replayed from its own
+    record -- the same rule ``RecipeSource._validate_reader_pin`` applies on the recipe
+    side and ``AcquisitionReceipt`` applies on the evidence side.
+
+    Identity is screened with this module's own rules rather than the readers package's,
+    because the value that has to survive the round trip is the one the receipt will
+    record, and the receipt screens ``family_id`` with ``_identifier``.  A pin that could
+    be requested but never recorded would fail at the far end of the chain instead of
+    here.
+
+    ``decode_options`` takes exactly the screen ``request.query`` takes, so an options
+    blob cannot smuggle a non-serialisable or cross-runtime-unsafe value into the request
+    digest.  That screen's 16 KiB ceiling is tighter than the 256 KiB the recipe applies
+    when sealing the same options; no shipped family comes near either, and the request
+    side is the tighter of the two on purpose because a request crosses a coordinator
+    boundary.
+    """
+
+    if not isinstance(value, Mapping):
+        raise SourceContractError("READER_PIN", path, "must be an object")
+    if set(value) != READER_PIN_KEYS:
+        raise SourceContractError(
+            "READER_PIN",
+            path,
+            "must carry exactly " + ", ".join(sorted(READER_PIN_KEYS)),
+        )
+    if any(value[key] is None for key in READER_PIN_KEYS):
+        raise SourceContractError(
+            "READER_PIN",
+            path,
+            "family_id, family_version, and decode_options are all present or all absent",
+        )
+    _identifier(value["family_id"], f"{path}.family_id")
+    _semver(value["family_version"], f"{path}.family_version")
+    _query(value["decode_options"], f"{path}.decode_options")
+
+
+# The decode budgets a request may carry, named exactly as ``ReaderBudgets`` names them so the
+# request cannot invent a budget the Reader contract does not have.  Kept as a literal here
+# rather than imported from ``readers`` for the reason the pin keys are: this module is below
+# that one and importing upward would close a cycle.  ``tests/h3/test_adapters.py`` holds the
+# two spellings to agreement.
+RESOURCE_CAP_KEYS: frozenset[str] = frozenset(
+    {"max_declared_cells", "max_container_members", "max_nesting_depth"}
+)
+
+
+def _resource_caps(value: Any, path: str) -> None:
+    """Admit the recipe's decode budgets as an exact, closed, positive-integer object.
+
+    Every key is required.  A partially stated cap object would let a recipe believe it had
+    narrowed a budget it never named, and "a silently ignored cap is a budget a recipe believes
+    it set" is the sentence ``ReaderBudgets.narrowed_by`` exists for.  The recipe layer already
+    refuses a cap that widens a ceiling; this layer refuses one that is not a cap at all.
+    """
+
+    if not isinstance(value, Mapping):
+        raise SourceContractError("DECODE_CAPS", path, "must be an object")
+    if set(value) != RESOURCE_CAP_KEYS:
+        raise SourceContractError(
+            "DECODE_CAPS",
+            path,
+            "must carry exactly " + ", ".join(sorted(RESOURCE_CAP_KEYS)),
+        )
+    for key in sorted(RESOURCE_CAP_KEYS):
+        item = value[key]
+        if type(item) is not int or item < 1:
+            raise SourceContractError(
+                "DECODE_CAPS",
+                f"{path}.{key}",
+                "must be a positive whole number",
+            )
+    if value["max_nesting_depth"] != 1:
+        raise SourceContractError(
+            "DECODE_CAPS",
+            f"{path}.max_nesting_depth",
+            "must be exactly 1: nesting depth is a security invariant, not a budget",
+        )
+
+
+def _decode_flags(value: Any, path: str, *, family_id: str | None) -> None:
+    """Admit the closed set of facts a decode reported about itself.
+
+    Refused rather than normalised.  ``ReaderResult`` already sorts and de-duplicates its
+    flags at the producing end, so a receipt meeting an unsorted tuple met something other
+    than a Reader result, and silently rewriting evidence on its way into a digest is how
+    two different decodes come to share one receipt.
+    """
+
+    if not isinstance(value, tuple):
+        raise SourceContractError("DECODE_FLAGS", path, "must be an immutable tuple")
+    unknown = sorted(str(flag) for flag in value if flag not in DECODE_FLAGS)
+    if unknown:
+        raise SourceContractError(
+            "DECODE_FLAGS",
+            path,
+            f"names no such decode flag: {', '.join(unknown)}",
+        )
+    if tuple(sorted(set(value))) != value:
+        raise SourceContractError("DECODE_FLAGS", path, "must be sorted and free of repeats")
+    if value and family_id is None:
+        raise SourceContractError(
+            "DECODE_FLAGS",
+            path,
+            "a flag describes a decode, so a flag without a Reader family is incoherent",
+        )
+
+
+def _query(value: Any, path: str) -> None:
+    if not isinstance(value, Mapping):
+        raise SourceContractError("TYPE", path, "must be an object")
+    _safe_json_numbers(value, path)
+    try:
+        encoded = canonical_json_bytes(dict(value))
+    except (TypeError, ValueError) as exc:
+        raise SourceContractError("QUERY_JSON", path, str(exc)) from None
+    if len(encoded) > MAX_QUERY_BYTES:
+        raise SourceContractError(
+            "QUERY_LIMIT",
+            path,
+            f"canonical query exceeds {MAX_QUERY_BYTES} bytes",
+        )
+
+
+def _safe_json_numbers(value: Any, path: str) -> None:
+    if type(value) is int:
+        if abs(value) > MAX_SAFE_INTEGER:
+            raise SourceContractError(
+                "SAFE_INTEGER",
+                path,
+                "integer exceeds the exact Python/JavaScript JSON domain",
+            )
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise SourceContractError("QUERY_KEY", path, "query keys must be strings")
+            _text(key, f"{path}.<key>", maximum=128)
+            _safe_json_numbers(item, f"{path}.{key}")
+        return
+    if isinstance(value, (list, tuple)):
+        for index, item in enumerate(value):
+            _safe_json_numbers(item, f"{path}[{index}]")
+        return
+    if value is None or type(value) is bool or isinstance(value, str):
+        if isinstance(value, str):
+            _text(value, path, maximum=MAX_TEXT)
+        return
+    raise SourceContractError(
+        "QUERY_VALUE",
+        path,
+        f"unsupported query value type {type(value).__name__}",
+    )