mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/delta.py

@@ -0,0 +1,1340 @@
+"""Deterministic public-catalog deltas over one complete fill generation.
+
+Publisher identifiers and Harness entry identifiers are deliberately separate.  A caller must
+therefore provide both mappings explicitly: the current provider record to its authored candidate
+entry, and each predecessor provider record to the entry it previously produced.  This module
+never transliterates or guesses an identifier.
+
+Classification is read-only.  It binds one complete, converged ``FillStaging`` generation and
+produces admitted entries plus receipt-only absence and rights-review records.  Publication lives
+below so an incomplete page checkpoint can never accidentally become a public catalog.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.acquisition.url_policy import EgressPolicy
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.sources.catalog.authoring import (
+    seal_catalog_successor,
+    seal_retrieval_catalog_successor,
+)
+from mostlyright.data_harness.sources.catalog.contracts import (
+    CatalogEntry,
+    catalog_entry_from_dict,
+    next_entry_version,
+    verify_version_chain,
+)
+from mostlyright.data_harness.sources.catalog.embedding import EmbeddingBackend
+from mostlyright.data_harness.sources.catalog.fill import CatalogFillResult
+from mostlyright.data_harness.sources.catalog.fill_staging import FillStaging
+from mostlyright.data_harness.sources.catalog.harvest.ckan import ckan_licence_rights
+from mostlyright.data_harness.sources.catalog.harvest.protocol import HarvestedRecord
+from mostlyright.data_harness.sources.catalog.harvest.stac import stac_licence_rights
+from mostlyright.data_harness.sources.catalog.retrieval_manifest import (
+    LoadedRetrievalCatalog,
+    RetrievalManifestError,
+    load_retrieval_catalog,
+)
+from mostlyright.data_harness.sources.catalog.rights_decisions import RightsDecision
+from mostlyright.data_harness.sources.contracts import (
+    EvidenceReference,
+    LicenseObligation,
+    RightsEvidence,
+    SourceContractError,
+    SourceObservation,
+)
+from mostlyright.data_harness.sources.rights_rule import rights_disposition
+
+CATALOG_DELTA_SCHEMA = "harness-source-catalog-delta.v1"
+
+
+class CatalogDeltaError(SourceContractError):
+    """A stable refusal while classifying or publishing a catalog successor."""
+
+
+@dataclass(frozen=True)
+class CatalogAbsenceObservation:
+    """One predecessor provider record absent from a complete converged fill."""
+
+    record_id: str
+    entry_id: str
+    previous_coordinate: str
+    previous_facts_digest: str
+    observed_at: str
+    fill_receipt_sha256: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "record_id": self.record_id,
+            "entry_id": self.entry_id,
+            "previous_coordinate": self.previous_coordinate,
+            "previous_facts_digest": self.previous_facts_digest,
+            "observed_at": self.observed_at,
+            "fill_receipt_sha256": self.fill_receipt_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogFlaggedRecord:
+    """One provider record kept out of admission pending a rights decision."""
+
+    protocol: str
+    record_id: str
+    record_sha256: str
+    license_id: str | None
+    license_uri: str | None
+    rights_status: str
+    authority: str = "human_review_required"
+    entry_id: str | None = None
+    human_decision_reference: str | None = None
+    decided_at: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "protocol": self.protocol,
+            "record_id": self.record_id,
+            "record_sha256": self.record_sha256,
+            "license_id": self.license_id,
+            "license_uri": self.license_uri,
+            "rights_status": self.rights_status,
+            "authority": self.authority,
+            "entry_id": self.entry_id,
+            "human_decision_reference": self.human_decision_reference,
+            "decided_at": self.decided_at,
+        }
+
+
+@dataclass(frozen=True)
+class CatalogDeltaClassification:
+    """A complete deterministic partition of one fill against its predecessor."""
+
+    predecessor_sha256: str | None
+    fill_receipt_sha256: str
+    staging_sha256: str
+    records_sha256: str
+    unchanged: tuple[CatalogEntry, ...]
+    changed: tuple[CatalogEntry, ...]
+    new: tuple[CatalogEntry, ...]
+    absent: tuple[CatalogAbsenceObservation, ...]
+    flagged: tuple[CatalogFlaggedRecord, ...]
+    version_chains: tuple[tuple[CatalogEntry, ...], ...]
+    rights_decisions_sha256: str | None = None
+    schema_version: str = CATALOG_DELTA_SCHEMA
+
+    @property
+    def admitted_entries(self) -> tuple[CatalogEntry, ...]:
+        return tuple(sorted((*self.unchanged, *self.changed, *self.new), key=_entry_key))
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "predecessor_sha256": self.predecessor_sha256,
+            "fill_receipt_sha256": self.fill_receipt_sha256,
+            "staging_sha256": self.staging_sha256,
+            "records_sha256": self.records_sha256,
+            "rights_decisions_sha256": self.rights_decisions_sha256,
+            "counts": {
+                "unchanged": len(self.unchanged),
+                "changed": len(self.changed),
+                "new": len(self.new),
+                "absent": len(self.absent),
+                "flagged": len(self.flagged),
+                "admitted": len(self.admitted_entries),
+            },
+            "unchanged": [_entry_receipt(item) for item in self.unchanged],
+            "changed": [_entry_receipt(item) for item in self.changed],
+            "new": [_entry_receipt(item) for item in self.new],
+            "absent": [item.to_dict() for item in self.absent],
+            "flagged": [item.to_dict() for item in self.flagged],
+            "version_chains": [
+                [_entry_receipt(item) for item in chain] for chain in self.version_chains
+            ],
+        }
+
+
+@dataclass(frozen=True)
+class CatalogDeltaPublication:
+    """The exact durable v1 successor and its incremental-work receipt."""
+
+    delta_sha256: str
+    manifest_sha256: str
+    entries: tuple[CatalogEntry, ...]
+    reused_vector_sha256s: tuple[str, ...]
+    created_vector_sha256s: tuple[str, ...]
+    encoder_invocations: int
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": "harness-source-catalog-publication.v1",
+            "delta_sha256": self.delta_sha256,
+            "manifest_sha256": self.manifest_sha256,
+            "entries": [_entry_receipt(entry) for entry in self.entries],
+            "reused_vector_sha256s": list(self.reused_vector_sha256s),
+            "created_vector_sha256s": list(self.created_vector_sha256s),
+            "encoder_invocations": self.encoder_invocations,
+        }
+
+
+@dataclass(frozen=True)
+class RetrievalCatalogDeltaPublication:
+    """Canonical v2 delta receipt with independent representation work accounting."""
+
+    delta_sha256: str
+    classification_checkpoint_sha256: str
+    manifest_sha256: str
+    entries: tuple[CatalogEntry, ...]
+    unchanged: int
+    changed: int
+    new: int
+    absent: int
+    flagged: int
+    lexical_reused_vector_sha256s: tuple[str, ...]
+    lexical_created_vector_sha256s: tuple[str, ...]
+    neural_reused_vector_sha256s: tuple[str, ...]
+    neural_created_vector_sha256s: tuple[str, ...]
+    lexical_encoder_invocations: int
+    neural_encoder_invocations: int
+    fallback_reason: str | None
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": "harness-source-catalog-retrieval-publication.v2",
+            "delta_sha256": self.delta_sha256,
+            "classification_checkpoint_sha256": self.classification_checkpoint_sha256,
+            "manifest_sha256": self.manifest_sha256,
+            "counts": {
+                "unchanged": self.unchanged,
+                "changed": self.changed,
+                "new": self.new,
+                "absent": self.absent,
+                "flagged": self.flagged,
+            },
+            "entries": [_entry_receipt(entry) for entry in self.entries],
+            "representations": {
+                "lexical": {
+                    "reused_vector_sha256s": list(self.lexical_reused_vector_sha256s),
+                    "created_vector_sha256s": list(self.lexical_created_vector_sha256s),
+                    "encoder_invocations": self.lexical_encoder_invocations,
+                },
+                "neural": {
+                    "reused_vector_sha256s": list(self.neural_reused_vector_sha256s),
+                    "created_vector_sha256s": list(self.neural_created_vector_sha256s),
+                    "encoder_invocations": self.neural_encoder_invocations,
+                },
+            },
+            "fallback_reason": self.fallback_reason,
+        }
+
+
+@dataclass(frozen=True)
+class _FillSnapshot:
+    records: tuple[HarvestedRecord, ...]
+    flagged: tuple[CatalogFlaggedRecord, ...]
+    observed_at: str
+    records_sha256: str
+
+
+def classify_catalog_delta(
+    *,
+    predecessor: tuple[CatalogEntry, ...],
+    predecessor_record_ids: Mapping[str, str],
+    candidates_by_record_id: Mapping[str, CatalogEntry],
+    fill_result: CatalogFillResult,
+    staging_root: Path,
+    predecessor_chains: Mapping[str, tuple[CatalogEntry, ...]] | None = None,
+    rights_decisions: Mapping[str, RightsDecision] | None = None,
+    rights_decisions_sha256: str | None = None,
+) -> CatalogDeltaClassification:
+    """Partition a complete fill into unchanged, changed, new, absent, and flagged facts.
+
+    ``candidates_by_record_id`` contains authored, unsealed entries for every non-flagged provider
+    record. ``predecessor_record_ids`` preserves the explicit provider-to-Harness identity chosen
+    when the predecessor was authored.  Neither map is inferred from publisher text.
+
+    ``rights_decisions`` is the queue's one exit. Each decision must name a record the queue
+    holds and bind the exact bytes the person decided against; a cleared record leaves the
+    queue and demands a candidate whose rights are exactly the decided rights, and a
+    prohibited record stays out of admission carrying the decision, so the queue
+    distinguishes "nobody has looked" from "somebody looked and said no".
+    """
+
+    previous_by_id, chains = _validate_predecessor(
+        predecessor, predecessor_record_ids, predecessor_chains or {}
+    )
+    snapshot = _capture_complete_fill(fill_result, staging_root)
+    records_by_id = {record.record_id: record for record in snapshot.records}
+    staged_flagged = {item.record_id: item for item in snapshot.flagged}
+
+    decisions = dict(rights_decisions or {})
+    if decisions:
+        _validate_mapping(decisions, "rights_decisions")
+    prohibited_ids: set[str] = set()
+    for record_id in sorted(decisions):
+        decision = decisions[record_id]
+        if not isinstance(decision, RightsDecision):
+            raise CatalogDeltaError(
+                "TYPE", f"delta.rights_decisions.{record_id}", "must be a RightsDecision"
+            )
+        if decision.record_id != record_id:
+            raise CatalogDeltaError(
+                "CATALOG_RIGHTS_DECISION_TARGET",
+                f"delta.rights_decisions.{record_id}",
+                "the decision names a different record than the mapping key; one decision "
+                "is about one record, spelled once",
+            )
+        record = records_by_id.get(record_id)
+        if record is None:
+            raise CatalogDeltaError(
+                "CATALOG_RIGHTS_DECISION_TARGET",
+                f"delta.rights_decisions.{record_id}",
+                "names a record this fill did not observe",
+            )
+        if decision.record_facts_sha256 != record.facts_sha256:
+            raise CatalogDeltaError(
+                "CATALOG_RIGHTS_DECISION_DRIFT",
+                f"delta.rights_decisions.{record_id}",
+                "the record's published facts changed after this decision was made; a "
+                "decision is about one spelling of the facts, so a person must decide "
+                "again against the current facts",
+            )
+        staged = staged_flagged.get(record_id)
+        if decision.cleared:
+            if staged is None:
+                raise CatalogDeltaError(
+                    "CATALOG_RIGHTS_DECISION_TARGET",
+                    f"delta.rights_decisions.{record_id}",
+                    "names a record the rights queue does not hold; the provider states "
+                    "its own licence, so there is nothing left for a clearance to clear",
+                )
+            if staged.rights_status == "prohibited":
+                raise CatalogDeltaError(
+                    "CATALOG_RIGHTS_DECISION_OVERRULE",
+                    f"delta.rights_decisions.{record_id}",
+                    "the provider's own licence prohibits reuse; a decision may clear "
+                    "silence, never overrule a provider's explicit no",
+                )
+        else:
+            # A person's no outranks a provider's yes, so a prohibiting decision holds
+            # whether or not the provider's own licence would have admitted the record.
+            prohibited_ids.add(record_id)
+    cleared_ids = {record_id for record_id, item in decisions.items() if item.cleared}
+
+    _validate_mapping(candidates_by_record_id, "candidates_by_record_id")
+    candidate_keys = set(candidates_by_record_id)
+    required_candidate_keys = (
+        (set(records_by_id) - set(staged_flagged)) | cleared_ids
+    ) - prohibited_ids
+    if candidate_keys != required_candidate_keys:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CANDIDATE_MAPPING",
+            "delta.candidates_by_record_id",
+            "must name exactly every current provider record not held by the rights queue, "
+            "plus every record a decision cleared out of it, minus every record a decision "
+            "prohibits; "
+            f"missing={sorted(required_candidate_keys - candidate_keys)}, "
+            f"extra={sorted(candidate_keys - required_candidate_keys)}",
+        )
+
+    unchanged: list[CatalogEntry] = []
+    changed: list[CatalogEntry] = []
+    new: list[CatalogEntry] = []
+    flagged: dict[str, CatalogFlaggedRecord] = dict(staged_flagged)
+    for record_id, decision in decisions.items():
+        if decision.cleared:
+            flagged.pop(record_id, None)
+        else:
+            record = records_by_id[record_id]
+            flagged[record_id] = CatalogFlaggedRecord(
+                protocol=record.protocol,
+                record_id=record.record_id,
+                record_sha256=record.digest,
+                license_id=record.license_id,
+                license_uri=record.license_uri,
+                rights_status=decision.rights.status,
+                authority="human_decision",
+                entry_id=None,
+                human_decision_reference=decision.human_decision_reference,
+                decided_at=decision.decided_at,
+            )
+    resulting_chains: list[tuple[CatalogEntry, ...]] = []
+
+    for record_id in sorted(required_candidate_keys):
+        record = records_by_id[record_id]
+        decision = decisions.get(record_id)
+        candidate = _validated_candidate(
+            record_id,
+            record,
+            candidates_by_record_id[record_id],
+            decided_rights=decision.rights if decision is not None else None,
+        )
+        disposition = rights_disposition(candidate.rights.status)
+        if disposition != "admit":
+            flagged[record_id] = CatalogFlaggedRecord(
+                protocol=record.protocol,
+                record_id=record.record_id,
+                record_sha256=record.digest,
+                license_id=record.license_id,
+                license_uri=record.license_uri,
+                rights_status=candidate.rights.status,
+                entry_id=candidate.entry_id,
+            )
+            continue
+        previous_id = predecessor_record_ids.get(record_id)
+        if previous_id is None:
+            if candidate.entry_id in previous_by_id:
+                raise CatalogDeltaError(
+                    "CATALOG_DELTA_PREDECESSOR_MAPPING",
+                    f"delta.candidates_by_record_id.{record_id}",
+                    "a current entry reuses a predecessor entry_id without an explicit provider "
+                    "record mapping",
+                )
+            new.append(candidate)
+            resulting_chains.append((candidate,))
+            verify_version_chain((candidate,))
+            continue
+        previous = previous_by_id[previous_id]
+        if candidate.entry_id != previous.entry_id:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_ENTRY_ID",
+                f"delta.candidates_by_record_id.{record_id}.entry_id",
+                f"must remain {previous.entry_id!r} for this predecessor mapping",
+            )
+        chain = chains[previous.entry_id]
+        # ``CatalogEntry.facts_digest`` correctly commits the version and predecessor link. The
+        # author's current spelling is deliberately v1 so those managed fields necessarily differ
+        # from a v2+ head even when every observed/public fact is unchanged. Compare the canonical
+        # non-managed projection for classification; keep ``facts_digest`` for the chain link.
+        if _classifiable_facts_digest(candidate) == _classifiable_facts_digest(previous):
+            unchanged.append(previous)
+            resulting_chains.append(chain)
+            continue
+        successor = next_entry_version(previous, **_successor_changes(candidate))
+        successor_chain = (*chain, successor)
+        verify_version_chain(successor_chain)
+        changed.append(successor)
+        resulting_chains.append(successor_chain)
+
+    current_record_ids = set(records_by_id)
+    absent: list[CatalogAbsenceObservation] = []
+    for record_id in sorted(set(predecessor_record_ids) - current_record_ids):
+        previous = previous_by_id[predecessor_record_ids[record_id]]
+        absent.append(
+            CatalogAbsenceObservation(
+                record_id=record_id,
+                entry_id=previous.entry_id,
+                previous_coordinate=previous.coordinate,
+                previous_facts_digest=previous.facts_digest,
+                observed_at=snapshot.observed_at,
+                fill_receipt_sha256=fill_result.receipt.digest,
+            )
+        )
+
+    # A current flagged record is neither admitted nor absent. Its prior public head is removed
+    # from the current-head manifest, while the canonical queue preserves why that happened.
+    ordered_flags = tuple(
+        sorted(flagged.values(), key=lambda item: (item.protocol, item.record_id))
+    )
+    ordered_chains = tuple(sorted(resulting_chains, key=lambda chain: _entry_key(chain[-1])))
+    return CatalogDeltaClassification(
+        predecessor_sha256=fill_result.receipt.predecessor_sha256,
+        fill_receipt_sha256=fill_result.receipt.digest,
+        staging_sha256=fill_result.eligible_staging_sha256 or "",
+        records_sha256=snapshot.records_sha256,
+        unchanged=tuple(sorted(unchanged, key=_entry_key)),
+        changed=tuple(sorted(changed, key=_entry_key)),
+        new=tuple(sorted(new, key=_entry_key)),
+        absent=tuple(absent),
+        flagged=ordered_flags,
+        version_chains=ordered_chains,
+        rights_decisions_sha256=rights_decisions_sha256,
+    )
+
+
+def publish_catalog_successor(
+    classification: CatalogDeltaClassification,
+    *,
+    backend: EmbeddingBackend,
+    directory: Path,
+    predecessor_directory: Path | None,
+    egress_policy: EgressPolicy,
+) -> CatalogDeltaPublication:
+    """Publish a fully classified current-head successor with durable exact readback."""
+
+    _validate_classification_for_publication(classification)
+    try:
+        sealed = seal_catalog_successor(
+            reused_entries=classification.unchanged,
+            fresh_entries=tuple((*classification.changed, *classification.new)),
+            backend=backend,
+            directory=directory,
+            predecessor_directory=predecessor_directory,
+            predecessor_manifest_sha256=classification.predecessor_sha256,
+            egress_policy=egress_policy,
+        )
+    except CatalogDeltaError:
+        raise
+    except SourceContractError as error:
+        raise CatalogDeltaError(error.code, error.path, error.detail) from error
+    except OSError as error:
+        raise CatalogDeltaError(
+            "CATALOG_PUBLICATION",
+            "catalog.directory",
+            "durable catalog publication failed",
+        ) from error
+    return CatalogDeltaPublication(
+        delta_sha256=classification.digest,
+        manifest_sha256=sealed.manifest_sha256,
+        entries=sealed.entries,
+        reused_vector_sha256s=sealed.reused_vector_sha256s,
+        created_vector_sha256s=sealed.created_vector_sha256s,
+        encoder_invocations=sealed.encoder_invocations,
+    )
+
+
+def checkpoint_catalog_delta_classification(
+    classification: CatalogDeltaClassification,
+    *,
+    staging_root: Path,
+    lexical_backend: EmbeddingBackend,
+    neural_backend: EmbeddingBackend | None,
+) -> str:
+    """Persist the complete classification before either representation is encoded."""
+
+    _validate_classification_for_publication(classification)
+    staging = FillStaging(staging_root)
+    with staging.locked():
+        state = staging.load()
+        if state is None or staging.state_digest() != classification.staging_sha256:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_STAGING",
+                "delta.classification.staging_sha256",
+                "classification does not bind the live complete staging generation",
+            )
+        if not state["completed"] or state["reason_code"] is not None or state["pass_drift"]:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_INCOMPLETE",
+                "delta.staging",
+                "classification checkpoints require complete converged staging",
+            )
+        return staging.write_shard(
+            "classification",
+            _classification_checkpoint_payload(
+                classification,
+                lexical_coordinate=lexical_backend.descriptor.coordinate,
+                neural_coordinate=None
+                if neural_backend is None
+                else neural_backend.descriptor.coordinate,
+            ),
+        )
+
+
+def load_catalog_delta_classification(
+    checkpoint_sha256: str,
+    *,
+    staging_root: Path,
+    expected_staging_sha256: str,
+    expected_predecessor_sha256: str | None,
+    lexical_backend: EmbeddingBackend,
+    neural_backend: EmbeddingBackend | None,
+) -> CatalogDeltaClassification:
+    """Restore a checkpoint only under the exact staging, predecessor, and model tuple."""
+
+    staging = FillStaging(staging_root)
+    with staging.locked():
+        state = staging.load()
+        if state is None or staging.state_digest() != expected_staging_sha256:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_STAGING",
+                "delta.classification.staging_sha256",
+                "live staging differs from the expected complete generation",
+            )
+        payload = staging.read_shard("classification", checkpoint_sha256)
+    exact = {
+        "schema_version",
+        "classification_sha256",
+        "staging_sha256",
+        "predecessor_sha256",
+        "lexical_coordinate",
+        "neural_coordinate",
+        "classification",
+    }
+    if not isinstance(payload, dict) or set(payload) != exact:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CHECKPOINT", "delta.classification", "checkpoint fields differ"
+        )
+    expected_neural = None if neural_backend is None else neural_backend.descriptor.coordinate
+    if (
+        payload["schema_version"] != "harness-source-catalog-delta-checkpoint.v1"
+        or payload["staging_sha256"] != expected_staging_sha256
+        or payload["predecessor_sha256"] != expected_predecessor_sha256
+        or payload["lexical_coordinate"] != lexical_backend.descriptor.coordinate
+        or payload["neural_coordinate"] != expected_neural
+    ):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CHECKPOINT_BINDING",
+            "delta.classification",
+            "checkpoint staging, predecessor, or representation coordinate differs",
+        )
+    rebuilt = _classification_from_checkpoint(payload["classification"])
+    if rebuilt.digest != payload["classification_sha256"]:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CHECKPOINT",
+            "delta.classification",
+            "checkpoint classification digest differs",
+        )
+    _validate_classification_for_publication(rebuilt)
+    return rebuilt
+
+
+def publish_retrieval_catalog_successor(
+    classification: CatalogDeltaClassification,
+    *,
+    classification_checkpoint_sha256: str,
+    staging_root: Path,
+    lexical_backend: EmbeddingBackend,
+    neural_backend: EmbeddingBackend | None,
+    directory: Path,
+    predecessor_directory: Path | None,
+    egress_policy: EgressPolicy,
+    fallback_reason: str | None = None,
+    expected_existing_manifest_sha256: str | None = None,
+) -> RetrievalCatalogDeltaPublication:
+    """Publish one v2 successor from the exact complete checkpointed classification."""
+
+    restored = load_catalog_delta_classification(
+        classification_checkpoint_sha256,
+        staging_root=staging_root,
+        expected_staging_sha256=classification.staging_sha256,
+        expected_predecessor_sha256=classification.predecessor_sha256,
+        lexical_backend=lexical_backend,
+        neural_backend=neural_backend,
+    )
+    if restored != classification:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CHECKPOINT_BINDING",
+            "delta.classification",
+            "supplied classification differs from its immutable checkpoint",
+        )
+
+    predecessor: LoadedRetrievalCatalog | None = None
+    if classification.predecessor_sha256 is not None:
+        if predecessor_directory is None:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_PREDECESSOR",
+                "delta.predecessor",
+                "an exact predecessor directory is required",
+            )
+        try:
+            predecessor = load_retrieval_catalog(
+                predecessor_directory,
+                expected_manifest_sha256=classification.predecessor_sha256,
+                neural_backend=neural_backend,
+            )
+        except (RetrievalManifestError, SourceContractError) as error:
+            raise CatalogDeltaError(error.code, error.path, error.detail) from error
+
+    lexical_reused = classification.unchanged
+    neural_reused: tuple[CatalogEntry, ...] = ()
+    if predecessor is not None:
+        previous_lexical = {entry.entry_id: entry for entry in predecessor.lexical.entries}
+        if any(previous_lexical.get(entry.entry_id) != entry for entry in lexical_reused):
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_PREDECESSOR",
+                "delta.unchanged",
+                "unchanged lexical entries differ from the exact predecessor representation",
+            )
+        if neural_backend is not None and predecessor.neural is not None:
+            previous_neural = {entry.entry_id: entry for entry in predecessor.neural.entries}
+            neural_reused = tuple(previous_neural[entry.entry_id] for entry in lexical_reused)
+
+    try:
+        sealed = seal_retrieval_catalog_successor(
+            lexical_reused_entries=lexical_reused,
+            fresh_entries=tuple((*classification.changed, *classification.new)),
+            lexical_backend=lexical_backend,
+            neural_reused_entries=neural_reused,
+            neural_backend=neural_backend,
+            directory=directory,
+            predecessor_retrieval_directory=predecessor_directory,
+            predecessor_retrieval_manifest_sha256=classification.predecessor_sha256,
+            egress_policy=egress_policy,
+            fallback_reason=fallback_reason,
+            expected_existing_manifest_sha256=expected_existing_manifest_sha256,
+        )
+    except SourceContractError as error:
+        raise CatalogDeltaError(error.code, error.path, error.detail) from error
+    except OSError as error:
+        raise CatalogDeltaError(
+            "CATALOG_PUBLICATION",
+            "catalog.directory",
+            "durable retrieval publication failed",
+        ) from error
+    return RetrievalCatalogDeltaPublication(
+        delta_sha256=classification.digest,
+        classification_checkpoint_sha256=classification_checkpoint_sha256,
+        manifest_sha256=sealed.manifest_sha256,
+        entries=sealed.lexical_entries,
+        unchanged=len(classification.unchanged),
+        changed=len(classification.changed),
+        new=len(classification.new),
+        absent=len(classification.absent),
+        flagged=len(classification.flagged),
+        lexical_reused_vector_sha256s=sealed.lexical_reused_vector_sha256s,
+        lexical_created_vector_sha256s=sealed.lexical_created_vector_sha256s,
+        neural_reused_vector_sha256s=sealed.neural_reused_vector_sha256s,
+        neural_created_vector_sha256s=sealed.neural_created_vector_sha256s,
+        lexical_encoder_invocations=sealed.lexical_encoder_invocations,
+        neural_encoder_invocations=sealed.neural_encoder_invocations,
+        fallback_reason=sealed.manifest.fallback_reason,
+    )
+
+
+def _validate_classification_for_publication(
+    classification: CatalogDeltaClassification,
+) -> None:
+    if not isinstance(classification, CatalogDeltaClassification):
+        raise CatalogDeltaError(
+            "TYPE", "delta.classification", "must be a CatalogDeltaClassification"
+        )
+    if classification.schema_version != CATALOG_DELTA_SCHEMA:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_VERSION", "delta.schema_version", "unsupported version"
+        )
+    partitions = (classification.unchanged, classification.changed, classification.new)
+    for name, entries in zip(("unchanged", "changed", "new"), partitions, strict=True):
+        if tuple(sorted(entries, key=_entry_key)) != entries:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_ORDER", f"delta.{name}", "entries must be sorted"
+            )
+    if any(not entry.vectors for entry in classification.unchanged):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_REUSE", "delta.unchanged", "unchanged entries must remain sealed"
+        )
+    if any(entry.vectors for entry in (*classification.changed, *classification.new)):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_REUSE",
+            "delta.changed",
+            "changed and new entries must be encoded from unsealed facts",
+        )
+    admitted = classification.admitted_entries
+    if len({entry.entry_id for entry in admitted}) != len(admitted):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_DUPLICATE", "delta.entries", "entry ids must be unique"
+        )
+    if any(rights_disposition(entry.rights.status) != "admit" for entry in admitted):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_RIGHTS",
+            "delta.entries",
+            "a non-admitted rights status cannot enter the public manifest",
+        )
+    if (
+        tuple(sorted(classification.absent, key=lambda item: item.record_id))
+        != classification.absent
+    ):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_ORDER", "delta.absent", "absence observations must be sorted"
+        )
+    if (
+        tuple(
+            sorted(
+                classification.flagged,
+                key=lambda item: (item.protocol, item.record_id),
+            )
+        )
+        != classification.flagged
+    ):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_ORDER", "delta.flagged", "rights queue must be sorted"
+        )
+    heads: dict[str, CatalogEntry] = {}
+    for chain in classification.version_chains:
+        verify_version_chain(chain)
+        head = chain[-1]
+        if head.entry_id in heads:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_VERSION_CHAIN",
+                "delta.version_chains",
+                "one version chain is allowed per admitted entry",
+            )
+        heads[head.entry_id] = head
+    if set(heads) != {entry.entry_id for entry in admitted}:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_VERSION_CHAIN",
+            "delta.version_chains",
+            "verified chains must cover every admitted entry",
+        )
+    for entry in admitted:
+        head = heads[entry.entry_id]
+        if head.coordinate != entry.coordinate or head.facts_digest != entry.facts_digest:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_VERSION_CHAIN",
+                f"delta.version_chains.{entry.entry_id}",
+                "verified chain head differs from the admitted entry",
+            )
+
+
+def _validate_predecessor(
+    predecessor: tuple[CatalogEntry, ...],
+    record_ids: Mapping[str, str],
+    supplied_chains: Mapping[str, tuple[CatalogEntry, ...]],
+) -> tuple[dict[str, CatalogEntry], dict[str, tuple[CatalogEntry, ...]]]:
+    if not isinstance(predecessor, tuple) or any(
+        type(entry) is not CatalogEntry for entry in predecessor
+    ):
+        raise CatalogDeltaError("TYPE", "delta.predecessor", "must be a tuple of CatalogEntry")
+    previous_by_id = {entry.entry_id: entry for entry in predecessor}
+    if len(previous_by_id) != len(predecessor):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_PREDECESSOR", "delta.predecessor", "entry ids must be unique"
+        )
+    _validate_mapping(record_ids, "predecessor_record_ids")
+    if len(set(record_ids.values())) != len(record_ids):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_PREDECESSOR_MAPPING",
+            "delta.predecessor_record_ids",
+            "one predecessor entry must map to exactly one provider record",
+        )
+    if set(record_ids.values()) != set(previous_by_id):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_PREDECESSOR_MAPPING",
+            "delta.predecessor_record_ids",
+            "must map every predecessor entry exactly once; "
+            f"missing={sorted(set(previous_by_id) - set(record_ids.values()))}, "
+            f"unknown={sorted(set(record_ids.values()) - set(previous_by_id))}",
+        )
+    if set(supplied_chains) - set(previous_by_id):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_VERSION_CHAIN",
+            "delta.predecessor_chains",
+            "contains a chain for an unknown predecessor entry",
+        )
+    chains: dict[str, tuple[CatalogEntry, ...]] = {}
+    for entry_id, previous in previous_by_id.items():
+        chain = supplied_chains.get(entry_id)
+        if chain is None:
+            if previous.entry_version != 1:
+                raise CatalogDeltaError(
+                    "CATALOG_DELTA_VERSION_CHAIN",
+                    f"delta.predecessor_chains.{entry_id}",
+                    "a predecessor after v1 requires its complete explicit version chain",
+                )
+            chain = (previous,)
+        verify_version_chain(chain)
+        head = chain[-1]
+        if head.coordinate != previous.coordinate or head.facts_digest != previous.facts_digest:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_VERSION_CHAIN",
+                f"delta.predecessor_chains.{entry_id}",
+                "the verified chain head does not match the predecessor snapshot",
+            )
+        chains[entry_id] = chain
+    return previous_by_id, chains
+
+
+def _capture_complete_fill(fill_result: CatalogFillResult, staging_root: Path) -> _FillSnapshot:
+    if not isinstance(fill_result, CatalogFillResult):
+        raise CatalogDeltaError("TYPE", "delta.fill_result", "must be a CatalogFillResult")
+    receipt = fill_result.receipt
+    eligible = fill_result.eligible_staging_sha256
+    if (
+        fill_result.status != "complete"
+        or fill_result.reason_code is not None
+        or receipt.status != "complete"
+        or receipt.reason_code is not None
+        or eligible is None
+        or eligible != fill_result.checkpoint_sha256
+    ):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_INCOMPLETE",
+            "delta.fill_result",
+            "only one complete reconciled fill generation may be classified",
+        )
+    if not isinstance(staging_root, Path):
+        raise CatalogDeltaError("TYPE", "delta.staging_root", "must be a Path")
+    staging = FillStaging(staging_root)
+    with staging.locked():
+        state = staging.load()
+        if state is None or staging.state_digest() != eligible:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_STAGING",
+                "delta.staging",
+                "the eligible fill generation is not the live staged generation",
+            )
+        if not state["completed"] or state["reason_code"] is not None or state["pass_drift"]:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_INCOMPLETE",
+                "delta.staging",
+                "staging is not complete and converged",
+            )
+        bindings = (
+            receipt.config_sha256 == state["config_sha256"]
+            and receipt.endpoint == state["endpoint"]
+            and receipt.harvester_coordinate == state["harvester_coordinate"]
+            and receipt.predecessor_sha256 == state["predecessor_sha256"]
+            and receipt.page_shard_digests == tuple(state["page_shards"])
+            and receipt.response_evidence_digests == tuple(state["response_shards"])
+            and receipt.pages == state["budget"]["pages"]
+            and receipt.requests == state["budget"]["requests"]
+            and receipt.responses == state["budget"]["responses"]
+            and receipt.records == state["budget"]["records"]
+            and receipt.network_bytes == state["budget"]["network_bytes"]
+            and receipt.elapsed_ns == state["budget"]["elapsed_ns"]
+            and receipt.skipped_records == state["budget"]["skipped_records"]
+            and receipt.provider_count == state["provider_count"]
+            and receipt.count_basis == state["count_basis"]
+            and receipt.convergence_passes == state["pass_number"]
+        )
+        if not bindings:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_RECEIPT",
+                "delta.fill_result.receipt",
+                "receipt does not bind the live complete staging generation",
+            )
+        records: dict[str, HarvestedRecord] = {}
+        flags: dict[tuple[str, str], CatalogFlaggedRecord] = {}
+        observed_at: str | None = None
+        for digest in state["page_shards"][state["pass_start_index"] :]:
+            page = staging.read_shard("page", digest)
+            page_evidence = _evidence_from_dict(page.get("evidence"), "delta.page.evidence")
+            if observed_at is None:
+                observed_at = page_evidence.observed_at
+            elif observed_at != page_evidence.observed_at:
+                raise CatalogDeltaError(
+                    "CATALOG_DELTA_OBSERVATION",
+                    "delta.page.evidence.observed_at",
+                    "one fill generation must use one observation time",
+                )
+            raw_records = page.get("records")
+            if not isinstance(raw_records, list):
+                raise CatalogDeltaError(
+                    "CATALOG_DELTA_STAGING", "delta.page.records", "must be an array"
+                )
+            page_map = page.get("id_facts")
+            if not isinstance(page_map, dict):
+                raise CatalogDeltaError(
+                    "CATALOG_DELTA_STAGING", "delta.page.id_facts", "must be an object"
+                )
+            for raw in raw_records:
+                record = _record_from_dict(raw)
+                if page_map.get(record.record_id) != record.digest:
+                    raise CatalogDeltaError(
+                        "CATALOG_DELTA_STAGING",
+                        f"delta.page.id_facts.{record.record_id}",
+                        "does not match the staged record facts",
+                    )
+                prior = records.get(record.record_id)
+                if prior is not None and prior.digest != record.digest:
+                    raise CatalogDeltaError(
+                        "CATALOG_DELTA_STAGING",
+                        f"delta.records.{record.record_id}",
+                        "complete generation contains conflicting record facts",
+                    )
+                records[record.record_id] = record
+            raw_flags = page.get("flagged_rights")
+            if not isinstance(raw_flags, list):
+                raise CatalogDeltaError(
+                    "CATALOG_DELTA_STAGING", "delta.page.flagged_rights", "must be an array"
+                )
+            for raw_flag in raw_flags:
+                flag = _flag_from_dict(raw_flag)
+                flags[(flag.protocol, flag.record_id)] = flag
+        if observed_at is None:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_STAGING", "delta.page_shards", "complete fill has no final page"
+            )
+        record_map = {record_id: records[record_id].digest for record_id in sorted(records)}
+        if canonical_sha256(record_map) != state["final_map_sha256"]:
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_STAGING",
+                "delta.staging.final_map_sha256",
+                "final staged records do not match the converged map",
+            )
+        ordered_flags = tuple(flags[key] for key in sorted(flags))
+        # The receipt binds exactly what the fill staged. Decision facts join a flag only at
+        # classification, downstream of staging, so the queue digest is computed over the
+        # staged shape rather than over ``to_dict``, which now also carries them.
+        fill_queue = [
+            {
+                "protocol": item.protocol,
+                "record_id": item.record_id,
+                "record_sha256": item.record_sha256,
+                "license_id": item.license_id,
+                "license_uri": item.license_uri,
+                "rights_status": item.rights_status,
+                "authority": item.authority,
+            }
+            for item in ordered_flags
+        ]
+        if (
+            receipt.unique_records != len(records)
+            or receipt.flagged_rights != len(ordered_flags)
+            or receipt.flagged_queue_sha256 != canonical_sha256(fill_queue)
+        ):
+            raise CatalogDeltaError(
+                "CATALOG_DELTA_RECEIPT",
+                "delta.fill_result.receipt",
+                "receipt counts or rights queue do not match final staged facts",
+            )
+        return _FillSnapshot(
+            records=tuple(records[key] for key in sorted(records)),
+            flagged=ordered_flags,
+            observed_at=observed_at,
+            records_sha256=canonical_sha256(record_map),
+        )
+
+
+def _validate_mapping(mapping: Mapping[str, Any], name: str) -> None:
+    if not isinstance(mapping, Mapping) or any(
+        not isinstance(key, str) or not key for key in mapping
+    ):
+        raise CatalogDeltaError("TYPE", f"delta.{name}", "must be a string-keyed mapping")
+
+
+def _validated_candidate(
+    record_id: str,
+    record: HarvestedRecord,
+    candidate: CatalogEntry,
+    *,
+    decided_rights: RightsEvidence | None = None,
+) -> CatalogEntry:
+    if type(candidate) is not CatalogEntry:
+        raise CatalogDeltaError(
+            "TYPE", f"delta.candidates_by_record_id.{record_id}", "must be a CatalogEntry"
+        )
+    if candidate.entry_version != 1 or candidate.previous_digest is not None or candidate.vectors:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CANDIDATE",
+            f"delta.candidates_by_record_id.{record_id}",
+            "must be an unsealed first-version spelling; version links and vectors are managed",
+        )
+    try:
+        # Capture one strict immutable spelling before comparing or classifying it. Nested
+        # contract subclasses may override ``to_dict``; retaining the caller's object after a
+        # successful comparison would let a later publication observe different facts.
+        captured = catalog_entry_from_dict(candidate.to_dict())
+        authored_formats = captured.data_formats if record.protocol == "sdmx" else None
+        expected = _candidate_from_record(
+            record,
+            entry_id=captured.entry_id,
+            authored_formats=authored_formats,
+            decided_rights=decided_rights,
+        )
+    except SourceContractError as error:
+        raise CatalogDeltaError(error.code, error.path, error.detail) from error
+    if captured.to_dict() != expected.to_dict():
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_RECORD_BINDING",
+            f"delta.candidates_by_record_id.{record_id}",
+            "authored candidate differs from the complete deterministic provider-fact projection",
+        )
+    return captured
+
+
+def _candidate_from_record(
+    record: HarvestedRecord,
+    *,
+    entry_id: str,
+    authored_formats: tuple[str, ...] | None = None,
+    decided_rights: RightsEvidence | None = None,
+) -> CatalogEntry:
+    """Derive every publishable v1 fact from the captured provider record.
+
+    The legacy v1 entry contract cannot represent unknown spatial and temporal facts directly.
+    Its closed sentinel values state only what this metadata harvest established; authored input
+    cannot replace them with source coverage, cadence, liveness, schema, or access claims.
+
+    ``decided_rights`` is the one authored substitution, and only for a record a human rights
+    decision cleared out of the queue: the provider stated no licence, so the rights facts are
+    the person's claim with the person's evidence, not a derivation from provider metadata.
+    Every other fact stays the deterministic projection.
+    """
+
+    data_formats = record.data_formats or authored_formats or ()
+    if not data_formats:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_RECORD_FORMATS",
+            f"delta.records.{record.record_id}.data_formats",
+            "the provider record declares no supported payload format",
+        )
+    if decided_rights is not None:
+        rights = decided_rights
+    else:
+        status, allowed_uses, obligation = _record_rights(record)
+        obligations: tuple[LicenseObligation, ...] = ()
+        if obligation == "attribution":
+            obligations = (
+                LicenseObligation(
+                    obligation_id="attribution",
+                    applies_at=("publication",),
+                    permitted_uses=allowed_uses,
+                    prohibited_uses=(),
+                    required_artifact_digests=(),
+                    escalation_when_ambiguous=True,
+                ),
+            )
+        rights = RightsEvidence(
+            status=status,
+            lawful_basis=record.license_id or "No recognized license declared",
+            allowed_uses=allowed_uses,
+            evidence=(record.evidence,),
+            obligations=obligations,
+        )
+    observed_time = record.declared_updated_at or record.evidence.observed_at
+    return CatalogEntry(
+        entry_id=entry_id,
+        entry_version=1,
+        publisher=record.publisher,
+        title=record.title,
+        description=record.description,
+        spatial_scope=("unspecified",),
+        data_formats=data_formats,
+        access_kind="open_catalog",
+        authentication_required=False,
+        observation=SourceObservation(
+            source_id=entry_id,
+            observed_at=record.evidence.observed_at,
+            event_time_field=None,
+            available_at_field=None,
+            historical_start=observed_time,
+            historical_end=observed_time,
+            live_status="not_applicable",
+            publication_delay_seconds=0,
+            update_frequency_seconds=0,
+            response_status=None,
+            evidence=(record.evidence,),
+        ),
+        rights=rights,
+        evidence=(record.evidence,),
+    )
+
+
+def _record_rights(record: HarvestedRecord) -> tuple[str, tuple[str, ...], str | None]:
+    if record.protocol == "ckan":
+        return ckan_licence_rights(record.license_id)
+    if record.protocol == "stac":
+        return stac_licence_rights(record.license_id)
+    return ("unclear", (), None)
+
+
+def _successor_changes(candidate: CatalogEntry) -> dict[str, object]:
+    return {
+        "publisher": candidate.publisher,
+        "title": candidate.title,
+        "description": candidate.description,
+        "spatial_scope": candidate.spatial_scope,
+        "data_formats": candidate.data_formats,
+        "access_kind": candidate.access_kind,
+        "authentication_required": candidate.authentication_required,
+        "observation": candidate.observation,
+        "rights": candidate.rights,
+        "quirks": candidate.quirks,
+        "declared_columns": candidate.declared_columns,
+        "declared_vocabulary": candidate.declared_vocabulary,
+        "declared_row_count": candidate.declared_row_count,
+        "evidence": candidate.evidence,
+    }
+
+
+def _classifiable_facts_digest(entry: CatalogEntry) -> str:
+    payload = entry.to_dict()
+    for managed in ("entry_version", "previous_digest", "vectors"):
+        del payload[managed]
+    return canonical_sha256(payload)
+
+
+def _classification_checkpoint_payload(
+    classification: CatalogDeltaClassification,
+    *,
+    lexical_coordinate: str,
+    neural_coordinate: str | None,
+) -> dict[str, Any]:
+    return {
+        "schema_version": "harness-source-catalog-delta-checkpoint.v1",
+        "classification_sha256": classification.digest,
+        "staging_sha256": classification.staging_sha256,
+        "predecessor_sha256": classification.predecessor_sha256,
+        "lexical_coordinate": lexical_coordinate,
+        "neural_coordinate": neural_coordinate,
+        "classification": {
+            "predecessor_sha256": classification.predecessor_sha256,
+            "rights_decisions_sha256": classification.rights_decisions_sha256,
+            "fill_receipt_sha256": classification.fill_receipt_sha256,
+            "staging_sha256": classification.staging_sha256,
+            "records_sha256": classification.records_sha256,
+            "unchanged": [entry.to_dict() for entry in classification.unchanged],
+            "changed": [entry.to_dict() for entry in classification.changed],
+            "new": [entry.to_dict() for entry in classification.new],
+            "absent": [item.to_dict() for item in classification.absent],
+            "flagged": [item.to_dict() for item in classification.flagged],
+            "version_chains": [
+                [entry.to_dict() for entry in chain] for chain in classification.version_chains
+            ],
+        },
+    }
+
+
+def _classification_from_checkpoint(value: Any) -> CatalogDeltaClassification:
+    exact = {
+        "predecessor_sha256",
+        "rights_decisions_sha256",
+        "fill_receipt_sha256",
+        "staging_sha256",
+        "records_sha256",
+        "unchanged",
+        "changed",
+        "new",
+        "absent",
+        "flagged",
+        "version_chains",
+    }
+    if not isinstance(value, dict) or set(value) != exact:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CHECKPOINT",
+            "delta.classification",
+            "serialized classification fields differ",
+        )
+    try:
+        unchanged = tuple(catalog_entry_from_dict(item) for item in value["unchanged"])
+        changed = tuple(catalog_entry_from_dict(item) for item in value["changed"])
+        new = tuple(catalog_entry_from_dict(item) for item in value["new"])
+        absent = tuple(CatalogAbsenceObservation(**item) for item in value["absent"])
+        flagged = tuple(CatalogFlaggedRecord(**item) for item in value["flagged"])
+        chains = tuple(
+            tuple(catalog_entry_from_dict(item) for item in chain)
+            for chain in value["version_chains"]
+        )
+        return CatalogDeltaClassification(
+            predecessor_sha256=value["predecessor_sha256"],
+            rights_decisions_sha256=value["rights_decisions_sha256"],
+            fill_receipt_sha256=value["fill_receipt_sha256"],
+            staging_sha256=value["staging_sha256"],
+            records_sha256=value["records_sha256"],
+            unchanged=unchanged,
+            changed=changed,
+            new=new,
+            absent=absent,
+            flagged=flagged,
+            version_chains=chains,
+        )
+    except (KeyError, TypeError, ValueError, SourceContractError) as error:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_CHECKPOINT",
+            "delta.classification",
+            "serialized classification is invalid",
+        ) from error
+
+
+def _entry_receipt(entry: CatalogEntry) -> dict[str, Any]:
+    return {
+        "coordinate": entry.coordinate,
+        "facts_sha256": entry.facts_digest,
+        "entry_sha256": entry.digest,
+        "vector_sha256s": [reference.vector_sha256 for reference in entry.vectors],
+    }
+
+
+def _entry_key(entry: CatalogEntry) -> tuple[str, int]:
+    return (entry.entry_id, entry.entry_version)
+
+
+def _record_from_dict(value: Any) -> HarvestedRecord:
+    if not isinstance(value, dict):
+        raise CatalogDeltaError("CATALOG_DELTA_STAGING", "delta.page.records[]", "must be object")
+    expected = {
+        "schema_version",
+        "protocol",
+        "record_id",
+        "title",
+        "description",
+        "publisher",
+        "landing_uri",
+        "data_formats",
+        "evidence",
+        "license_id",
+        "license_uri",
+        "declared_updated_at",
+    }
+    if set(value) != expected or not isinstance(value.get("data_formats"), list):
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_STAGING", "delta.page.records[]", "record fields differ"
+        )
+    return HarvestedRecord(
+        schema_version=value["schema_version"],
+        protocol=value["protocol"],
+        record_id=value["record_id"],
+        title=value["title"],
+        description=value["description"],
+        publisher=value["publisher"],
+        landing_uri=value["landing_uri"],
+        data_formats=tuple(value["data_formats"]),
+        evidence=_evidence_from_dict(value["evidence"], "delta.page.records[].evidence"),
+        license_id=value["license_id"],
+        license_uri=value["license_uri"],
+        declared_updated_at=value["declared_updated_at"],
+    )
+
+
+def _evidence_from_dict(value: Any, path: str) -> EvidenceReference:
+    if not isinstance(value, dict) or set(value) != {
+        "uri",
+        "observed_at",
+        "content_sha256",
+        "media_type",
+    }:
+        raise CatalogDeltaError("CATALOG_DELTA_STAGING", path, "evidence fields differ")
+    return EvidenceReference(
+        uri=value["uri"],
+        observed_at=value["observed_at"],
+        content_sha256=value["content_sha256"],
+        media_type=value["media_type"],
+    )
+
+
+def _flag_from_dict(value: Any) -> CatalogFlaggedRecord:
+    expected = {
+        "protocol",
+        "record_id",
+        "record_sha256",
+        "license_id",
+        "license_uri",
+        "rights_status",
+        "authority",
+    }
+    if not isinstance(value, dict) or set(value) != expected:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_STAGING", "delta.page.flagged_rights[]", "flag fields differ"
+        )
+    if value["authority"] != "human_review_required" or value["rights_status"] not in {
+        "unclear",
+        "prohibited",
+    }:
+        raise CatalogDeltaError(
+            "CATALOG_DELTA_RIGHTS",
+            "delta.page.flagged_rights[]",
+            "flag must require human review for unclear or prohibited rights",
+        )
+    return CatalogFlaggedRecord(
+        protocol=value["protocol"],
+        record_id=value["record_id"],
+        record_sha256=value["record_sha256"],
+        license_id=value["license_id"],
+        license_uri=value["license_uri"],
+        rights_status=value["rights_status"],
+    )