mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/entry_v2.py

@@ -0,0 +1,1182 @@
+"""Honest version-two public catalog entries.
+
+The frozen :mod:`contracts` module remains the complete v1 contract.  This module adds a
+side-by-side successor in which absence is data: every nullable semantic fact says exactly
+``known``, ``unknown``, or ``not_applicable``.  A known fact is inseparable from the exact provider
+record and canonical provider JSON path that stated it.
+
+Semantic provenance and sweep provenance deliberately have different digests.  The semantic
+facts digest drives entry versioning and vector reuse; append-only observations record when and
+from which response/page evidence those facts were seen without changing their meaning.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime
+from types import MappingProxyType
+from typing import Any
+
+from mostlyright.data_harness.canonical import (
+    MAX_CANONICAL_DEPTH,
+    CanonicalJSONError,
+    canonical_sha256,
+    parse_canonical_json,
+)
+from mostlyright.data_harness.sources.catalog.contracts import (
+    ACCESS_KINDS,
+    CATALOG_ENTRY_CONTRACT_VERSION,
+    EMBEDDING_LAYERS,
+    MAX_DECLARED_COLUMNS,
+    MAX_DECLARED_NAME,
+    MAX_DECLARED_VOCABULARY,
+    MAX_DESCRIPTION,
+    MAX_ENTRY_VERSION,
+    MAX_SPATIAL_SCOPE,
+    CatalogEntry,
+    LayerVectorReference,
+    catalog_entry_from_dict,
+)
+from mostlyright.data_harness.sources.catalog.harvest.protocol import (
+    DATAGOV_V4_HARVESTER_COORDINATE,
+)
+from mostlyright.data_harness.sources.contracts import (
+    DATA_FORMATS,
+    MAX_SAFE_INTEGER,
+    RIGHTS_STATUSES,
+    SourceContractError,
+    _CanonicalContract,
+)
+
+CATALOG_ENTRY_V2_CONTRACT_VERSION = "harness-source-catalog-entry.v2"
+
+# Keep a single entry below the existing four-MiB catalog-fact admission ceiling, and enforce it
+# before ``json.loads`` can allocate a decoded object graph. Provider-scale collections use bounded
+# shards/packs; no individual semantic record needs a wider spelling.
+MAX_CATALOG_ENTRY_BYTES = 4 * 1024 * 1024
+MAX_CATALOG_ENTRY_NESTING = MAX_CANONICAL_DEPTH
+
+
+@dataclass(frozen=True)
+class ProviderContract:
+    """Exact provider identity field and implementation coordinate; neither is inferred."""
+
+    harvester_coordinate: str
+    identifier_json_path: str
+
+
+# One immutable provider contract prevents the identity field and observation producer from
+# drifting into independently maintained maps. Adding a provider requires one explicit reviewed
+# registry entry; names, prefixes, and semantic-version proximity never imply authority.
+PROVIDER_CONTRACTS: Mapping[str, ProviderContract] = MappingProxyType(
+    {
+        "datagov_v4": ProviderContract(
+            harvester_coordinate=DATAGOV_V4_HARVESTER_COORDINATE,
+            identifier_json_path="$.identifier",
+        )
+    }
+)
+
+FACT_STATES = frozenset({"known", "unknown", "not_applicable"})
+MAX_PROVIDER_RECORD_ID = 512
+MAX_PROVIDER_PATHS = 64
+MAX_OBSERVATIONS = 10_000
+MAX_PROFILES = 256
+
+FILTERABLE_FACTS = frozenset(
+    {
+        "publisher",
+        "description",
+        "spatial_scope",
+        "data_formats",
+        "access_kind",
+        "authentication_required",
+        "declared_columns",
+        "declared_vocabulary",
+        "declared_row_count",
+        "profiles",
+    }
+)
+
+_IDENTIFIER = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_HARVESTER_COORDINATE = re.compile(
+    r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*@[1-9][0-9]*\.[0-9]+\.[0-9]+$"
+)
+# Deliberately excludes numeric array positions. Provider records may reorder arrays between
+# responses; a semantic author may cite the complete array (``[*]``), never an unstable local
+# position. Keys are the closed portable spelling used by normalized provider records.
+_PROVIDER_NAMED_SEGMENT = re.compile(r"\.[A-Za-z_][A-Za-z0-9_-]*")
+_PROVIDER_QUOTED_KEYS = frozenset({"@type"})
+_UTC_SECOND = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$")
+
+
+@dataclass(frozen=True)
+class ProviderRecordIdentity(_CanonicalContract):
+    """Stable provider record identity, directly cited from one normalized provider field."""
+
+    provider_id: str
+    provider_record_id: str
+    provider_record_sha256: str
+    identifier_json_path: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.provider_id, "provider_record.provider_id")
+        _text(
+            self.provider_record_id,
+            "provider_record.provider_record_id",
+            maximum=MAX_PROVIDER_RECORD_ID,
+        )
+        _digest(self.provider_record_sha256, "provider_record.provider_record_sha256")
+        _provider_identifier_path(
+            self.identifier_json_path,
+            "provider_record.identifier_json_path",
+        )
+        contract = PROVIDER_CONTRACTS.get(self.provider_id)
+        if contract is None or self.identifier_json_path != contract.identifier_json_path:
+            raise SourceContractError(
+                "CATALOG_PROVIDER_IDENTITY_PATH",
+                "provider_record.identifier_json_path",
+                "must equal the sole registered identity path for this provider",
+            )
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "provider_id": self.provider_id,
+            "provider_record_id": self.provider_record_id,
+            "provider_record_sha256": self.provider_record_sha256,
+            "identifier_json_path": self.identifier_json_path,
+        }
+
+
+@dataclass(frozen=True)
+class ProviderFactProvenance(_CanonicalContract):
+    """Exact provider record and JSON paths supporting one known fact."""
+
+    provider_id: str
+    provider_record_id: str
+    provider_record_sha256: str
+    json_paths: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        _identifier(self.provider_id, "fact.provenance.provider_id")
+        _text(
+            self.provider_record_id,
+            "fact.provenance.provider_record_id",
+            maximum=MAX_PROVIDER_RECORD_ID,
+        )
+        _digest(self.provider_record_sha256, "fact.provenance.provider_record_sha256")
+        if not isinstance(self.json_paths, tuple):
+            raise SourceContractError(
+                "TYPE",
+                "fact.provenance.json_paths",
+                "must be an immutable tuple",
+            )
+        if not self.json_paths or len(self.json_paths) > MAX_PROVIDER_PATHS:
+            raise SourceContractError(
+                "LIMIT",
+                "fact.provenance.json_paths",
+                f"must contain between 1 and {MAX_PROVIDER_PATHS} paths",
+            )
+        for index, path in enumerate(self.json_paths):
+            _provider_path(path, f"fact.provenance.json_paths[{index}]")
+        if tuple(sorted(set(self.json_paths))) != self.json_paths:
+            raise SourceContractError(
+                "ORDER",
+                "fact.provenance.json_paths",
+                "paths must be unique and sorted",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "provider_id": self.provider_id,
+            "provider_record_id": self.provider_record_id,
+            "provider_record_sha256": self.provider_record_sha256,
+            "json_paths": list(self.json_paths),
+        }
+
+
+@dataclass(frozen=True)
+class CatalogFact(_CanonicalContract):
+    """One explicit nullable fact.
+
+    ``None`` is not a fourth state. It is only the canonical empty slot carried by the two states
+    that have no value. Known values cannot be null and cannot exist without provenance.
+    """
+
+    state: str
+    value: object | None = None
+    provenance: ProviderFactProvenance | None = None
+
+    def __post_init__(self) -> None:
+        _choice(self.state, FACT_STATES, "fact.state")
+        if self.state == "known":
+            if self.value is None:
+                raise SourceContractError("FACT_VALUE", "fact.value", "known requires a value")
+            if not isinstance(self.provenance, ProviderFactProvenance):
+                raise SourceContractError(
+                    "FACT_PROVENANCE",
+                    "fact.provenance",
+                    "known requires exact provider provenance",
+                )
+            return
+        if self.value is not None:
+            raise SourceContractError(
+                "FACT_VALUE",
+                "fact.value",
+                f"{self.state} cannot carry a value",
+            )
+        if self.provenance is not None:
+            raise SourceContractError(
+                "FACT_PROVENANCE",
+                "fact.provenance",
+                f"{self.state} cannot carry provenance",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        value = list(self.value) if isinstance(self.value, tuple) else self.value
+        return {
+            "state": self.state,
+            "value": value,
+            "provenance": self.provenance.to_dict() if self.provenance is not None else None,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogObservation(_CanonicalContract):
+    """Append-only sweep evidence, excluded from semantic versioning and vector identity."""
+
+    harvester_coordinate: str
+    observed_at: str
+    response_evidence_sha256: str
+    page_evidence_sha256: str
+
+    def __post_init__(self) -> None:
+        coordinate = _text(
+            self.harvester_coordinate,
+            "observation.harvester_coordinate",
+            maximum=192,
+        )
+        if not _HARVESTER_COORDINATE.fullmatch(coordinate):
+            raise SourceContractError(
+                "COORDINATE",
+                "observation.harvester_coordinate",
+                "must be a provider/harvester identifier plus positive-major semantic version",
+            )
+        _utc_second(self.observed_at, "observation.observed_at")
+        _digest(self.response_evidence_sha256, "observation.response_evidence_sha256")
+        _digest(self.page_evidence_sha256, "observation.page_evidence_sha256")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "harvester_coordinate": self.harvester_coordinate,
+            "observed_at": self.observed_at,
+            "response_evidence_sha256": self.response_evidence_sha256,
+            "page_evidence_sha256": self.page_evidence_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogFactFilter(_CanonicalContract):
+    """One closed exact filter over semantic facts, with no score-shaped input channel."""
+
+    field: str
+    expected: str | bool | int
+
+    def __post_init__(self) -> None:
+        _choice(self.field, FILTERABLE_FACTS, "filter.field")
+        path = "filter.expected"
+        if self.field == "authentication_required":
+            if type(self.expected) is not bool:
+                raise SourceContractError("BOOLEAN", path, "must be a boolean for this field")
+        elif self.field == "declared_row_count":
+            if type(self.expected) is not int or not 0 <= self.expected <= MAX_SAFE_INTEGER:
+                raise SourceContractError(
+                    "INTEGER",
+                    path,
+                    f"must be an integer in [0, {MAX_SAFE_INTEGER}] for this field",
+                )
+        else:
+            _text(self.expected, path, maximum=MAX_DESCRIPTION)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"field": self.field, "expected": self.expected}
+
+
+@dataclass(frozen=True)
+class CatalogEntryV2Decision(_CanonicalContract):
+    """Score-blind retrieval/filter/admission projection for one already-safe v2 entry."""
+
+    entry_coordinate: str
+    searchable: bool
+    filters_match: bool
+    filter_failures: tuple[str, ...]
+    rights_disposition: str
+    recommendation: str
+    semantic_facts_digest: str
+    entry_digest: str
+
+    def __post_init__(self) -> None:
+        _text(self.entry_coordinate, "decision.entry_coordinate", maximum=256)
+        _boolean(self.searchable, "decision.searchable")
+        _boolean(self.filters_match, "decision.filters_match")
+        if not isinstance(self.filter_failures, tuple):
+            raise SourceContractError(
+                "TYPE",
+                "decision.filter_failures",
+                "must be an immutable tuple",
+            )
+        for index, failure in enumerate(self.filter_failures):
+            _text(failure, f"decision.filter_failures[{index}]", maximum=256)
+        _choice(
+            self.rights_disposition,
+            frozenset({"admitted", "flagged", "refused"}),
+            "decision.rights_disposition",
+        )
+        _choice(
+            self.recommendation,
+            frozenset({"use_source", "no_match"}),
+            "decision.recommendation",
+        )
+        _digest(self.semantic_facts_digest, "decision.semantic_facts_digest")
+        _digest(self.entry_digest, "decision.entry_digest")
+        if self.recommendation == "use_source" and (
+            not self.searchable or not self.filters_match or self.rights_disposition != "admitted"
+        ):
+            raise SourceContractError(
+                "CATALOG_AUTHORITY",
+                "decision.recommendation",
+                "use_source requires searchable admitted facts satisfying every filter",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "entry_coordinate": self.entry_coordinate,
+            "searchable": self.searchable,
+            "filters_match": self.filters_match,
+            "filter_failures": list(self.filter_failures),
+            "rights_disposition": self.rights_disposition,
+            "recommendation": self.recommendation,
+            "semantic_facts_digest": self.semantic_facts_digest,
+            "entry_digest": self.entry_digest,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogRetrievalRead:
+    """Durable parse disposition used by packed readers before a record can reach retrieval."""
+
+    entry: CatalogEntry | CatalogEntryV2 | None
+    schema_version: str | None
+    retrieval_disposition: str
+    searchable: bool
+    reason_code: str
+
+    def __post_init__(self) -> None:
+        if self.retrieval_disposition not in {"searchable", "skipped"}:
+            raise SourceContractError(
+                "ENUM",
+                "retrieval_read.retrieval_disposition",
+                "must be searchable or skipped",
+            )
+        if type(self.searchable) is not bool:
+            raise SourceContractError(
+                "BOOLEAN",
+                "retrieval_read.searchable",
+                "must be a boolean",
+            )
+        if (self.retrieval_disposition == "searchable") != self.searchable:
+            raise SourceContractError(
+                "CATALOG_RETRIEVAL_DISPOSITION",
+                "retrieval_read.searchable",
+                "must agree with retrieval_disposition",
+            )
+        if self.searchable != (self.entry is not None):
+            raise SourceContractError(
+                "CATALOG_RETRIEVAL_DISPOSITION",
+                "retrieval_read.entry",
+                "skipped reads carry no entry and searchable reads carry one",
+            )
+        _text(self.reason_code, "retrieval_read.reason_code", maximum=128)
+
+
+_FACT_FIELDS = (
+    "title",
+    "publisher",
+    "description",
+    "spatial_scope",
+    "data_formats",
+    "access_kind",
+    "authentication_required",
+    "rights",
+    "declared_columns",
+    "declared_vocabulary",
+    "declared_row_count",
+    "profiles",
+)
+
+
+@dataclass(frozen=True)
+class CatalogEntryV2(_CanonicalContract):
+    """One v2 public-source entry with explicit fact states and separate sweep history."""
+
+    entry_id: str
+    entry_version: int
+    provider_record: ProviderRecordIdentity
+    title: CatalogFact
+    publisher: CatalogFact
+    description: CatalogFact
+    spatial_scope: CatalogFact
+    data_formats: CatalogFact
+    access_kind: CatalogFact
+    authentication_required: CatalogFact
+    rights: CatalogFact
+    declared_columns: CatalogFact
+    declared_vocabulary: CatalogFact
+    declared_row_count: CatalogFact
+    profiles: CatalogFact
+    observations: tuple[CatalogObservation, ...]
+    vectors: tuple[LayerVectorReference, ...] = ()
+    previous_semantic_digest: str | None = None
+    schema_version: str = CATALOG_ENTRY_V2_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CATALOG_ENTRY_V2_CONTRACT_VERSION:
+            raise SourceContractError(
+                "VERSION",
+                "catalog_entry_v2.schema_version",
+                f"must equal {CATALOG_ENTRY_V2_CONTRACT_VERSION!r}",
+            )
+        _identifier(self.entry_id, "catalog_entry_v2.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_v2.entry_version",
+                f"must be an integer in [1, {MAX_ENTRY_VERSION}]",
+            )
+        if not isinstance(self.provider_record, ProviderRecordIdentity):
+            raise SourceContractError(
+                "TYPE",
+                "catalog_entry_v2.provider_record",
+                "must be a ProviderRecordIdentity",
+            )
+        for name in _FACT_FIELDS:
+            fact = getattr(self, name)
+            if not isinstance(fact, CatalogFact):
+                raise SourceContractError(
+                    "TYPE",
+                    f"catalog_entry_v2.{name}",
+                    "must be a CatalogFact",
+                )
+            self._validate_fact_provenance(name, fact)
+        if self.title.state != "known":
+            raise SourceContractError(
+                "CATALOG_IDENTITY",
+                "catalog_entry_v2.title",
+                "safe searchable identity requires a directly evidenced known title",
+            )
+        self._validate_fact_types()
+        self._validate_observations()
+        self._validate_vectors()
+        if self.previous_semantic_digest is not None:
+            _digest(
+                self.previous_semantic_digest,
+                "catalog_entry_v2.previous_semantic_digest",
+            )
+        if self.entry_version == 1 and self.previous_semantic_digest is not None:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                "catalog_entry_v2.previous_semantic_digest",
+                "a first version has no semantic predecessor",
+            )
+        if self.entry_version > 1 and self.previous_semantic_digest is None:
+            raise SourceContractError(
+                "CATALOG_VERSION_CHAIN",
+                "catalog_entry_v2.previous_semantic_digest",
+                "a semantic successor must link to its predecessor",
+            )
+
+    def _validate_fact_provenance(self, name: str, fact: CatalogFact) -> None:
+        if fact.state != "known":
+            return
+        provenance = fact.provenance
+        assert provenance is not None
+        expected = (
+            self.provider_record.provider_id,
+            self.provider_record.provider_record_id,
+            self.provider_record.provider_record_sha256,
+        )
+        actual = (
+            provenance.provider_id,
+            provenance.provider_record_id,
+            provenance.provider_record_sha256,
+        )
+        if actual != expected:
+            raise SourceContractError(
+                "CATALOG_PROVIDER_BINDING",
+                f"catalog_entry_v2.{name}.provenance",
+                "known fact provenance must name this exact provider record and digest",
+            )
+
+    def _validate_fact_types(self) -> None:
+        _known_text(self.title, "catalog_entry_v2.title", maximum=200)
+        _known_text(self.publisher, "catalog_entry_v2.publisher", maximum=200)
+        _known_text(self.description, "catalog_entry_v2.description", maximum=MAX_DESCRIPTION)
+        _known_text_tuple(
+            self.spatial_scope,
+            "catalog_entry_v2.spatial_scope",
+            maximum=MAX_SPATIAL_SCOPE,
+        )
+        _known_choices(
+            self.data_formats,
+            "catalog_entry_v2.data_formats",
+            allowed=DATA_FORMATS,
+            maximum=len(DATA_FORMATS),
+        )
+        _known_choice(
+            self.access_kind,
+            "catalog_entry_v2.access_kind",
+            allowed=ACCESS_KINDS,
+        )
+        _known_boolean(
+            self.authentication_required,
+            "catalog_entry_v2.authentication_required",
+        )
+        _known_choice(self.rights, "catalog_entry_v2.rights", allowed=RIGHTS_STATUSES)
+        _known_text_tuple(
+            self.declared_columns,
+            "catalog_entry_v2.declared_columns",
+            maximum=MAX_DECLARED_COLUMNS,
+        )
+        _known_text_tuple(
+            self.declared_vocabulary,
+            "catalog_entry_v2.declared_vocabulary",
+            maximum=MAX_DECLARED_VOCABULARY,
+        )
+        _known_integer(
+            self.declared_row_count,
+            "catalog_entry_v2.declared_row_count",
+            minimum=0,
+            maximum=MAX_SAFE_INTEGER,
+        )
+        _known_text_tuple(self.profiles, "catalog_entry_v2.profiles", maximum=MAX_PROFILES)
+
+    def _validate_observations(self) -> None:
+        if not isinstance(self.observations, tuple):
+            raise SourceContractError(
+                "TYPE",
+                "catalog_entry_v2.observations",
+                "must be an immutable tuple",
+            )
+        if not self.observations or len(self.observations) > MAX_OBSERVATIONS:
+            raise SourceContractError(
+                "LIMIT",
+                "catalog_entry_v2.observations",
+                f"must contain between 1 and {MAX_OBSERVATIONS} observations",
+            )
+        for index, item in enumerate(self.observations):
+            if not isinstance(item, CatalogObservation):
+                raise SourceContractError(
+                    "TYPE",
+                    f"catalog_entry_v2.observations[{index}]",
+                    "must be a CatalogObservation",
+                )
+            contract = PROVIDER_CONTRACTS.get(self.provider_record.provider_id)
+            if contract is None or item.harvester_coordinate != contract.harvester_coordinate:
+                raise SourceContractError(
+                    "CATALOG_PROVIDER_HARVESTER",
+                    f"catalog_entry_v2.observations[{index}].harvester_coordinate",
+                    "must be an exact registered harvester coordinate for this provider",
+                )
+        keys = tuple((item.observed_at, item.digest) for item in self.observations)
+        if tuple(sorted(set(keys))) != keys:
+            raise SourceContractError(
+                "CATALOG_OBSERVATION_HISTORY",
+                "catalog_entry_v2.observations",
+                "observations must be unique and append-ordered by timestamp and digest",
+            )
+
+    def _validate_vectors(self) -> None:
+        if not isinstance(self.vectors, tuple):
+            raise SourceContractError(
+                "TYPE",
+                "catalog_entry_v2.vectors",
+                "must be an immutable tuple",
+            )
+        for index, item in enumerate(self.vectors):
+            if not isinstance(item, LayerVectorReference):
+                raise SourceContractError(
+                    "TYPE",
+                    f"catalog_entry_v2.vectors[{index}]",
+                    "must be a LayerVectorReference",
+                )
+        if not self.vectors:
+            return
+        layers = tuple(item.layer for item in self.vectors)
+        if layers != EMBEDDING_LAYERS:
+            raise SourceContractError(
+                "CATALOG_VECTOR_LAYERS",
+                "catalog_entry_v2.vectors",
+                f"must carry exactly one vector for all layers in order {list(EMBEDDING_LAYERS)}",
+            )
+        for index, vector in enumerate(self.vectors):
+            if vector.entry_facts_digest != self.semantic_facts_digest:
+                raise SourceContractError(
+                    "CATALOG_VECTOR_FACTS",
+                    f"catalog_entry_v2.vectors[{index}].entry_facts_digest",
+                    "must equal this entry's semantic facts digest",
+                )
+
+    @property
+    def coordinate(self) -> str:
+        return f"{self.entry_id}@v{self.entry_version}"
+
+    @property
+    def semantic_facts_digest(self) -> str:
+        """Digest meaning and provider paths, excluding observations and vector instances."""
+
+        return canonical_sha256(self._semantic_payload())
+
+    @property
+    def provenance_history_digest(self) -> str:
+        """Digest the stable meaning coordinate plus every append-only sweep observation."""
+
+        return canonical_sha256(
+            {
+                "schema_version": self.schema_version,
+                "semantic_facts_digest": self.semantic_facts_digest,
+                "observations": [item.to_dict() for item in self.observations],
+            }
+        )
+
+    def _semantic_payload(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "entry_id": self.entry_id,
+            "entry_version": self.entry_version,
+            "provider_record": self.provider_record.to_dict(),
+            **{name: getattr(self, name).to_dict() for name in _FACT_FIELDS},
+            "previous_semantic_digest": self.previous_semantic_digest,
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            **self._semantic_payload(),
+            "observations": [item.to_dict() for item in self.observations],
+            "vectors": [item.to_dict() for item in self.vectors],
+        }
+
+
+def append_catalog_observation(
+    entry: CatalogEntryV2,
+    observation: CatalogObservation,
+) -> CatalogEntryV2:
+    """Append one evidence observation without minting a new semantic entry version."""
+
+    if not isinstance(entry, CatalogEntryV2):
+        raise SourceContractError("TYPE", "entry", "must be a CatalogEntryV2")
+    if not isinstance(observation, CatalogObservation):
+        raise SourceContractError("TYPE", "observation", "must be a CatalogObservation")
+    return replace(entry, observations=(*entry.observations, observation))
+
+
+def catalog_entry_from_canonical_bytes(data: bytes) -> CatalogEntry | CatalogEntryV2:
+    """Dispatch exact canonical bytes to frozen v1 or explicit v2 without reinterpretation."""
+
+    if not isinstance(data, (bytes, bytearray, memoryview)):
+        raise SourceContractError(
+            "TYPE",
+            "catalog_entry_bytes",
+            "must be a bytes-like value",
+        )
+    if len(data) > MAX_CATALOG_ENTRY_BYTES:
+        raise SourceContractError(
+            "CATALOG_ENTRY_BYTES",
+            "catalog_entry_bytes",
+            f"must contain at most {MAX_CATALOG_ENTRY_BYTES} bytes",
+        )
+    try:
+        decoded = parse_canonical_json(data)
+    except RecursionError:
+        # CPython's JSON decoder may reach its interpreter recursion limit before the canonical
+        # normalizer can issue JSON_DEPTH. Normalize both routes to one stable contract refusal.
+        raise SourceContractError(
+            "JSON_DEPTH",
+            "catalog_entry_bytes",
+            f"nesting exceeds {MAX_CATALOG_ENTRY_NESTING} levels",
+        ) from None
+    except CanonicalJSONError as error:
+        raise SourceContractError(
+            error.code,
+            "catalog_entry_bytes",
+            f"must be canonical JSON: {error.detail}",
+        ) from None
+    payload = _mapping(decoded, "catalog_entry")
+    schema_version = payload.get("schema_version")
+    if schema_version == CATALOG_ENTRY_CONTRACT_VERSION:
+        return catalog_entry_from_dict(payload)
+    if schema_version == CATALOG_ENTRY_V2_CONTRACT_VERSION:
+        return catalog_entry_v2_from_dict(payload)
+    raise SourceContractError(
+        "VERSION",
+        "catalog_entry.schema_version",
+        "must name the exact frozen v1 or explicit v2 catalog entry contract",
+    )
+
+
+def read_catalog_entry_for_retrieval(data: bytes) -> CatalogRetrievalRead:
+    """Parse a record for retrieval, durably skipping unsafe identity or provenance."""
+
+    try:
+        entry = catalog_entry_from_canonical_bytes(data)
+    except RecursionError:
+        # Defense in depth: this adapter is the retrieval trust boundary, so a future parser
+        # branch must not accidentally restore an interpreter exception as a public outcome.
+        return CatalogRetrievalRead(
+            entry=None,
+            schema_version=None,
+            retrieval_disposition="skipped",
+            searchable=False,
+            reason_code="JSON_DEPTH",
+        )
+    except SourceContractError as error:
+        return CatalogRetrievalRead(
+            entry=None,
+            schema_version=None,
+            retrieval_disposition="skipped",
+            searchable=False,
+            reason_code=error.code,
+        )
+    return CatalogRetrievalRead(
+        entry=entry,
+        schema_version=entry.schema_version,
+        retrieval_disposition="searchable",
+        searchable=True,
+        reason_code="OK",
+    )
+
+
+def evaluate_catalog_entry_v2(
+    entry: CatalogEntryV2,
+    *,
+    filters: tuple[CatalogFactFilter, ...] = (),
+) -> CatalogEntryV2Decision:
+    """Project searchable metadata and fail-closed fact authority without retrieval scores."""
+
+    if not isinstance(entry, CatalogEntryV2):
+        raise SourceContractError("TYPE", "entry", "must be a CatalogEntryV2")
+    if not isinstance(filters, tuple):
+        raise SourceContractError("TYPE", "filters", "must be an immutable tuple")
+    failures: list[str] = []
+    seen: set[str] = set()
+    for index, required in enumerate(filters):
+        if not isinstance(required, CatalogFactFilter):
+            raise SourceContractError(
+                "TYPE",
+                f"filters[{index}]",
+                "must be a CatalogFactFilter",
+            )
+        if required.field in seen:
+            raise SourceContractError(
+                "DUPLICATE",
+                f"filters[{index}].field",
+                "each structured fact may be filtered at most once",
+            )
+        seen.add(required.field)
+        fact = getattr(entry, required.field)
+        if fact.state != "known":
+            failures.append(f"{required.field}:{fact.state}")
+            continue
+        value = fact.value
+        matched = (
+            required.expected in value if isinstance(value, tuple) else value == required.expected
+        )
+        if not matched:
+            failures.append(f"{required.field}:mismatch")
+
+    rights_disposition = _v2_rights_disposition(entry.rights)
+    explicitly_public = (
+        entry.authentication_required.state == "known"
+        and entry.authentication_required.value is False
+        and entry.access_kind.state == "known"
+        and entry.data_formats.state == "known"
+    )
+    recommendation = (
+        "use_source"
+        if rights_disposition == "admitted" and explicitly_public and not failures
+        else "no_match"
+    )
+    return CatalogEntryV2Decision(
+        entry_coordinate=entry.coordinate,
+        searchable=True,
+        filters_match=not failures,
+        filter_failures=tuple(failures),
+        rights_disposition=rights_disposition,
+        recommendation=recommendation,
+        semantic_facts_digest=entry.semantic_facts_digest,
+        entry_digest=entry.digest,
+    )
+
+
+def _v2_rights_disposition(rights: CatalogFact) -> str:
+    if rights.state != "known":
+        return "flagged"
+    if rights.value == "approved":
+        return "admitted"
+    if rights.value == "prohibited":
+        return "refused"
+    # ``conditional`` lacks a v2 obligation fact, and ``unclear`` explicitly requires escalation.
+    return "flagged"
+
+
+def catalog_entry_v2_from_dict(data: Mapping[str, Any]) -> CatalogEntryV2:
+    """Strictly rebuild the one exact canonical v2 object shape."""
+
+    payload = _mapping(data, "catalog_entry_v2")
+    _exact(
+        payload,
+        {
+            "schema_version",
+            "entry_id",
+            "entry_version",
+            "provider_record",
+            *_FACT_FIELDS,
+            "observations",
+            "vectors",
+            "previous_semantic_digest",
+        },
+        "catalog_entry_v2",
+    )
+    provider_record = _provider_record_from_dict(payload["provider_record"])
+    facts = {
+        name: _fact_from_dict(
+            payload[name],
+            f"catalog_entry_v2.{name}",
+            tuple_value=name
+            in {
+                "spatial_scope",
+                "data_formats",
+                "declared_columns",
+                "declared_vocabulary",
+                "profiles",
+            },
+        )
+        for name in _FACT_FIELDS
+    }
+    return CatalogEntryV2(
+        schema_version=payload["schema_version"],
+        entry_id=payload["entry_id"],
+        entry_version=payload["entry_version"],
+        provider_record=provider_record,
+        **facts,
+        observations=tuple(
+            _observation_from_dict(item, f"catalog_entry_v2.observations[{index}]")
+            for index, item in enumerate(
+                _sequence(payload["observations"], "catalog_entry_v2.observations")
+            )
+        ),
+        vectors=tuple(
+            _vector_from_dict(item, f"catalog_entry_v2.vectors[{index}]")
+            for index, item in enumerate(_sequence(payload["vectors"], "catalog_entry_v2.vectors"))
+        ),
+        previous_semantic_digest=payload["previous_semantic_digest"],
+    )
+
+
+def _provider_record_from_dict(data: Any) -> ProviderRecordIdentity:
+    path = "catalog_entry_v2.provider_record"
+    payload = _mapping(data, path)
+    _exact(
+        payload,
+        {
+            "provider_id",
+            "provider_record_id",
+            "provider_record_sha256",
+            "identifier_json_path",
+        },
+        path,
+    )
+    return ProviderRecordIdentity(
+        provider_id=payload["provider_id"],
+        provider_record_id=payload["provider_record_id"],
+        provider_record_sha256=payload["provider_record_sha256"],
+        identifier_json_path=payload["identifier_json_path"],
+    )
+
+
+def _fact_from_dict(data: Any, path: str, *, tuple_value: bool) -> CatalogFact:
+    payload = _mapping(data, path)
+    _exact(payload, {"state", "value", "provenance"}, path)
+    value = payload["value"]
+    if tuple_value and value is not None:
+        value = tuple(_sequence(value, f"{path}.value"))
+    provenance_payload = payload["provenance"]
+    provenance = None
+    if provenance_payload is not None:
+        provenance_data = _mapping(provenance_payload, f"{path}.provenance")
+        _exact(
+            provenance_data,
+            {"provider_id", "provider_record_id", "provider_record_sha256", "json_paths"},
+            f"{path}.provenance",
+        )
+        provenance = ProviderFactProvenance(
+            provider_id=provenance_data["provider_id"],
+            provider_record_id=provenance_data["provider_record_id"],
+            provider_record_sha256=provenance_data["provider_record_sha256"],
+            json_paths=tuple(
+                _sequence(provenance_data["json_paths"], f"{path}.provenance.json_paths")
+            ),
+        )
+    return CatalogFact(state=payload["state"], value=value, provenance=provenance)
+
+
+def _observation_from_dict(data: Any, path: str) -> CatalogObservation:
+    payload = _mapping(data, path)
+    _exact(
+        payload,
+        {
+            "harvester_coordinate",
+            "observed_at",
+            "response_evidence_sha256",
+            "page_evidence_sha256",
+        },
+        path,
+    )
+    return CatalogObservation(
+        harvester_coordinate=payload["harvester_coordinate"],
+        observed_at=payload["observed_at"],
+        response_evidence_sha256=payload["response_evidence_sha256"],
+        page_evidence_sha256=payload["page_evidence_sha256"],
+    )
+
+
+def _vector_from_dict(data: Any, path: str) -> LayerVectorReference:
+    payload = _mapping(data, path)
+    _exact(
+        payload,
+        {
+            "layer",
+            "backend_id",
+            "backend_version",
+            "dimensions",
+            "quantization",
+            "vector_sha256",
+            "entry_facts_digest",
+        },
+        path,
+    )
+    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 _mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise SourceContractError("TYPE", path, "must be an object with string keys")
+    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}",
+            )
+        if ord(char) < 0x20 or 0x7F <= ord(char) <= 0x9F:
+            raise SourceContractError(
+                "CONTROL_CHARACTER",
+                path,
+                f"contains a C0/C1 control character at character {index}",
+            )
+        if char.isspace() and char != " ":
+            raise SourceContractError(
+                "UNSAFE_WHITESPACE",
+                path,
+                f"contains non-ASCII-space whitespace at character {index}",
+            )
+    return value
+
+
+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 _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 _boolean(value: Any, path: str) -> bool:
+    if type(value) is not bool:
+        raise SourceContractError("BOOLEAN", path, "must be a boolean")
+    return value
+
+
+def _provider_path(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=512)
+    valid_root = text.startswith("$")
+    position = 1 if valid_root else len(text)
+    segments = 0
+    while position < len(text):
+        named = _PROVIDER_NAMED_SEGMENT.match(text, position)
+        if named is not None:
+            position = named.end()
+            segments += 1
+            continue
+        if text.startswith("[*]", position):
+            position += 3
+            segments += 1
+            continue
+        if text.startswith('["', position):
+            end = text.find('"]', position + 2)
+            if end != -1:
+                key = text[position + 2 : end]
+                if key in _PROVIDER_QUOTED_KEYS:
+                    position = end + 2
+                    segments += 1
+                    continue
+        break
+    if not valid_root or position != len(text) or segments == 0:
+        raise SourceContractError(
+            "PROVIDER_PATH",
+            path,
+            "must use canonical named keys, optional [*], and only closed bracket-quoted keys",
+        )
+    return text
+
+
+def _provider_identifier_path(value: Any, path: str) -> str:
+    text = _provider_path(value, path)
+    if "[*]" in text:
+        raise SourceContractError(
+            "PROVIDER_IDENTIFIER_PATH",
+            path,
+            "must identify one singular named provider field without an array wildcard",
+        )
+    return text
+
+
+def _utc_second(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=20)
+    if not _UTC_SECOND.fullmatch(text):
+        raise SourceContractError("TIMESTAMP", path, "must be canonical UTC to whole seconds")
+    try:
+        parsed = datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=UTC)
+    except ValueError:
+        raise SourceContractError("TIMESTAMP", path, "must be a real UTC timestamp") from None
+    if parsed.strftime("%Y-%m-%dT%H:%M:%SZ") != text:
+        raise SourceContractError("TIMESTAMP", path, "must be canonical UTC to whole seconds")
+    return text
+
+
+def _known_text(fact: CatalogFact, path: str, *, maximum: int) -> None:
+    if fact.state == "known":
+        _text(fact.value, f"{path}.value", maximum=maximum)
+
+
+def _known_text_tuple(fact: CatalogFact, path: str, *, maximum: int) -> None:
+    if fact.state != "known":
+        return
+    value = fact.value
+    if not isinstance(value, tuple):
+        raise SourceContractError("TYPE", f"{path}.value", "must be an immutable tuple")
+    if len(value) > maximum:
+        raise SourceContractError("LIMIT", f"{path}.value", f"must contain at most {maximum}")
+    for index, item in enumerate(value):
+        _text(item, f"{path}.value[{index}]", maximum=MAX_DECLARED_NAME)
+    if len(set(value)) != len(value):
+        raise SourceContractError("DUPLICATE", f"{path}.value", "values must be unique")
+
+
+def _known_choice(fact: CatalogFact, path: str, *, allowed: frozenset[str]) -> None:
+    if fact.state == "known":
+        _choice(fact.value, allowed, f"{path}.value")
+
+
+def _known_choices(
+    fact: CatalogFact,
+    path: str,
+    *,
+    allowed: frozenset[str],
+    maximum: int,
+) -> None:
+    if fact.state != "known":
+        return
+    value = fact.value
+    if not isinstance(value, tuple):
+        raise SourceContractError("TYPE", f"{path}.value", "must be an immutable tuple")
+    if not value or len(value) > maximum:
+        raise SourceContractError(
+            "LIMIT",
+            f"{path}.value",
+            f"must contain between 1 and {maximum} values",
+        )
+    for index, item in enumerate(value):
+        _choice(item, allowed, f"{path}.value[{index}]")
+    if len(set(value)) != len(value):
+        raise SourceContractError("DUPLICATE", f"{path}.value", "values must be unique")
+
+
+def _known_boolean(fact: CatalogFact, path: str) -> None:
+    if fact.state == "known" and type(fact.value) is not bool:
+        raise SourceContractError("BOOLEAN", f"{path}.value", "must be a boolean")
+
+
+def _known_integer(fact: CatalogFact, path: str, *, minimum: int, maximum: int) -> None:
+    if fact.state != "known":
+        return
+    if type(fact.value) is not int or not minimum <= fact.value <= maximum:
+        raise SourceContractError(
+            "INTEGER",
+            f"{path}.value",
+            f"must be an integer in [{minimum}, {maximum}]",
+        )