mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/contracts.py

@@ -0,0 +1,825 @@
+"""Versioned catalog facts about one public source.
+
+A ``CatalogEntry`` names one public source and carries the facts an agent needs to choose it:
+coverage and cadence (through ``SourceObservation``), payload formats, access shape, rights
+evidence, published column and vocabulary names, and the quirks a reader will trip over. Its
+identity reads ``faostat_qcl@v3`` -- an entry id plus a version that is chained to its
+predecessor's canonical **facts** digest, so the version cannot drift from the evidence and the
+chain reads the same before and after the catalog is sealed.
+
+Three properties of this module are load-bearing and must not be relaxed.
+
+**No float, anywhere.** ``canonical_json_bytes`` refuses every non-integer JSON number, and
+``_CanonicalContract.digest`` routes through it. Embedding vectors are therefore integer-quantized
+and referenced by digest through ``LayerVectorReference`` rather than inlined; that also keeps an
+entry far below the canonical member cap.
+
+**No tenant data, by construction.** There is deliberately no field able to hold a dataset, a
+recipe, a Reader, a row sample, or a profile drawn from a tenant's private source. Adding one
+would break the tenancy rule at the type level. ``declared_columns`` and ``declared_vocabulary``
+hold *published names only* -- the headers a source documents and the item, category, or unit
+terms it publishes -- never values read out of anyone's data. Both are bounded, and the bound is
+part of the defence: a name list capped at 256 and 512 entries of 128 characters cannot smuggle a
+dataset. The ``profiles`` embedding *layer* describes the public source's shape and is sealed as
+an integer vector reference, never as data.
+
+**No public citation, no entry.** An entry cannot be constructed without at least one
+``EvidenceReference``, whose ``uri`` must already be HTTPS. A fact nobody can cite is not a
+catalog fact.
+
+Rights are never adjudicated here. ``sources.rights_rule.rights_disposition`` is the one authority
+that decides what a rights status means.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.sources.contracts import (
+    DATA_FORMATS,
+    MAX_EVIDENCE,
+    MAX_SAFE_INTEGER,
+    EvidenceReference,
+    LicenseObligation,
+    RightsEvidence,
+    SourceContractError,
+    SourceObservation,
+    _CanonicalContract,
+)
+
+CATALOG_ENTRY_CONTRACT_VERSION = "harness-source-catalog-entry.v1"
+CATALOG_INDEX_CONTRACT_VERSION = "harness-source-catalog-index.v1"
+
+# The four retrieval layers, in order. Retrieval finds; facts gate.
+EMBEDDING_LAYERS = ("description", "metadata", "columns", "profiles")
+
+# Every access kind is an open-access shape by construction. There is deliberately no
+# authenticated member: harvesters cover open endpoints only, and a 401/403 is a typed refusal
+# naming the parked authenticated-adapter item rather than a credential prompt.
+ACCESS_KINDS = frozenset({"bulk_download", "open_api", "open_catalog"})
+
+# One sealed quantization scheme. A changed scale silently changes retrieval, so the scheme is
+# named in the entry and verified when a sealed catalog is loaded.
+QUANTIZATIONS = frozenset({"int32_fixed_point_10000"})
+
+MAX_QUIRKS = 32
+MAX_QUIRK_DETAIL = 500
+MAX_SPATIAL_SCOPE = 64
+MAX_ENTRY_VERSION = 10_000
+MAX_DECLARED_COLUMNS = 256
+MAX_DECLARED_VOCABULARY = 512
+MAX_DECLARED_NAME = 128
+MAX_DESCRIPTION = 4_000
+MAX_DIMENSIONS = 4_096
+
+_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}$")
+
+
+@dataclass(frozen=True)
+class SourceQuirk(_CanonicalContract):
+    """One published-data trap a reader of this source will hit.
+
+    The worked examples are real: FAOSTAT publishes code columns with a leading apostrophe (an
+    Excel text-guard artifact) and ships its CSV with a UTF-8 byte-order mark. Both silently
+    corrupt a naive read, and both are facts about the public source rather than about anyone's
+    data.
+    """
+
+    code: str
+    detail: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.code, "quirk.code")
+        _text(self.detail, "quirk.detail", maximum=MAX_QUIRK_DETAIL)
+
+    def to_dict(self) -> dict[str, str]:
+        return {"code": self.code, "detail": self.detail}
+
+
+@dataclass(frozen=True)
+class LayerVectorReference(_CanonicalContract):
+    """A sealed integer embedding vector, referenced by digest and never inlined.
+
+    Carrying the vector itself would put thousands of numbers inside a digested contract. Instead
+    the entry names the layer, the backend that produced the vector, the quantization scheme, the
+    dimension count, and the SHA-256 of the sealed bytes -- the same shape ``SnapshotReference``
+    already uses for sealed payloads.
+
+    ``entry_facts_digest`` is what binds the vector to the facts it was computed from. Without it a
+    vector is just four self-consistent numbers: a sealed catalog assembled from entries carrying
+    some *other* entry's vectors passes every integrity check -- four layers present, one backend
+    identity, files present and digest-matching -- and then ranks the wrong source on the wrong
+    text, with no error at any point. That is the one failure mode of this module that is silent,
+    so the binding is a field rather than a convention. Checking it costs a digest comparison and
+    computes no embedding, which is what keeps it legal on the query path.
+    """
+
+    layer: str
+    backend_id: str
+    backend_version: str
+    dimensions: int
+    quantization: str
+    vector_sha256: str
+    entry_facts_digest: str
+
+    def __post_init__(self) -> None:
+        _choice(self.layer, frozenset(EMBEDDING_LAYERS), "vector.layer")
+        _identifier(self.backend_id, "vector.backend_id")
+        _semver(self.backend_version, "vector.backend_version")
+        _integer(self.dimensions, "vector.dimensions", minimum=1, maximum=MAX_DIMENSIONS)
+        _choice(self.quantization, QUANTIZATIONS, "vector.quantization")
+        _digest(self.vector_sha256, "vector.vector_sha256")
+        _digest(self.entry_facts_digest, "vector.entry_facts_digest")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "layer": self.layer,
+            "backend_id": self.backend_id,
+            "backend_version": self.backend_version,
+            "dimensions": self.dimensions,
+            "quantization": self.quantization,
+            "vector_sha256": self.vector_sha256,
+            "entry_facts_digest": self.entry_facts_digest,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogEntry(_CanonicalContract):
+    """One versioned public source, described entirely by citable facts."""
+
+    entry_id: str
+    entry_version: int
+    publisher: str
+    title: str
+    description: str
+    spatial_scope: tuple[str, ...]
+    data_formats: tuple[str, ...]
+    access_kind: str
+    authentication_required: bool
+    observation: SourceObservation
+    rights: RightsEvidence
+    quirks: tuple[SourceQuirk, ...] = ()
+    declared_columns: tuple[str, ...] = ()
+    declared_vocabulary: tuple[str, ...] = ()
+    declared_row_count: int | None = None
+    evidence: tuple[EvidenceReference, ...] = ()
+    vectors: tuple[LayerVectorReference, ...] = ()
+    previous_digest: str | None = None
+    schema_version: str = CATALOG_ENTRY_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CATALOG_ENTRY_CONTRACT_VERSION:
+            raise SourceContractError(
+                "VERSION",
+                "catalog_entry.schema_version",
+                f"must equal {CATALOG_ENTRY_CONTRACT_VERSION!r}",
+            )
+        _identifier(self.entry_id, "catalog_entry.entry_id")
+        if type(self.entry_version) is not int or not 1 <= self.entry_version <= MAX_ENTRY_VERSION:
+            raise SourceContractError(
+                "CATALOG_VERSION",
+                "catalog_entry.entry_version",
+                f"must be an integer in [1, {MAX_ENTRY_VERSION}]",
+            )
+        _text(self.publisher, "catalog_entry.publisher", maximum=200)
+        _text(self.title, "catalog_entry.title", maximum=200)
+        _text(self.description, "catalog_entry.description", maximum=MAX_DESCRIPTION)
+        _texts(
+            self.spatial_scope,
+            "catalog_entry.spatial_scope",
+            nonempty=True,
+            maximum=MAX_SPATIAL_SCOPE,
+            item_maximum=MAX_DECLARED_NAME,
+        )
+        _choices(
+            self.data_formats,
+            DATA_FORMATS,
+            "catalog_entry.data_formats",
+            nonempty=True,
+            maximum=len(DATA_FORMATS),
+        )
+        _choice(self.access_kind, ACCESS_KINDS, "catalog_entry.access_kind")
+        _boolean(self.authentication_required, "catalog_entry.authentication_required")
+        if not isinstance(self.observation, SourceObservation):
+            raise SourceContractError(
+                "TYPE",
+                "catalog_entry.observation",
+                "must be a SourceObservation",
+            )
+        if not isinstance(self.rights, RightsEvidence):
+            raise SourceContractError(
+                "TYPE",
+                "catalog_entry.rights",
+                "must be a RightsEvidence",
+            )
+        if self.observation.source_id != self.entry_id:
+            raise SourceContractError(
+                "CATALOG_SOURCE_BINDING",
+                "catalog_entry.observation",
+                "the observation and the entry must describe the same source",
+            )
+        _typed_tuple(
+            self.quirks,
+            SourceQuirk,
+            "catalog_entry.quirks",
+            maximum=MAX_QUIRKS,
+        )
+        if len({item.code for item in self.quirks}) != len(self.quirks):
+            raise SourceContractError(
+                "DUPLICATE",
+                "catalog_entry.quirks",
+                "quirk codes must be unique",
+            )
+        _texts(
+            self.declared_columns,
+            "catalog_entry.declared_columns",
+            nonempty=False,
+            maximum=MAX_DECLARED_COLUMNS,
+            item_maximum=MAX_DECLARED_NAME,
+        )
+        _texts(
+            self.declared_vocabulary,
+            "catalog_entry.declared_vocabulary",
+            nonempty=False,
+            maximum=MAX_DECLARED_VOCABULARY,
+            item_maximum=MAX_DECLARED_NAME,
+        )
+        if self.declared_row_count is not None:
+            _integer(
+                self.declared_row_count,
+                "catalog_entry.declared_row_count",
+                minimum=0,
+                maximum=MAX_SAFE_INTEGER,
+            )
+        _typed_tuple(
+            self.evidence,
+            EvidenceReference,
+            "catalog_entry.evidence",
+            maximum=MAX_EVIDENCE,
+        )
+        if not self.evidence:
+            raise SourceContractError(
+                "CATALOG_EVIDENCE",
+                "catalog_entry.evidence",
+                "a catalog entry requires at least one public citation",
+            )
+        _typed_tuple(
+            self.vectors,
+            LayerVectorReference,
+            "catalog_entry.vectors",
+            maximum=len(EMBEDDING_LAYERS),
+        )
+        if self.vectors:
+            layers = tuple(item.layer for item in self.vectors)
+            if sorted(layers) != sorted(EMBEDDING_LAYERS):
+                raise SourceContractError(
+                    "CATALOG_VECTOR_LAYERS",
+                    "catalog_entry.vectors",
+                    f"must carry exactly one vector per layer {list(EMBEDDING_LAYERS)}, "
+                    "or none at all",
+                )
+        if self.previous_digest is not None:
+            _digest(self.previous_digest, "catalog_entry.previous_digest")
+        if self.entry_version == 1 and self.previous_digest is not None:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                "catalog_entry.previous_digest",
+                "a first version has no predecessor to link to",
+            )
+        if self.entry_version > 1 and self.previous_digest is None:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                "catalog_entry.previous_digest",
+                "a successor version must link to its predecessor's digest",
+            )
+
+    @property
+    def coordinate(self) -> str:
+        """Return the entry identity, for example ``faostat_qcl@v3``."""
+
+        return f"{self.entry_id}@v{self.entry_version}"
+
+    @property
+    def facts_digest(self) -> str:
+        """The digest of everything this entry *claims*, with its sealed vectors excluded.
+
+        The version chain runs on this rather than on ``digest``, and it has to. Sealing replaces
+        an entry's ``vectors``, which changes ``digest``; a chain linked on ``digest`` would
+        therefore verify before sealing and break after it, so the entries a sealed catalog holds
+        and the authored entry files they came from would be two permanently incompatible spellings
+        of one history. Excluding the vectors makes the link stable across sealing while leaving
+        every fact -- including ``previous_digest`` itself -- inside the digest, so a tampered
+        history still cannot re-link.
+
+        This is also the value a ``LayerVectorReference`` carries, which is what binds a sealed
+        vector to the facts it was computed from.
+        """
+
+        payload = self.to_dict()
+        del payload["vectors"]
+        return canonical_sha256(payload)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "entry_id": self.entry_id,
+            "entry_version": self.entry_version,
+            "publisher": self.publisher,
+            "title": self.title,
+            "description": self.description,
+            "spatial_scope": list(self.spatial_scope),
+            "data_formats": list(self.data_formats),
+            "access_kind": self.access_kind,
+            "authentication_required": self.authentication_required,
+            "observation": self.observation.to_dict(),
+            "rights": self.rights.to_dict(),
+            "quirks": [item.to_dict() for item in self.quirks],
+            "declared_columns": list(self.declared_columns),
+            "declared_vocabulary": list(self.declared_vocabulary),
+            "declared_row_count": self.declared_row_count,
+            "evidence": [item.to_dict() for item in self.evidence],
+            "vectors": [item.to_dict() for item in self.vectors],
+            "previous_digest": self.previous_digest,
+        }
+
+
+_MANAGED_VERSION_FIELDS = ("entry_version", "previous_digest", "vectors")
+
+
+def next_entry_version(previous: CatalogEntry, **changes: object) -> CatalogEntry:
+    """Mint the successor of ``previous``, linked to its predecessor's facts digest.
+
+    The caller supplies the changed facts and nothing else. ``entry_version``,
+    ``previous_digest`` and ``vectors`` are computed here and refused as arguments -- that refusal
+    is precisely what stops a version from drifting away from the evidence it claims to describe.
+
+    Two of those three deserve their reason stated.
+
+    ``previous_digest`` is ``previous.facts_digest`` and not ``previous.digest``: sealing rewrites
+    an entry's ``vectors``, so a link taken over the whole entry would depend on whether the author
+    happened to hold the sealed or the unsealed spelling of the predecessor, and only one of the
+    two would ever verify. Linking on the facts makes the answer the same either way.
+
+    ``vectors`` is cleared unconditionally. Carrying a predecessor's sealed vectors onto a
+    successor is the one way to manufacture an entry that ranks on facts it no longer states, and
+    it is exactly what a bare ``dataclasses.replace`` would do. A successor is re-sealed, never
+    inherited.
+    """
+
+    if not isinstance(previous, CatalogEntry):
+        raise SourceContractError("TYPE", "previous", "must be a CatalogEntry")
+    managed = sorted(name for name in _MANAGED_VERSION_FIELDS if name in changes)
+    if managed:
+        raise SourceContractError(
+            "CATALOG_VERSION_MANAGED",
+            f"changes.{managed[0]}",
+            f"{sorted(_MANAGED_VERSION_FIELDS)} are derived from the predecessor and cannot be "
+            "supplied",
+        )
+    return replace(
+        previous,
+        entry_version=previous.entry_version + 1,
+        previous_digest=previous.facts_digest,
+        vectors=(),
+        **changes,
+    )
+
+
+def verify_version_chain(chain: tuple[CatalogEntry, ...]) -> str:
+    """Verify a whole entry history and return its head coordinate, e.g. ``faostat_qcl@v3``.
+
+    A chain verifies when every member names the same source, the versions run ``1..n`` with no
+    gap, the first member claims no predecessor, and every later member's ``previous_digest`` is
+    the exact ``facts_digest`` of the member before it. Changing any fact of any member breaks
+    every link after it, so a tampered history cannot re-link itself.
+
+    The link is over ``facts_digest`` rather than ``digest`` so that one history verifies in both
+    of its spellings: the authored entries an author holds and the sealed entries a catalog holds
+    differ only in their vectors, and a chain that verified in one and not the other would be a
+    chain nobody could actually check.
+    """
+
+    if not isinstance(chain, tuple):
+        raise SourceContractError("TYPE", "chain", "must be an immutable tuple")
+    if not chain:
+        raise SourceContractError(
+            "CATALOG_VERSION_CHAIN",
+            "chain",
+            "a version chain must contain at least one entry",
+        )
+    for index, entry in enumerate(chain):
+        if not isinstance(entry, CatalogEntry):
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                f"chain[{index}]",
+                "must be a CatalogEntry",
+            )
+        if entry.entry_id != chain[0].entry_id:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                f"chain[{index}].entry_id",
+                f"every member must describe {chain[0].entry_id!r}, found {entry.entry_id!r}",
+            )
+        if entry.entry_version != index + 1:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                f"chain[{index}].entry_version",
+                f"versions must run 1..n in order with no gap; expected {index + 1}, "
+                f"found {entry.entry_version}",
+            )
+        if index == 0:
+            if entry.previous_digest is not None:
+                raise SourceContractError(
+                    "CATALOG_VERSION_CHAIN",
+                    "chain[0].previous_digest",
+                    "the first version has no predecessor",
+                )
+            continue
+        expected = chain[index - 1].facts_digest
+        if entry.previous_digest != expected:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                f"chain[{index}].previous_digest",
+                "does not match the canonical facts digest of the preceding version",
+            )
+    return chain[-1].coordinate
+
+
+def catalog_entry_from_dict(data: Mapping[str, Any]) -> CatalogEntry:
+    """Rebuild an entry from its exact ``to_dict()`` shape, refusing anything else.
+
+    Reconstruction is strict on both sides: a missing key and an unknown key are equally a typed
+    failure. A parser that silently drops what it does not recognise turns a tampered artifact
+    into a valid-looking one, which is the failure mode the digest chain exists to prevent.
+    """
+
+    payload = _mapping(data, "catalog_entry")
+    _exact(
+        payload,
+        {
+            "schema_version",
+            "entry_id",
+            "entry_version",
+            "publisher",
+            "title",
+            "description",
+            "spatial_scope",
+            "data_formats",
+            "access_kind",
+            "authentication_required",
+            "observation",
+            "rights",
+            "quirks",
+            "declared_columns",
+            "declared_vocabulary",
+            "declared_row_count",
+            "evidence",
+            "vectors",
+            "previous_digest",
+        },
+        "catalog_entry",
+    )
+    return CatalogEntry(
+        schema_version=payload["schema_version"],
+        entry_id=payload["entry_id"],
+        entry_version=payload["entry_version"],
+        publisher=payload["publisher"],
+        title=payload["title"],
+        description=payload["description"],
+        spatial_scope=tuple(_sequence(payload["spatial_scope"], "catalog_entry.spatial_scope")),
+        data_formats=tuple(_sequence(payload["data_formats"], "catalog_entry.data_formats")),
+        access_kind=payload["access_kind"],
+        authentication_required=payload["authentication_required"],
+        observation=_observation_from_dict(payload["observation"]),
+        rights=_rights_from_dict(payload["rights"]),
+        quirks=tuple(
+            _quirk_from_dict(item) for item in _sequence(payload["quirks"], "catalog_entry.quirks")
+        ),
+        declared_columns=tuple(
+            _sequence(payload["declared_columns"], "catalog_entry.declared_columns")
+        ),
+        declared_vocabulary=tuple(
+            _sequence(payload["declared_vocabulary"], "catalog_entry.declared_vocabulary")
+        ),
+        declared_row_count=payload["declared_row_count"],
+        evidence=tuple(
+            _evidence_from_dict(item, f"catalog_entry.evidence[{index}]")
+            for index, item in enumerate(_sequence(payload["evidence"], "catalog_entry.evidence"))
+        ),
+        vectors=tuple(
+            _vector_from_dict(item)
+            for item in _sequence(payload["vectors"], "catalog_entry.vectors")
+        ),
+        previous_digest=payload["previous_digest"],
+    )
+
+
+def _quirk_from_dict(data: Any) -> SourceQuirk:
+    payload = _mapping(data, "catalog_entry.quirks[]")
+    _exact(payload, {"code", "detail"}, "catalog_entry.quirks[]")
+    return SourceQuirk(code=payload["code"], detail=payload["detail"])
+
+
+def _vector_from_dict(data: Any) -> LayerVectorReference:
+    payload = _mapping(data, "catalog_entry.vectors[]")
+    _exact(
+        payload,
+        {
+            "layer",
+            "backend_id",
+            "backend_version",
+            "dimensions",
+            "quantization",
+            "vector_sha256",
+            "entry_facts_digest",
+        },
+        "catalog_entry.vectors[]",
+    )
+    return LayerVectorReference(
+        layer=payload["layer"],
+        backend_id=payload["backend_id"],
+        backend_version=payload["backend_version"],
+        dimensions=payload["dimensions"],
+        quantization=payload["quantization"],
+        vector_sha256=payload["vector_sha256"],
+        entry_facts_digest=payload["entry_facts_digest"],
+    )
+
+
+def _evidence_from_dict(data: Any, path: str) -> EvidenceReference:
+    payload = _mapping(data, path)
+    _exact(payload, {"uri", "observed_at", "content_sha256", "media_type"}, path)
+    return EvidenceReference(
+        uri=payload["uri"],
+        observed_at=payload["observed_at"],
+        content_sha256=payload["content_sha256"],
+        media_type=payload["media_type"],
+    )
+
+
+def _obligation_from_dict(data: Any) -> LicenseObligation:
+    path = "catalog_entry.rights.obligations[]"
+    payload = _mapping(data, path)
+    _exact(
+        payload,
+        {
+            "obligation_id",
+            "applies_at",
+            "permitted_uses",
+            "prohibited_uses",
+            "required_artifact_digests",
+            "escalation_when_ambiguous",
+        },
+        path,
+    )
+    return LicenseObligation(
+        obligation_id=payload["obligation_id"],
+        applies_at=tuple(_sequence(payload["applies_at"], f"{path}.applies_at")),
+        permitted_uses=tuple(_sequence(payload["permitted_uses"], f"{path}.permitted_uses")),
+        prohibited_uses=tuple(_sequence(payload["prohibited_uses"], f"{path}.prohibited_uses")),
+        required_artifact_digests=tuple(
+            _sequence(payload["required_artifact_digests"], f"{path}.required_artifact_digests")
+        ),
+        escalation_when_ambiguous=payload["escalation_when_ambiguous"],
+    )
+
+
+def rights_evidence_from_dict(data: Any, *, path: str = "catalog_entry.rights") -> RightsEvidence:
+    """Rebuild one authored rights claim from its exact ``to_dict()`` shape.
+
+    The public spelling of the parser ``catalog_entry_from_dict`` already uses for the
+    nested ``rights`` field, exported so a rights decision document can carry the same
+    shape without a second parser drifting from this one. ``path`` names the document the
+    claim actually sits in, so a refusal sends the person to the right file.
+    """
+
+    return _rights_from_dict(data, path=path)
+
+
+def _rights_from_dict(data: Any, *, path: str = "catalog_entry.rights") -> RightsEvidence:
+    payload = _mapping(data, path)
+    _exact(
+        payload,
+        {
+            "status",
+            "lawful_basis",
+            "allowed_uses",
+            "evidence",
+            "obligations",
+            "human_decision_reference",
+        },
+        path,
+    )
+    return RightsEvidence(
+        status=payload["status"],
+        lawful_basis=payload["lawful_basis"],
+        allowed_uses=tuple(_sequence(payload["allowed_uses"], f"{path}.allowed_uses")),
+        evidence=tuple(
+            _evidence_from_dict(item, f"{path}.evidence[{index}]")
+            for index, item in enumerate(_sequence(payload["evidence"], f"{path}.evidence"))
+        ),
+        obligations=tuple(
+            _obligation_from_dict(item)
+            for item in _sequence(payload["obligations"], f"{path}.obligations")
+        ),
+        human_decision_reference=payload["human_decision_reference"],
+    )
+
+
+def _observation_from_dict(data: Any) -> SourceObservation:
+    path = "catalog_entry.observation"
+    payload = _mapping(data, path)
+    _exact(
+        payload,
+        {
+            "schema_version",
+            "source_id",
+            "observed_at",
+            "event_time_field",
+            "available_at_field",
+            "historical_start",
+            "historical_end",
+            "live_status",
+            "publication_delay_seconds",
+            "update_frequency_seconds",
+            "response_status",
+            "evidence",
+        },
+        path,
+    )
+    return SourceObservation(
+        schema_version=payload["schema_version"],
+        source_id=payload["source_id"],
+        observed_at=payload["observed_at"],
+        event_time_field=payload["event_time_field"],
+        available_at_field=payload["available_at_field"],
+        historical_start=payload["historical_start"],
+        historical_end=payload["historical_end"],
+        live_status=payload["live_status"],
+        publication_delay_seconds=payload["publication_delay_seconds"],
+        update_frequency_seconds=payload["update_frequency_seconds"],
+        response_status=payload["response_status"],
+        evidence=tuple(
+            _evidence_from_dict(item, f"{path}.evidence[{index}]")
+            for index, item in enumerate(_sequence(payload["evidence"], f"{path}.evidence"))
+        ),
+    )
+
+
+def _mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise SourceContractError("TYPE", path, "must be an object")
+    for key in value:
+        if not isinstance(key, str):
+            raise SourceContractError("TYPE", path, "object keys must be strings")
+    return value
+
+
+def _sequence(value: Any, path: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise SourceContractError("TYPE", path, "must be an array")
+    return value
+
+
+def _exact(data: Mapping[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 _text(value: Any, path: str, *, maximum: int) -> 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=MAX_DECLARED_NAME)
+    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 _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 _choice(value: Any, allowed: frozenset[str], path: str) -> str:
+    text = _text(value, path, maximum=MAX_DECLARED_NAME)
+    if text not in allowed:
+        raise SourceContractError("ENUM", path, f"must be one of {sorted(allowed)}")
+    return text
+
+
+def _choices(
+    values: Any,
+    allowed: 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, *, maximum: int) -> None:
+    if not isinstance(values, tuple):
+        raise SourceContractError("TYPE", path, "must be an immutable tuple")
+    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:
+    # ``type(value) is not int`` rather than ``isinstance``: it refuses both bool and float, which
+    # is what keeps a float out of the digest before ``canonical_json_bytes`` ever sees it.
+    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 _boolean(value: Any, path: str) -> bool:
+    if type(value) is not bool:
+        raise SourceContractError("BOOLEAN", path, "must be a boolean")
+    return value