mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/cadence.py

@@ -0,0 +1,1428 @@
+"""Canonical empirical source observations and deterministic cadence inference.
+
+The existing :class:`SourceObservation` records researched/catalogue fitness.  This module owns a
+different fact: what one governed connector actually observed over repeated headless probes.  The
+two contracts deliberately have different names and schema coordinates.
+
+Inference consumes only the exact digest-bound ordered history passed by the caller. This module
+does not grant that history authority; the future Studio consumer must authenticate who recorded
+each observation before persisting it. The pure calculation never reads a clock, network,
+environment variable, mutable file, or model service, so every consumer can replay the same
+history and compare its result with the packaged golden vectors.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from hashlib import sha256
+from itertools import pairwise
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness import canonical as canonical_contract
+from mostlyright.data_harness.canonical import canonical_sha256
+
+SOURCE_CADENCE_OBSERVATION_SCHEMA = "harness-empirical-source-observation.v1"
+SOURCE_CADENCE_INFERENCE_SCHEMA = "harness-source-cadence-inference.v1"
+SOURCE_CADENCE_ALGORITHM_VERSION = "source-cadence.v1"
+_IMPLEMENTATION_SOURCE_SHA256 = sha256(Path(__file__).read_bytes()).hexdigest()
+_CANONICAL_SOURCE_SHA256 = sha256(Path(canonical_contract.__file__).read_bytes()).hexdigest()
+_FAILURE_CODE_VALUES = (
+    "contract_refused",
+    "http_4xx",
+    "http_5xx",
+    "rate_limited",
+    "reader_failure",
+    "source_unavailable",
+    "timeout",
+    "tls_failure",
+    "transport_failure",
+    "unknown_failure",
+)
+_SOURCE_CADENCE_ALGORITHM_SPEC: dict[str, object] = {
+    "version": SOURCE_CADENCE_ALGORITHM_VERSION,
+    "implementation_source_sha256": _IMPLEMENTATION_SOURCE_SHA256,
+    "canonicalization_source_sha256": _CANONICAL_SOURCE_SHA256,
+    "integer_arithmetic": {
+        "time_delta_seconds": "exact_utc_timestamp_difference_as_integer_seconds",
+        "per_edition_interval": "delta_seconds_floor_divided_by_positive_edition_delta",
+        "basis_points": "integer_multiply_then_floor_divide_by_10000",
+        "median": "sorted_middle_or_floor_of_two_middle_sum_divided_by_two",
+    },
+    "history": {
+        "maximum_observations": 4_096,
+        "maximum_partitions_per_observation": 128,
+        "maximum_partitions_per_history": 8_192,
+        "identity": [
+            "source",
+            "epoch",
+            "connector_configuration",
+            "locator",
+            "recipe",
+            "source_authority",
+            "reader_coordinate",
+            "reader_options",
+            "frontier_policy",
+            "time_interpretation",
+            "algorithm",
+            "acquired_frontier_kind_and_derivation",
+            "publication_coordinate_presence",
+        ],
+        "ordering": "contiguous_sequence_predecessor_digest_nonoverlapping_probe_time",
+        "material_order": "strict_publication_reference_and_edition_sequence_when_present",
+    },
+    "result_shapes": {
+        "changed": "complete_acquired_evidence_and_optional_complete_publication_coordinate",
+        "unchanged_acquired": "complete_acquired_evidence_equal_to_prior_acquired_facts",
+        "unchanged_no_body": "http_304_conditional_request_and_probe_receipt_no_parsed_facts",
+        "not_published": "probe_receipt_and_status_none_or_200_202_204_404_no_data_facts",
+        "failed": {
+            "shape": "closed_failure_code_and_probe_receipt_no_data_facts",
+            "failure_codes": list(_FAILURE_CODE_VALUES),
+        },
+    },
+    "interval": {
+        "source": "publication_reference_time_divided_by_edition_sequence_delta",
+        "minimum_changed_observations": 4,
+        "median": "sorted_integer_midpoint_floor",
+        "jitter": "maximum_absolute_distance_from_median_interval",
+        "regular_jitter_floor_seconds": 3_600,
+        "regular_jitter_basis_points": 2_000,
+        "regime_minimum_intervals": 5,
+        "regime_recent_intervals": 2,
+        "regime_change_basis_points": 4_000,
+        "regime_recent_consistency_basis_points": 2_000,
+    },
+    "dormancy": {
+        "elapsed_interval_multiplier": 4,
+        "minimum_successful_no_change_observations": 3,
+        "failures_disqualify_trailing_evidence": True,
+    },
+    "expected_window": {
+        "center": "last_publication_reference_plus_interval",
+        "minimum_margin_seconds": 300,
+        "interval_margin_basis_points": 500,
+        "include_only_if_latest_observation_not_after_window": True,
+    },
+    "confidence": {
+        "learning_per_change_basis_points": 1_000,
+        "learning_maximum_basis_points": 4_000,
+        "stable_base_basis_points": 6_000,
+        "stable_extra_interval_basis_points": 500,
+        "stable_maximum_basis_points": 9_500,
+        "dormant_base_basis_points": 5_000,
+        "dormant_per_interval_basis_points": 300,
+        "dormant_maximum_basis_points": 8_000,
+        "changed_pattern_basis_points": 2_500,
+        "failure_penalty_each_basis_points": 500,
+        "failure_penalty_maximum_basis_points": 3_000,
+    },
+    "probe_recommendation": {
+        "stable_divisor": 8,
+        "stable_maximum_seconds": 21_600,
+        "dormant_minimum_seconds": 86_400,
+        "dormant_maximum_seconds": 604_800,
+        "unstable_divisor": 4,
+        "unstable_minimum_seconds": 900,
+        "unstable_maximum_seconds": 86_400,
+        "unknown_seconds": 21_600,
+        "epoch_reset_maximum_seconds": 3_600,
+        "absolute_minimum_seconds": 300,
+        "absolute_maximum_seconds": 2_592_000,
+    },
+    "revision": {
+        "historical_revision": "changed_content_without_frontier_advance",
+        "replacement": "row_count_falls_or_prior_partition_missing_or_rewritten",
+        "append": "all_prior_partitions_unchanged_and_at_least_one_new_partition",
+        "fallback": "unknown",
+    },
+    "publication_delay": "observation_completion_minus_publication_reference_integer_seconds",
+    "evaluation_time": "last_observation_completed_at",
+    "state_precedence": [
+        "learning_until_four_coordinate_complete_material_changes",
+        "stable_if_jitter_within_threshold_else_changed_pattern_irregular",
+        "regime_change_overrides_regular_or_irregular_to_changed_pattern_and_epoch_reset",
+        "dormancy_overrides_stable_only_with_trailing_successful_no_change_evidence",
+        "missed_expected_window_overrides_remaining_stable_to_changed_pattern_regular",
+        "failure_penalty_and_reason_apply_after_state_selection",
+    ],
+    "output_formulas": {
+        "interval_jitter_seconds": "max_abs_each_interval_minus_median",
+        "publication_delay_summary": "minimum_floor_median_maximum",
+        "expected_window_margin": "max_300_interval_floor_div_20_jitter",
+        "confidence": "state_base_plus_interval_increment_then_failure_penalty_clamped_at_zero",
+        "evidence_range": "first_started_at_through_last_completed_at",
+        "history_digest": "canonical_sha256_of_exact_observation_documents_in_order",
+        "reason_order": "pattern_then_regime_then_dormancy_or_missed_window_then_failures",
+        "revision_precedence": (
+            "historical_revision_then_replacement_then_all_transitions_append_else_unknown"
+        ),
+    },
+    "reason_codes": [
+        "no_observations",
+        "missing_publication_coordinates",
+        "insufficient_changes",
+        "regular_intervals",
+        "irregular_intervals",
+        "cadence_regime_changed",
+        "publication_window_missed",
+        "prolonged_no_change",
+        "probe_failures_observed",
+    ],
+}
+SOURCE_CADENCE_ALGORITHM_DIGEST = canonical_sha256(_SOURCE_CADENCE_ALGORITHM_SPEC)
+
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+_READER_IDENTIFIER = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+_SEMVER = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$")
+_TIMESTAMP = re.compile(
+    r"^(?P<date>[0-9]{4}-[0-9]{2}-[0-9]{2})T"
+    r"(?P<time>[0-9]{2}:[0-9]{2}:[0-9]{2})(?P<fraction>\.[0-9]{1,6})?Z$"
+)
+_HTTP_STATUS_CLASSES = frozenset({"none", "2xx", "3xx", "4xx", "5xx"})
+_RESULT_KINDS = frozenset({"changed", "unchanged", "not_published", "failed"})
+_FRONTIER_KINDS = frozenset({"none", "date", "timestamp", "integer", "opaque"})
+_INFERENCE_STATES = frozenset({"unknown", "learning", "stable", "changed_pattern", "dormant"})
+_CADENCE_KINDS = frozenset({"unknown", "regular", "irregular"})
+_REVISION_STYLES = frozenset({"unknown", "append", "replacement", "historical_revision"})
+_FAILURE_CODES = frozenset(_FAILURE_CODE_VALUES)
+
+
+class CadenceContractError(ValueError):
+    """Typed refusal raised by observation, history, or inference validation."""
+
+    def __init__(self, code: str, path: str, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{path}: {detail} [{code}]")
+
+
+def source_cadence_algorithm_spec() -> dict[str, object]:
+    """Return an isolated copy of the complete normative algorithm manifest."""
+
+    return deepcopy(_SOURCE_CADENCE_ALGORITHM_SPEC)
+
+
+def _refuse(code: str, path: str, detail: str) -> None:
+    raise CadenceContractError(code, path, detail)
+
+
+def _digest(value: object, path: str, *, optional: bool = False) -> None:
+    if value is None and optional:
+        return
+    if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+        _refuse("DIGEST", path, "must be a lowercase SHA-256 digest")
+
+
+def _identifier(value: object, path: str) -> None:
+    if not isinstance(value, str) or _IDENTIFIER.fullmatch(value) is None:
+        _refuse("IDENTIFIER", path, "must be a bounded source identifier")
+
+
+def _reader_identifier(value: object, path: str) -> None:
+    if not isinstance(value, str) or len(value) > 64 or _READER_IDENTIFIER.fullmatch(value) is None:
+        _refuse("IDENTIFIER", path, "must be a canonical Reader identifier")
+
+
+def _timestamp(value: object, path: str) -> datetime:
+    if not isinstance(value, str) or _TIMESTAMP.fullmatch(value) is None:
+        _refuse("TIMESTAMP", path, "must be a canonical UTC timestamp ending in Z")
+    try:
+        parsed = datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError:
+        _refuse("TIMESTAMP", path, "must be a real calendar timestamp")
+    parsed = parsed.astimezone(UTC)
+    if _format_timestamp(parsed) != value:
+        _refuse("TIMESTAMP", path, "must use the one canonical UTC spelling")
+    return parsed
+
+
+def _format_timestamp(value: datetime) -> str:
+    value = value.astimezone(UTC)
+    if value.microsecond:
+        return value.isoformat(timespec="microseconds").replace("+00:00", "Z")
+    return value.isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _bounded_text(value: object, path: str, *, maximum: int) -> None:
+    if not isinstance(value, str) or not 1 <= len(value) <= maximum or value != value.strip():
+        _refuse("TEXT", path, f"must be stripped text of 1..{maximum} characters")
+    if any(
+        not character.isprintable() or unicodedata.category(character) in {"Zl", "Zp"}
+        for character in value
+    ):
+        _refuse("TEXT", path, "must contain only display-safe characters")
+
+
+def _exact(value: Mapping[str, Any], expected: set[str], path: str) -> None:
+    if set(value) != expected:
+        _refuse("EXACT_KEYS", path, "does not have the exact versioned key set")
+
+
+def _optional_int(value: object, path: str, *, minimum: int, maximum: int) -> None:
+    if value is None:
+        return
+    if type(value) is not int or not minimum <= value <= maximum:
+        _refuse("INTEGER", path, f"must be null or an integer in {minimum}..{maximum}")
+
+
+def _safe_shift(value: datetime, seconds: int, path: str) -> datetime:
+    try:
+        return value + timedelta(seconds=seconds)
+    except OverflowError:
+        _refuse("TIMESTAMP_RANGE", path, "cannot represent the inferred time")
+
+
+def _elapsed_whole_seconds(earlier: datetime, later: datetime) -> int:
+    """Return exact floor whole seconds without floating-point conversion."""
+
+    delta = later - earlier
+    return delta.days * 86_400 + delta.seconds
+
+
+@dataclass(frozen=True)
+class SourceFrontier:
+    """One approved, typed source frontier and its public derivation rule."""
+
+    kind: str
+    value: str | None
+    derivation_rule: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.kind, str) or self.kind not in _FRONTIER_KINDS:
+            _refuse("FRONTIER_KIND", "frontier.kind", "is not a supported frontier kind")
+        _bounded_text(self.derivation_rule, "frontier.derivation_rule", maximum=128)
+        if self.kind == "none":
+            if self.value is not None:
+                _refuse("FRONTIER_VALUE", "frontier.value", "must be null for kind none")
+            return
+        _bounded_text(self.value, "frontier.value", maximum=256)
+        if self.kind == "date":
+            try:
+                parsed_date = datetime.strptime(self.value, "%Y-%m-%d")
+            except ValueError:
+                _refuse("FRONTIER_VALUE", "frontier.value", "must be a real ISO date")
+            if parsed_date.strftime("%Y-%m-%d") != self.value:
+                _refuse("FRONTIER_VALUE", "frontier.value", "must use canonical ISO spelling")
+        elif self.kind == "timestamp":
+            _timestamp(self.value, "frontier.value")
+        elif self.kind == "integer":
+            if not re.fullmatch(r"0|[1-9][0-9]{0,18}", self.value):
+                _refuse("FRONTIER_VALUE", "frontier.value", "must be a canonical unsigned integer")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"kind": self.kind, "value": self.value, "derivation_rule": self.derivation_rule}
+
+
+@dataclass(frozen=True)
+class PartitionDigest:
+    """Credential-free identity and content digest for one approved source partition."""
+
+    partition_key_digest: str
+    content_digest: str
+
+    def __post_init__(self) -> None:
+        _digest(self.partition_key_digest, "partition.partition_key_digest")
+        _digest(self.content_digest, "partition.content_digest")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "partition_key_digest": self.partition_key_digest,
+            "content_digest": self.content_digest,
+        }
+
+
+@dataclass(frozen=True)
+class EmpiricalSourceObservation:
+    """Immutable result of one bounded connector probe or acquisition."""
+
+    source_id: str
+    sequence: int
+    inference_epoch: str
+    previous_observation_digest: str | None
+    connector_configuration_digest: str
+    locator_digest: str
+    recipe_digest: str
+    source_authority_digest: str
+    reader_family_id: str
+    reader_family_version: str
+    reader_options_digest: str
+    frontier_policy_digest: str
+    time_interpretation_digest: str
+    inference_algorithm_digest: str
+    started_at: str
+    completed_at: str
+    result_kind: str
+    failure_code: str | None
+    http_status_class: str
+    http_status_code: int | None
+    conditional_request_digest: str | None
+    probe_receipt_digest: str
+    etag_digest: str | None
+    last_modified_digest: str | None
+    acquired_size_bytes: int | None
+    content_digest: str | None
+    row_digest: str | None
+    schema_digest: str | None
+    row_count: int | None
+    frontier: SourceFrontier
+    max_event_time: str | None
+    partition_digests: tuple[PartitionDigest, ...]
+    acquisition_receipt_digest: str | None
+    next_watermark_candidate_digest: str | None
+    publication_reference_time: str | None
+    edition_sequence: int | None
+    schema_version: str = SOURCE_CADENCE_OBSERVATION_SCHEMA
+
+    def __post_init__(self) -> None:
+        if self.schema_version != SOURCE_CADENCE_OBSERVATION_SCHEMA:
+            _refuse("SCHEMA_VERSION", "observation.schema_version", "is not supported")
+        _identifier(self.source_id, "observation.source_id")
+        if type(self.sequence) is not int or not 0 <= self.sequence <= (1 << 53) - 1:
+            _refuse("SEQUENCE", "observation.sequence", "must be a non-negative safe integer")
+        _identifier(self.inference_epoch, "observation.inference_epoch")
+        _digest(
+            self.previous_observation_digest,
+            "observation.previous_observation_digest",
+            optional=True,
+        )
+        if (self.sequence == 0) != (self.previous_observation_digest is None):
+            _refuse(
+                "PREDECESSOR",
+                "observation.previous_observation_digest",
+                "must be null exactly for sequence zero",
+            )
+        for name, value in (
+            ("connector_configuration_digest", self.connector_configuration_digest),
+            ("locator_digest", self.locator_digest),
+            ("recipe_digest", self.recipe_digest),
+            ("source_authority_digest", self.source_authority_digest),
+            ("reader_options_digest", self.reader_options_digest),
+            ("frontier_policy_digest", self.frontier_policy_digest),
+            ("time_interpretation_digest", self.time_interpretation_digest),
+            ("inference_algorithm_digest", self.inference_algorithm_digest),
+            ("probe_receipt_digest", self.probe_receipt_digest),
+        ):
+            _digest(value, f"observation.{name}")
+        _reader_identifier(self.reader_family_id, "observation.reader_family_id")
+        if (
+            not isinstance(self.reader_family_version, str)
+            or len(self.reader_family_version) > 32
+            or _SEMVER.fullmatch(self.reader_family_version) is None
+        ):
+            _refuse("SEMVER", "observation.reader_family_version", "must be x.y.z")
+        started = _timestamp(self.started_at, "observation.started_at")
+        completed = _timestamp(self.completed_at, "observation.completed_at")
+        if completed < started:
+            _refuse("TEMPORAL_ORDER", "observation.completed_at", "precedes started_at")
+        if not isinstance(self.result_kind, str) or self.result_kind not in _RESULT_KINDS:
+            _refuse("RESULT_KIND", "observation.result_kind", "is not supported")
+        if (
+            not isinstance(self.http_status_class, str)
+            or self.http_status_class not in _HTTP_STATUS_CLASSES
+        ):
+            _refuse("HTTP_STATUS_CLASS", "observation.http_status_class", "is not supported")
+        _optional_int(
+            self.http_status_code,
+            "observation.http_status_code",
+            minimum=100,
+            maximum=599,
+        )
+        if self.http_status_class == "none":
+            if self.http_status_code is not None:
+                _refuse("HTTP_STATUS", "observation.http_status_code", "must be null")
+        elif (
+            self.http_status_code is None
+            or f"{self.http_status_code // 100}xx" != self.http_status_class
+        ):
+            _refuse("HTTP_STATUS", "observation.http_status_code", "does not match its class")
+        for name, value in (
+            ("conditional_request_digest", self.conditional_request_digest),
+            ("etag_digest", self.etag_digest),
+            ("last_modified_digest", self.last_modified_digest),
+            ("content_digest", self.content_digest),
+            ("row_digest", self.row_digest),
+            ("schema_digest", self.schema_digest),
+            ("acquisition_receipt_digest", self.acquisition_receipt_digest),
+            ("next_watermark_candidate_digest", self.next_watermark_candidate_digest),
+        ):
+            _digest(value, f"observation.{name}", optional=True)
+        _optional_int(
+            self.acquired_size_bytes,
+            "observation.acquired_size_bytes",
+            minimum=0,
+            maximum=1 << 40,
+        )
+        _optional_int(self.row_count, "observation.row_count", minimum=0, maximum=1_000_000_000)
+        _optional_int(
+            self.edition_sequence,
+            "observation.edition_sequence",
+            minimum=0,
+            maximum=(1 << 53) - 1,
+        )
+        if self.publication_reference_time is not None:
+            publication_reference = _timestamp(
+                self.publication_reference_time,
+                "observation.publication_reference_time",
+            )
+            if publication_reference > completed:
+                _refuse(
+                    "PUBLICATION_TIME",
+                    "observation.publication_reference_time",
+                    "follows observation completion",
+                )
+        if (self.publication_reference_time is None) != (self.edition_sequence is None):
+            _refuse(
+                "PUBLICATION_COORDINATE",
+                "observation",
+                "publication time and edition sequence must appear together",
+            )
+        if not isinstance(self.frontier, SourceFrontier):
+            _refuse("TYPE", "observation.frontier", "must be a SourceFrontier")
+        if self.max_event_time is not None:
+            _timestamp(self.max_event_time, "observation.max_event_time")
+        if not isinstance(self.partition_digests, tuple) or len(self.partition_digests) > 128:
+            _refuse("PARTITIONS", "observation.partition_digests", "must be a bounded tuple")
+        if any(not isinstance(item, PartitionDigest) for item in self.partition_digests):
+            _refuse("PARTITIONS", "observation.partition_digests", "contains an invalid item")
+        keys = tuple(item.partition_key_digest for item in self.partition_digests)
+        if keys != tuple(sorted(keys)) or len(keys) != len(set(keys)):
+            _refuse(
+                "PARTITIONS",
+                "observation.partition_digests",
+                "must be unique and sorted by partition_key_digest",
+            )
+        acquired = (
+            self.acquired_size_bytes,
+            self.content_digest,
+            self.row_digest,
+            self.schema_digest,
+            self.row_count,
+            self.acquisition_receipt_digest,
+        )
+        if self.result_kind == "changed":
+            if self.failure_code is not None or any(value is None for value in acquired):
+                _refuse(
+                    "RESULT_SHAPE",
+                    "observation",
+                    "changed requires complete acquired evidence",
+                )
+            if self.http_status_class not in {"none", "2xx"}:
+                _refuse("RESULT_STATUS", "observation", "changed requires a successful result")
+            if self.probe_receipt_digest != self.acquisition_receipt_digest:
+                _refuse(
+                    "RESULT_SHAPE",
+                    "observation.probe_receipt_digest",
+                    "must be the acquired Receipt digest",
+                )
+        elif self.result_kind == "unchanged":
+            no_acquired_evidence = all(value is None for value in acquired)
+            complete_acquired_evidence = all(value is not None for value in acquired)
+            if self.failure_code is not None or not (
+                no_acquired_evidence or complete_acquired_evidence
+            ):
+                _refuse(
+                    "RESULT_SHAPE",
+                    "observation",
+                    "unchanged requires complete evidence or a conditional no-body result",
+                )
+            if no_acquired_evidence and self.next_watermark_candidate_digest is not None:
+                _refuse(
+                    "RESULT_SHAPE",
+                    "observation.next_watermark_candidate_digest",
+                    "cannot advance without acquired evidence",
+                )
+            if no_acquired_evidence:
+                if (
+                    self.http_status_code != 304
+                    or self.conditional_request_digest is None
+                    or self.frontier.kind != "none"
+                    or self.max_event_time is not None
+                    or self.partition_digests
+                    or self.publication_reference_time is not None
+                ):
+                    _refuse(
+                        "RESULT_SHAPE",
+                        "observation",
+                        "no-body unchanged requires a conditional 304 with no parsed facts",
+                    )
+            else:
+                if self.http_status_class not in {"none", "2xx"}:
+                    _refuse(
+                        "RESULT_STATUS",
+                        "observation",
+                        "acquired unchanged requires a successful result",
+                    )
+                if self.probe_receipt_digest != self.acquisition_receipt_digest:
+                    _refuse(
+                        "RESULT_SHAPE",
+                        "observation.probe_receipt_digest",
+                        "must be the acquired Receipt digest",
+                    )
+        elif self.result_kind in {"not_published", "failed"}:
+            if any(value is not None for value in acquired) or self.frontier.kind != "none":
+                _refuse("RESULT_SHAPE", "observation", "result cannot claim acquired evidence")
+            if self.next_watermark_candidate_digest is not None:
+                _refuse(
+                    "RESULT_SHAPE",
+                    "observation.next_watermark_candidate_digest",
+                    "cannot advance without acquired evidence",
+                )
+            if self.partition_digests or self.max_event_time is not None:
+                _refuse("RESULT_SHAPE", "observation", "result cannot claim parsed evidence")
+            if self.publication_reference_time is not None:
+                _refuse("RESULT_SHAPE", "observation", "result cannot claim a publication")
+        if self.result_kind == "not_published" and self.http_status_code not in {
+            None,
+            200,
+            202,
+            204,
+            404,
+        }:
+            _refuse(
+                "RESULT_STATUS",
+                "observation.http_status_code",
+                "is not a successful not-published outcome",
+            )
+        if self.result_kind == "failed":
+            if not isinstance(self.failure_code, str) or self.failure_code not in _FAILURE_CODES:
+                _refuse("FAILURE_CODE", "observation.failure_code", "is not supported")
+        elif self.failure_code is not None:
+            _refuse("RESULT_SHAPE", "observation.failure_code", "must be null unless failed")
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "source_id": self.source_id,
+            "sequence": self.sequence,
+            "inference_epoch": self.inference_epoch,
+            "previous_observation_digest": self.previous_observation_digest,
+            "connector_configuration_digest": self.connector_configuration_digest,
+            "locator_digest": self.locator_digest,
+            "recipe_digest": self.recipe_digest,
+            "source_authority_digest": self.source_authority_digest,
+            "reader_family_id": self.reader_family_id,
+            "reader_family_version": self.reader_family_version,
+            "reader_options_digest": self.reader_options_digest,
+            "frontier_policy_digest": self.frontier_policy_digest,
+            "time_interpretation_digest": self.time_interpretation_digest,
+            "inference_algorithm_digest": self.inference_algorithm_digest,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "result_kind": self.result_kind,
+            "failure_code": self.failure_code,
+            "http_status_class": self.http_status_class,
+            "http_status_code": self.http_status_code,
+            "conditional_request_digest": self.conditional_request_digest,
+            "probe_receipt_digest": self.probe_receipt_digest,
+            "etag_digest": self.etag_digest,
+            "last_modified_digest": self.last_modified_digest,
+            "acquired_size_bytes": self.acquired_size_bytes,
+            "content_digest": self.content_digest,
+            "row_digest": self.row_digest,
+            "schema_digest": self.schema_digest,
+            "row_count": self.row_count,
+            "frontier": self.frontier.to_dict(),
+            "max_event_time": self.max_event_time,
+            "partition_digests": [item.to_dict() for item in self.partition_digests],
+            "acquisition_receipt_digest": self.acquisition_receipt_digest,
+            "next_watermark_candidate_digest": self.next_watermark_candidate_digest,
+            "publication_reference_time": self.publication_reference_time,
+            "edition_sequence": self.edition_sequence,
+        }
+
+
+@dataclass(frozen=True)
+class CadenceInference:
+    """Pure replay result for one exact empirical observation history."""
+
+    source_id: str
+    inference_epoch: str
+    history_digest: str
+    state: str
+    cadence_kind: str
+    estimated_interval_seconds: int | None
+    interval_jitter_seconds: int | None
+    publication_delay_min_seconds: int | None
+    publication_delay_median_seconds: int | None
+    publication_delay_max_seconds: int | None
+    expected_next_earliest: str | None
+    expected_next_latest: str | None
+    confidence_basis_points: int
+    evidence_count: int
+    evidence_started_at: str | None
+    evidence_completed_at: str | None
+    recommended_probe_interval_seconds: int
+    revision_style: str
+    recommended_epoch_reset: bool
+    reason_codes: tuple[str, ...]
+    algorithm_version: str = SOURCE_CADENCE_ALGORITHM_VERSION
+    algorithm_digest: str = SOURCE_CADENCE_ALGORITHM_DIGEST
+    schema_version: str = SOURCE_CADENCE_INFERENCE_SCHEMA
+
+    def __post_init__(self) -> None:
+        if self.schema_version != SOURCE_CADENCE_INFERENCE_SCHEMA:
+            _refuse("SCHEMA_VERSION", "inference.schema_version", "is not supported")
+        if (
+            self.algorithm_version != SOURCE_CADENCE_ALGORITHM_VERSION
+            or self.algorithm_digest != SOURCE_CADENCE_ALGORITHM_DIGEST
+        ):
+            _refuse("ALGORITHM", "inference.algorithm_version", "is not the exact algorithm")
+        _identifier(self.source_id, "inference.source_id")
+        _identifier(self.inference_epoch, "inference.inference_epoch")
+        _digest(self.history_digest, "inference.history_digest")
+        if (
+            not isinstance(self.state, str)
+            or self.state not in _INFERENCE_STATES
+            or not isinstance(self.cadence_kind, str)
+            or self.cadence_kind not in _CADENCE_KINDS
+        ):
+            _refuse("INFERENCE_STATE", "inference.state", "is not supported")
+        allowed_cadence = {
+            "unknown": {"unknown"},
+            "learning": {"unknown"},
+            "stable": {"regular"},
+            "dormant": {"regular"},
+            "changed_pattern": {"regular", "irregular"},
+        }
+        if self.cadence_kind not in allowed_cadence[self.state]:
+            _refuse("INFERENCE_STATE", "inference.cadence_kind", "contradicts the state")
+        if not isinstance(self.revision_style, str) or self.revision_style not in _REVISION_STYLES:
+            _refuse("REVISION_STYLE", "inference.revision_style", "is not supported")
+        _optional_int(
+            self.estimated_interval_seconds,
+            "inference.estimated_interval_seconds",
+            minimum=1,
+            maximum=1 << 40,
+        )
+        for name, value in (
+            ("interval_jitter_seconds", self.interval_jitter_seconds),
+            ("publication_delay_min_seconds", self.publication_delay_min_seconds),
+            ("publication_delay_median_seconds", self.publication_delay_median_seconds),
+            ("publication_delay_max_seconds", self.publication_delay_max_seconds),
+        ):
+            _optional_int(value, f"inference.{name}", minimum=0, maximum=1 << 40)
+        if self.cadence_kind == "regular" and self.estimated_interval_seconds is None:
+            _refuse("INFERENCE_STATE", "inference.estimated_interval_seconds", "is required")
+        if self.cadence_kind == "irregular" and self.estimated_interval_seconds is not None:
+            _refuse("INFERENCE_STATE", "inference.estimated_interval_seconds", "must be null")
+        delays = (
+            self.publication_delay_min_seconds,
+            self.publication_delay_median_seconds,
+            self.publication_delay_max_seconds,
+        )
+        if any(value is None for value in delays) and not all(value is None for value in delays):
+            _refuse("PUBLICATION_DELAY", "inference", "delay values must appear together")
+        if all(value is not None for value in delays):
+            delay_min, delay_median, delay_max = delays
+            assert delay_min is not None and delay_median is not None and delay_max is not None
+            if not delay_min <= delay_median <= delay_max:
+                _refuse("PUBLICATION_DELAY", "inference", "delay values are out of order")
+        for name, value in (
+            ("expected_next_earliest", self.expected_next_earliest),
+            ("expected_next_latest", self.expected_next_latest),
+            ("evidence_started_at", self.evidence_started_at),
+            ("evidence_completed_at", self.evidence_completed_at),
+        ):
+            if value is not None:
+                _timestamp(value, f"inference.{name}")
+        if (self.expected_next_earliest is None) != (self.expected_next_latest is None):
+            _refuse(
+                "EXPECTED_WINDOW",
+                "inference",
+                "expected window endpoints must appear together",
+            )
+        if self.expected_next_earliest is not None and _timestamp(
+            self.expected_next_latest, "inference.expected_next_latest"
+        ) < _timestamp(self.expected_next_earliest, "inference.expected_next_earliest"):
+            _refuse("EXPECTED_WINDOW", "inference.expected_next_latest", "precedes earliest")
+        if self.expected_next_earliest is not None and self.state != "stable":
+            _refuse("EXPECTED_WINDOW", "inference", "is available only for stable cadence")
+        if (
+            type(self.confidence_basis_points) is not int
+            or not 0 <= self.confidence_basis_points <= 10_000
+        ):
+            _refuse("CONFIDENCE", "inference.confidence_basis_points", "must be 0..10000")
+        if type(self.evidence_count) is not int or not 0 <= self.evidence_count <= 4_096:
+            _refuse("EVIDENCE_COUNT", "inference.evidence_count", "must be 0..4096")
+        if (self.evidence_count == 0) != (self.evidence_started_at is None):
+            _refuse("EVIDENCE_COUNT", "inference.evidence_started_at", "does not match the count")
+        if (self.evidence_count == 0) != (self.evidence_completed_at is None):
+            _refuse("EVIDENCE_COUNT", "inference.evidence_completed_at", "does not match the count")
+        if self.state == "unknown" and self.evidence_count != 0:
+            _refuse("EVIDENCE_COUNT", "inference.evidence_count", "contradicts unknown state")
+        if self.state != "unknown" and self.evidence_count == 0:
+            _refuse("EVIDENCE_COUNT", "inference.evidence_count", "contradicts observed state")
+        if self.evidence_started_at is not None and _timestamp(
+            self.evidence_completed_at,
+            "inference.evidence_completed_at",
+        ) < _timestamp(self.evidence_started_at, "inference.evidence_started_at"):
+            _refuse("EVIDENCE_TIME", "inference.evidence_completed_at", "precedes start")
+        if (
+            type(self.recommended_probe_interval_seconds) is not int
+            or not 300 <= self.recommended_probe_interval_seconds <= 30 * 24 * 60 * 60
+        ):
+            _refuse(
+                "PROBE_INTERVAL",
+                "inference.recommended_probe_interval_seconds",
+                "is out of bounds",
+            )
+        if not isinstance(self.recommended_epoch_reset, bool):
+            _refuse("TYPE", "inference.recommended_epoch_reset", "must be boolean")
+        if self.recommended_epoch_reset and self.state != "changed_pattern":
+            _refuse("INFERENCE_STATE", "inference.recommended_epoch_reset", "contradicts state")
+        if (
+            not isinstance(self.reason_codes, tuple)
+            or not 1 <= len(self.reason_codes) <= 32
+            or any(
+                not isinstance(item, str)
+                or len(item) > 64
+                or _READER_IDENTIFIER.fullmatch(item) is None
+                for item in self.reason_codes
+            )
+            or len(set(self.reason_codes)) != len(self.reason_codes)
+        ):
+            _refuse("REASON_CODES", "inference.reason_codes", "must be unique typed codes")
+        reason_set = set(self.reason_codes)
+        reason_order = tuple(_SOURCE_CADENCE_ALGORITHM_SPEC["reason_codes"])
+        supported_reasons = set(reason_order)
+        if not reason_set <= supported_reasons:
+            _refuse("REASON_CODES", "inference.reason_codes", "contains an unsupported code")
+        if self.reason_codes != tuple(item for item in reason_order if item in reason_set):
+            _refuse("REASON_CODES", "inference.reason_codes", "is not in canonical order")
+        if self.state == "unknown":
+            if (
+                self.source_id != "unknown"
+                or self.inference_epoch != "unknown"
+                or self.history_digest != canonical_sha256([])
+                or self.estimated_interval_seconds is not None
+                or self.interval_jitter_seconds is not None
+                or any(value is not None for value in delays)
+                or self.expected_next_earliest is not None
+                or self.confidence_basis_points != 0
+                or self.revision_style != "unknown"
+                or self.recommended_epoch_reset
+                or self.reason_codes != ("no_observations",)
+                or self.recommended_probe_interval_seconds != 21_600
+            ):
+                _refuse("INFERENCE_STATE", "inference", "is not the canonical unknown result")
+        elif self.state == "learning":
+            if (
+                "insufficient_changes" not in reason_set
+                or not reason_set
+                <= {
+                    "missing_publication_coordinates",
+                    "insufficient_changes",
+                    "probe_failures_observed",
+                }
+                or self.expected_next_earliest is not None
+                or self.recommended_epoch_reset
+            ):
+                _refuse("INFERENCE_STATE", "inference.reason_codes", "contradicts learning state")
+        elif self.state == "stable":
+            if (
+                "regular_intervals" not in reason_set
+                or not reason_set <= {"regular_intervals", "probe_failures_observed"}
+                or self.expected_next_earliest is None
+                or self.confidence_basis_points < 3_000
+                or self.recommended_epoch_reset
+            ):
+                _refuse("INFERENCE_STATE", "inference.reason_codes", "contradicts stable state")
+        elif self.state == "dormant":
+            if (
+                not {"regular_intervals", "prolonged_no_change"} <= reason_set
+                or not reason_set
+                <= {"regular_intervals", "prolonged_no_change", "probe_failures_observed"}
+                or self.expected_next_earliest is not None
+                or self.confidence_basis_points < 2_900
+                or self.recommended_epoch_reset
+            ):
+                _refuse("INFERENCE_STATE", "inference.reason_codes", "contradicts dormant state")
+        elif self.cadence_kind == "irregular":
+            base_reasons = reason_set & {"regular_intervals", "irregular_intervals"}
+            allowed = {
+                "regular_intervals",
+                "irregular_intervals",
+                "cadence_regime_changed",
+                "probe_failures_observed",
+            }
+            base_is_canonical = (
+                len(base_reasons) == 1
+                if self.recommended_epoch_reset
+                else base_reasons == {"irregular_intervals"}
+            )
+            if not base_is_canonical or not reason_set <= allowed:
+                _refuse("INFERENCE_STATE", "inference.reason_codes", "contradicts irregular state")
+        elif not {
+            "regular_intervals",
+            "publication_window_missed",
+        } <= reason_set or not reason_set <= {
+            "regular_intervals",
+            "publication_window_missed",
+            "probe_failures_observed",
+        }:
+            _refuse(
+                "INFERENCE_STATE",
+                "inference.reason_codes",
+                "contradicts changed regular state",
+            )
+        if self.recommended_epoch_reset != ("cadence_regime_changed" in reason_set):
+            _refuse(
+                "INFERENCE_STATE",
+                "inference.reason_codes",
+                "does not match the epoch-reset decision",
+            )
+        if self.cadence_kind in {"regular", "irregular"} and self.interval_jitter_seconds is None:
+            _refuse("INFERENCE_STATE", "inference.interval_jitter_seconds", "is required")
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "algorithm_version": self.algorithm_version,
+            "algorithm_digest": self.algorithm_digest,
+            "source_id": self.source_id,
+            "inference_epoch": self.inference_epoch,
+            "history_digest": self.history_digest,
+            "state": self.state,
+            "cadence_kind": self.cadence_kind,
+            "estimated_interval_seconds": self.estimated_interval_seconds,
+            "interval_jitter_seconds": self.interval_jitter_seconds,
+            "publication_delay_min_seconds": self.publication_delay_min_seconds,
+            "publication_delay_median_seconds": self.publication_delay_median_seconds,
+            "publication_delay_max_seconds": self.publication_delay_max_seconds,
+            "expected_next_earliest": self.expected_next_earliest,
+            "expected_next_latest": self.expected_next_latest,
+            "confidence_basis_points": self.confidence_basis_points,
+            "evidence_count": self.evidence_count,
+            "evidence_started_at": self.evidence_started_at,
+            "evidence_completed_at": self.evidence_completed_at,
+            "recommended_probe_interval_seconds": self.recommended_probe_interval_seconds,
+            "revision_style": self.revision_style,
+            "recommended_epoch_reset": self.recommended_epoch_reset,
+            "reason_codes": list(self.reason_codes),
+        }
+
+
+_OBSERVATION_KEYS = set(EmpiricalSourceObservation.__dataclass_fields__)
+_INFERENCE_KEYS = set(CadenceInference.__dataclass_fields__)
+
+
+def parse_empirical_source_observation(value: object) -> EmpiricalSourceObservation:
+    """Parse one exact observation dictionary and reject unknown or missing fields."""
+
+    if not isinstance(value, Mapping):
+        _refuse("TYPE", "observation", "must be an object")
+    payload = dict(value)
+    _exact(payload, _OBSERVATION_KEYS, "observation")
+    frontier_raw = payload["frontier"]
+    if not isinstance(frontier_raw, Mapping):
+        _refuse("TYPE", "observation.frontier", "must be an object")
+    frontier = dict(frontier_raw)
+    _exact(frontier, {"kind", "value", "derivation_rule"}, "observation.frontier")
+    partitions_raw = payload["partition_digests"]
+    if not isinstance(partitions_raw, list):
+        _refuse("TYPE", "observation.partition_digests", "must be an array")
+    partitions: list[PartitionDigest] = []
+    for index, raw in enumerate(partitions_raw):
+        if not isinstance(raw, Mapping):
+            _refuse("TYPE", f"observation.partition_digests[{index}]", "must be an object")
+        item = dict(raw)
+        _exact(
+            item,
+            {"partition_key_digest", "content_digest"},
+            f"observation.partition_digests[{index}]",
+        )
+        partitions.append(PartitionDigest(**item))
+    payload["frontier"] = SourceFrontier(**frontier)
+    payload["partition_digests"] = tuple(partitions)
+    return EmpiricalSourceObservation(**payload)
+
+
+def parse_cadence_inference(value: object) -> CadenceInference:
+    """Parse one exact inference dictionary."""
+
+    if not isinstance(value, Mapping):
+        _refuse("TYPE", "inference", "must be an object")
+    payload = dict(value)
+    _exact(payload, _INFERENCE_KEYS, "inference")
+    reasons = payload["reason_codes"]
+    if not isinstance(reasons, list):
+        _refuse("TYPE", "inference.reason_codes", "must be an array")
+    payload["reason_codes"] = tuple(reasons)
+    return CadenceInference(**payload)
+
+
+def validate_observation_history(
+    history: Sequence[EmpiricalSourceObservation],
+) -> tuple[EmpiricalSourceObservation, ...]:
+    """Validate order, predecessor links, coordinates, and change semantics."""
+
+    observations = tuple(history)
+    if len(observations) > 4_096:
+        _refuse("HISTORY_SIZE", "history", "exceeds 4096 observations")
+    if not observations:
+        return observations
+    if any(not isinstance(item, EmpiricalSourceObservation) for item in observations):
+        _refuse("TYPE", "history", "contains a non-observation item")
+    if sum(len(item.partition_digests) for item in observations) > 8_192:
+        _refuse("HISTORY_SIZE", "history", "exceeds 8192 partition records")
+    first = observations[0]
+    identity = (
+        first.source_id,
+        first.inference_epoch,
+        first.connector_configuration_digest,
+        first.locator_digest,
+        first.recipe_digest,
+        first.source_authority_digest,
+        first.reader_family_id,
+        first.reader_family_version,
+        first.reader_options_digest,
+        first.frontier_policy_digest,
+        first.time_interpretation_digest,
+        first.inference_algorithm_digest,
+    )
+    latest_acquired: EmpiricalSourceObservation | None = None
+    latest_change_time: datetime | None = None
+    latest_publication_time: datetime | None = None
+    latest_edition_sequence: int | None = None
+    publication_coordinates_present: bool | None = None
+    previous: EmpiricalSourceObservation | None = None
+    for index, item in enumerate(observations):
+        if item.sequence != index:
+            _refuse("HISTORY_SEQUENCE", f"history[{index}].sequence", "is not contiguous")
+        current_identity = (
+            item.source_id,
+            item.inference_epoch,
+            item.connector_configuration_digest,
+            item.locator_digest,
+            item.recipe_digest,
+            item.source_authority_digest,
+            item.reader_family_id,
+            item.reader_family_version,
+            item.reader_options_digest,
+            item.frontier_policy_digest,
+            item.time_interpretation_digest,
+            item.inference_algorithm_digest,
+        )
+        if current_identity != identity:
+            _refuse("HISTORY_IDENTITY", f"history[{index}]", "splices another source or epoch")
+        if previous is None:
+            if item.previous_observation_digest is not None:
+                _refuse("HISTORY_PREDECESSOR", f"history[{index}]", "has an unexpected predecessor")
+        else:
+            if item.previous_observation_digest != previous.digest:
+                _refuse("HISTORY_PREDECESSOR", f"history[{index}]", "does not bind its predecessor")
+            if _timestamp(item.started_at, f"history[{index}].started_at") < _timestamp(
+                previous.completed_at, f"history[{index - 1}].completed_at"
+            ):
+                _refuse("HISTORY_TIME", f"history[{index}].started_at", "overlaps its predecessor")
+        if item.result_kind in {"changed", "unchanged"} and item.content_digest is not None:
+            if item.result_kind == "unchanged" and latest_acquired is None:
+                _refuse(
+                    "UNCHANGED_BASELINE",
+                    f"history[{index}]",
+                    "has no prior acquired fact in this epoch",
+                )
+            if latest_acquired is not None:
+                if (
+                    item.frontier.kind != latest_acquired.frontier.kind
+                    or item.frontier.derivation_rule != latest_acquired.frontier.derivation_rule
+                ):
+                    _refuse(
+                        "HISTORY_IDENTITY",
+                        f"history[{index}].frontier",
+                        "changes the frontier policy within one epoch",
+                    )
+                same_content = item.content_digest == latest_acquired.content_digest
+                same_rows = item.row_digest == latest_acquired.row_digest
+                same_schema = item.schema_digest == latest_acquired.schema_digest
+                same_frontier = item.frontier == latest_acquired.frontier
+                same_acquired_facts = (
+                    item.acquired_size_bytes == latest_acquired.acquired_size_bytes
+                    and item.row_count == latest_acquired.row_count
+                    and item.max_event_time == latest_acquired.max_event_time
+                    and item.partition_digests == latest_acquired.partition_digests
+                    and item.next_watermark_candidate_digest
+                    == latest_acquired.next_watermark_candidate_digest
+                    and item.publication_reference_time
+                    == latest_acquired.publication_reference_time
+                    and item.edition_sequence == latest_acquired.edition_sequence
+                )
+                if item.result_kind == "changed" and same_content and same_rows and same_schema:
+                    _refuse(
+                        "CHANGE_SEMANTICS",
+                        f"history[{index}]",
+                        "claims changed for identical data",
+                    )
+                if item.result_kind == "unchanged" and not (
+                    same_content
+                    and same_rows
+                    and same_schema
+                    and same_frontier
+                    and same_acquired_facts
+                ):
+                    _refuse(
+                        "CHANGE_SEMANTICS",
+                        f"history[{index}]",
+                        "claims unchanged for changed data",
+                    )
+                comparison = _compare_frontiers(latest_acquired.frontier, item.frontier)
+                if comparison is not None and comparison < 0:
+                    _refuse("FRONTIER_REGRESSION", f"history[{index}].frontier", "regresses")
+                if comparison is not None and comparison > 0 and same_content:
+                    _refuse(
+                        "FRONTIER_CONTENT",
+                        f"history[{index}]",
+                        "advances with identical content",
+                    )
+            latest_acquired = item
+        elif item.result_kind == "unchanged" and latest_acquired is None:
+            _refuse(
+                "UNCHANGED_BASELINE",
+                f"history[{index}]",
+                "has no prior acquired fact in this epoch",
+            )
+        if item.result_kind == "changed":
+            has_publication_coordinates = item.publication_reference_time is not None
+            if publication_coordinates_present is None:
+                publication_coordinates_present = has_publication_coordinates
+            elif publication_coordinates_present != has_publication_coordinates:
+                _refuse(
+                    "HISTORY_IDENTITY",
+                    f"history[{index}]",
+                    "changes publication-coordinate policy within one epoch",
+                )
+            change_time = _timestamp(item.completed_at, f"history[{index}].completed_at")
+            if latest_change_time is not None and change_time <= latest_change_time:
+                _refuse(
+                    "HISTORY_CHANGE_TIME",
+                    f"history[{index}].completed_at",
+                    "does not follow the prior material change",
+                )
+            latest_change_time = change_time
+            if item.publication_reference_time is not None:
+                publication_time = _timestamp(
+                    item.publication_reference_time,
+                    f"history[{index}].publication_reference_time",
+                )
+                assert item.edition_sequence is not None
+                if (
+                    latest_publication_time is not None
+                    and publication_time <= latest_publication_time
+                ):
+                    _refuse(
+                        "PUBLICATION_ORDER",
+                        f"history[{index}].publication_reference_time",
+                        "does not follow the prior changed edition",
+                    )
+                if (
+                    latest_edition_sequence is not None
+                    and item.edition_sequence <= latest_edition_sequence
+                ):
+                    _refuse(
+                        "PUBLICATION_ORDER",
+                        f"history[{index}].edition_sequence",
+                        "does not follow the prior changed edition",
+                    )
+                latest_publication_time = publication_time
+                latest_edition_sequence = item.edition_sequence
+        previous = item
+    return observations
+
+
+def _frontier_value(frontier: SourceFrontier) -> object:
+    if frontier.kind == "date":
+        return datetime.strptime(frontier.value, "%Y-%m-%d").date()
+    if frontier.kind == "timestamp":
+        return _timestamp(frontier.value, "frontier.value")
+    if frontier.kind == "integer":
+        return int(frontier.value)
+    return frontier.value
+
+
+def _compare_frontiers(left: SourceFrontier, right: SourceFrontier) -> int | None:
+    if left.kind != right.kind or left.derivation_rule != right.derivation_rule:
+        return None
+    if left.kind in {"none", "opaque"}:
+        return 0 if left.value == right.value else None
+    left_value = _frontier_value(left)
+    right_value = _frontier_value(right)
+    return (right_value > left_value) - (right_value < left_value)
+
+
+def _median_int(values: Sequence[int]) -> int:
+    ordered = sorted(values)
+    middle = len(ordered) // 2
+    if len(ordered) % 2:
+        return ordered[middle]
+    return (ordered[middle - 1] + ordered[middle]) // 2
+
+
+def _revision_style(changes: Sequence[EmpiricalSourceObservation]) -> str:
+    if len(changes) < 2:
+        return "unknown"
+    saw_append = False
+    saw_unclassified = False
+    saw_replacement = False
+    for previous, current in pairwise(changes):
+        comparison = _compare_frontiers(previous.frontier, current.frontier)
+        if comparison == 0 and current.content_digest != previous.content_digest:
+            return "historical_revision"
+        if (
+            current.row_count is not None
+            and previous.row_count is not None
+            and current.row_count < previous.row_count
+        ):
+            saw_replacement = True
+        previous_partitions = {
+            item.partition_key_digest: item.content_digest for item in previous.partition_digests
+        }
+        current_partitions = {
+            item.partition_key_digest: item.content_digest for item in current.partition_digests
+        }
+        if previous_partitions:
+            prior_rewritten = any(
+                current_partitions.get(key) != digest for key, digest in previous_partitions.items()
+            )
+            if prior_rewritten:
+                saw_replacement = True
+            elif set(current_partitions) > set(previous_partitions):
+                saw_append = True
+            else:
+                saw_unclassified = True
+        else:
+            saw_unclassified = True
+    if saw_replacement:
+        return "replacement"
+    if saw_append and not saw_unclassified:
+        return "append"
+    return "unknown"
+
+
+def infer_source_cadence(
+    history: Sequence[EmpiricalSourceObservation],
+) -> CadenceInference:
+    """Return a deterministic empirical cadence result for one validated history."""
+
+    observations = validate_observation_history(history)
+    if not observations:
+        return CadenceInference(
+            source_id="unknown",
+            inference_epoch="unknown",
+            history_digest=canonical_sha256([]),
+            state="unknown",
+            cadence_kind="unknown",
+            estimated_interval_seconds=None,
+            interval_jitter_seconds=None,
+            publication_delay_min_seconds=None,
+            publication_delay_median_seconds=None,
+            publication_delay_max_seconds=None,
+            expected_next_earliest=None,
+            expected_next_latest=None,
+            confidence_basis_points=0,
+            evidence_count=0,
+            evidence_started_at=None,
+            evidence_completed_at=None,
+            recommended_probe_interval_seconds=21_600,
+            revision_style="unknown",
+            recommended_epoch_reset=False,
+            reason_codes=("no_observations",),
+        )
+    first = observations[0]
+    if first.inference_algorithm_digest != SOURCE_CADENCE_ALGORITHM_DIGEST:
+        _refuse("ALGORITHM", "history", "requires a different inference implementation")
+    history_digest = canonical_sha256([item.to_dict() for item in observations])
+    changes = tuple(item for item in observations if item.result_kind == "changed")
+    publication_coordinates_complete = bool(changes) and all(
+        item.publication_reference_time is not None and item.edition_sequence is not None
+        for item in changes
+    )
+    publication_times = (
+        tuple(
+            _timestamp(item.publication_reference_time, "observation.publication_reference_time")
+            for item in changes
+        )
+        if publication_coordinates_complete
+        else ()
+    )
+    edition_sequences = (
+        tuple(item.edition_sequence for item in changes) if publication_coordinates_complete else ()
+    )
+    interval_values: list[int] = []
+    for (left_time, right_time), (left_sequence, right_sequence) in zip(
+        pairwise(publication_times),
+        pairwise(edition_sequences),
+        strict=True,
+    ):
+        assert left_sequence is not None and right_sequence is not None
+        editions = right_sequence - left_sequence
+        seconds = _elapsed_whole_seconds(left_time, right_time)
+        if editions <= 0 or seconds < editions:
+            _refuse(
+                "PUBLICATION_INTERVAL",
+                "history",
+                "cannot derive a positive whole-second interval per edition",
+            )
+        interval_values.append(seconds // editions)
+    intervals = tuple(interval_values)
+    delays_list: list[int] = []
+    for item in changes:
+        if item.publication_reference_time is None:
+            continue
+        completed = _timestamp(item.completed_at, "observation.completed_at")
+        publication_time = _timestamp(
+            item.publication_reference_time,
+            "observation.publication_reference_time",
+        )
+        delays_list.append(_elapsed_whole_seconds(publication_time, completed))
+    delays = tuple(delays_list)
+    interval = _median_int(intervals) if intervals else None
+    jitter = (
+        max((abs(value - interval) for value in intervals), default=None)
+        if interval is not None
+        else None
+    )
+    state = "learning"
+    cadence_kind = "unknown"
+    reset = False
+    reasons: list[str] = []
+    if changes and not publication_coordinates_complete:
+        reasons.append("missing_publication_coordinates")
+    if len(changes) < 4 or not publication_coordinates_complete:
+        reasons.append("insufficient_changes")
+    else:
+        assert interval is not None and jitter is not None
+        allowed_spread = max(3_600, interval * 2_000 // 10_000)
+        if jitter <= allowed_spread:
+            state = "stable"
+            cadence_kind = "regular"
+            reasons.append("regular_intervals")
+        else:
+            state = "changed_pattern"
+            cadence_kind = "irregular"
+            interval = None
+            reasons.append("irregular_intervals")
+        if len(intervals) >= 5:
+            baseline = _median_int(intervals[:-2])
+            recent = intervals[-2:]
+            materially_changed = all(
+                abs(value - baseline) * 10_000 > baseline * 4_000 for value in recent
+            )
+            mutually_consistent = abs(recent[0] - recent[1]) * 10_000 <= max(recent) * 2_000
+            if materially_changed and mutually_consistent:
+                state = "changed_pattern"
+                cadence_kind = "irregular"
+                reset = True
+                interval = None
+                reasons.append("cadence_regime_changed")
+    latest_time = _timestamp(observations[-1].completed_at, "observation.completed_at")
+    regular_interval = _median_int(intervals) if intervals else None
+    if state == "stable" and regular_interval is not None and changes:
+        since_change = _elapsed_whole_seconds(publication_times[-1], latest_time)
+        trailing = tuple(
+            item.result_kind for item in observations[observations.index(changes[-1]) + 1 :]
+        )
+        if (
+            since_change > regular_interval * 4
+            and len(trailing) >= 3
+            and all(kind in {"unchanged", "not_published"} for kind in trailing)
+        ):
+            state = "dormant"
+            reasons.append("prolonged_no_change")
+    expected_earliest = expected_latest = None
+    if regular_interval is not None and changes and cadence_kind == "regular":
+        margin = max(300, regular_interval // 20, jitter or 0)
+        center = _safe_shift(
+            publication_times[-1],
+            regular_interval,
+            "inference.expected_window",
+        )
+        earliest = _safe_shift(center, -margin, "inference.expected_next_earliest")
+        latest = _safe_shift(center, margin, "inference.expected_next_latest")
+        if state == "stable" and latest_time <= latest:
+            expected_earliest = _format_timestamp(earliest)
+            expected_latest = _format_timestamp(latest)
+        elif state == "stable":
+            state = "changed_pattern"
+            reasons.append("publication_window_missed")
+    failure_count = sum(item.result_kind == "failed" for item in observations)
+    if failure_count:
+        reasons.append("probe_failures_observed")
+    confidence = 0
+    if state == "learning":
+        confidence = min(4_000, len(changes) * 1_000)
+    elif state == "stable":
+        confidence = min(9_500, 6_000 + max(0, len(intervals) - 3) * 500)
+    elif state == "dormant":
+        confidence = min(8_000, 5_000 + len(intervals) * 300)
+    elif state == "changed_pattern":
+        confidence = 2_500
+    confidence = max(0, confidence - min(3_000, failure_count * 500))
+    if state == "stable" and regular_interval is not None:
+        probe = max(300, min(21_600, regular_interval // 8))
+    elif state == "dormant" and regular_interval is not None:
+        probe = max(86_400, min(7 * 86_400, regular_interval))
+    elif intervals:
+        probe = max(900, min(86_400, _median_int(intervals) // 4))
+    else:
+        probe = 21_600
+    if reset:
+        probe = min(probe, 3_600)
+    delay_min = min(delays) if delays else None
+    delay_median = _median_int(delays) if delays else None
+    delay_max = max(delays) if delays else None
+    return CadenceInference(
+        source_id=first.source_id,
+        inference_epoch=first.inference_epoch,
+        history_digest=history_digest,
+        state=state,
+        cadence_kind=cadence_kind,
+        estimated_interval_seconds=interval,
+        interval_jitter_seconds=jitter,
+        publication_delay_min_seconds=delay_min,
+        publication_delay_median_seconds=delay_median,
+        publication_delay_max_seconds=delay_max,
+        expected_next_earliest=expected_earliest,
+        expected_next_latest=expected_latest,
+        confidence_basis_points=confidence,
+        evidence_count=len(observations),
+        evidence_started_at=observations[0].started_at,
+        evidence_completed_at=observations[-1].completed_at,
+        recommended_probe_interval_seconds=probe,
+        revision_style=_revision_style(changes),
+        recommended_epoch_reset=reset,
+        reason_codes=tuple(reasons),
+    )
+
+
+__all__ = [
+    "SOURCE_CADENCE_ALGORITHM_DIGEST",
+    "SOURCE_CADENCE_ALGORITHM_VERSION",
+    "SOURCE_CADENCE_INFERENCE_SCHEMA",
+    "SOURCE_CADENCE_OBSERVATION_SCHEMA",
+    "CadenceContractError",
+    "CadenceInference",
+    "EmpiricalSourceObservation",
+    "PartitionDigest",
+    "SourceFrontier",
+    "infer_source_cadence",
+    "parse_cadence_inference",
+    "parse_empirical_source_observation",
+    "source_cadence_algorithm_spec",
+    "validate_observation_history",
+]