mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/sports.py

@@ -0,0 +1,521 @@
+"""Recorded sports-source comparison and OpenLigaDB governance policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.acquisition.sandbox import CrawlerSandbox
+from mostlyright.data_harness.canonical import canonical_sha256, parse_json, sha256_bytes
+from mostlyright.data_harness.local_contracts import (
+    EvidenceReference as ProposalEvidence,
+)
+from mostlyright.data_harness.local_contracts import SourceProposal, TimeRange
+from mostlyright.data_harness.sources.adapters import (
+    AdapterGovernance,
+    PublicHttpsAdapter,
+)
+from mostlyright.data_harness.sources.contracts import (
+    FITNESS_DIMENSIONS,
+    AdapterDescriptor,
+    EvidenceReference,
+    LicenseObligation,
+    RightsEvidence,
+    SourceContractError,
+    SourceObservation,
+    evaluate_obligations,
+)
+from mostlyright.data_harness.sources.fitness import (
+    FitnessSignals,
+    build_fitness_report,
+    select_one_source,
+)
+
+OPENLIGADB_ORIGIN = "https://openligadb.de/"
+OPENLIGADB_API_HOST = "api.openligadb.de"
+STATSBOMB_ORIGIN = "https://github.com/statsbomb/open-data"
+
+
+@dataclass(frozen=True)
+class SportsComparison:
+    """Digests of both recorded sports fitness reports and of the one selected source."""
+
+    openligadb_report_digest: str
+    statsbomb_report_digest: str
+    selected_source_id: str
+    selected_report_digest: str
+    selected_observation_digest: str
+    selected_rights_digest: str
+    evidence_manifest_sha256: str
+    selected_sample_sha256: str
+
+
+_PACKAGE_TOKEN = object()
+_LIFECYCLE_TRANSITIONS = {
+    "candidate": frozenset({"derivative"}),
+    "derivative": frozenset({"redistribution", "publication"}),
+    "redistribution": frozenset({"publication"}),
+    "publication": frozenset(),
+}
+
+
+@dataclass(frozen=True, init=False)
+class GovernedSportsPackage:
+    """Only lifecycle object allowed to advance ODbL-governed source material."""
+
+    lifecycle: str
+    rights_digest: str
+    intended_use: str
+    attached_artifact_digests: tuple[str, ...]
+    predecessor_digest: str | None
+    package_digest: str
+    _rights: RightsEvidence
+
+    def __init__(
+        self,
+        *,
+        lifecycle: str,
+        rights: RightsEvidence,
+        intended_use: str,
+        attached_artifact_digests: tuple[str, ...],
+        predecessor_digest: str | None,
+        _token: object,
+    ) -> None:
+        if _token is not _PACKAGE_TOKEN:
+            raise SourceContractError(
+                "GOVERNED_PACKAGE_FACTORY",
+                "package",
+                "governed source packages must use the controlled lifecycle factory",
+            )
+        evaluate_obligations(
+            rights=rights,
+            lifecycle=lifecycle,
+            intended_use=intended_use,
+            attached_artifact_digests=attached_artifact_digests,
+        )
+        payload = {
+            "schema_version": "governed-sports-package.v1",
+            "lifecycle": lifecycle,
+            "rights_digest": rights.digest,
+            "intended_use": intended_use,
+            "attached_artifact_digests": list(attached_artifact_digests),
+            "predecessor_digest": predecessor_digest,
+        }
+        object.__setattr__(self, "lifecycle", lifecycle)
+        object.__setattr__(self, "rights_digest", rights.digest)
+        object.__setattr__(self, "intended_use", intended_use)
+        object.__setattr__(self, "attached_artifact_digests", attached_artifact_digests)
+        object.__setattr__(self, "predecessor_digest", predecessor_digest)
+        object.__setattr__(self, "package_digest", canonical_sha256(payload))
+        object.__setattr__(self, "_rights", rights)
+
+    def advance(
+        self,
+        *,
+        lifecycle: str,
+        intended_use: str,
+        attached_artifact_digests: tuple[str, ...],
+    ) -> GovernedSportsPackage:
+        if lifecycle not in _LIFECYCLE_TRANSITIONS[self.lifecycle]:
+            raise SourceContractError(
+                "LIFECYCLE_TRANSITION",
+                "package.lifecycle",
+                f"cannot advance {self.lifecycle} to {lifecycle}",
+            )
+        return GovernedSportsPackage(
+            lifecycle=lifecycle,
+            rights=self._rights,
+            intended_use=intended_use,
+            attached_artifact_digests=attached_artifact_digests,
+            predecessor_digest=self.package_digest,
+            _token=_PACKAGE_TOKEN,
+        )
+
+
+def create_governed_sports_package(
+    *,
+    rights: RightsEvidence,
+    intended_use: str,
+    attached_artifact_digests: tuple[str, ...],
+) -> GovernedSportsPackage:
+    """Create a candidate only after worker-owned candidate obligation evaluation."""
+
+    return GovernedSportsPackage(
+        lifecycle="candidate",
+        rights=rights,
+        intended_use=intended_use,
+        attached_artifact_digests=attached_artifact_digests,
+        predecessor_digest=None,
+        _token=_PACKAGE_TOKEN,
+    )
+
+
+def openligadb_descriptor() -> AdapterDescriptor:
+    return AdapterDescriptor(
+        adapter_id="external.openligadb",
+        adapter_version="1.0.0",
+        source_class="external_adapter",
+        data_formats=("json",),
+        capabilities=("snapshot", "historical", "live", "refresh"),
+    )
+
+
+def openligadb_adapter(
+    *,
+    sandbox: CrawlerSandbox,
+    governance: AdapterGovernance,
+) -> PublicHttpsAdapter:
+    """Return the source-specific adapter over the generic pinned HTTPS boundary."""
+
+    return PublicHttpsAdapter(
+        sandbox=sandbox,
+        allowed_hostnames=(OPENLIGADB_API_HOST,),
+        governance=governance,
+        descriptor=openligadb_descriptor(),
+    )
+
+
+def openligadb_rights(
+    *,
+    evidence: EvidenceReference,
+    attribution_digest: str,
+    notice_digest: str,
+    share_alike_digest: str,
+    downstream_access_digest: str,
+) -> RightsEvidence:
+    """Encode ODbL conditions as lifecycle-specific deterministic gates."""
+
+    all_stages = ("candidate", "derivative", "redistribution", "publication")
+    public_stages = ("derivative", "redistribution", "publication")
+    redistribution_stages = ("redistribution", "publication")
+    return RightsEvidence(
+        status="conditional",
+        lawful_basis="Open Database License 1.0 as recorded by the source project",
+        allowed_uses=("analysis", "redistribute_open_database"),
+        evidence=(evidence,),
+        obligations=(
+            LicenseObligation(
+                obligation_id="odbl.attribution",
+                applies_at=all_stages,
+                permitted_uses=("analysis", "redistribute_open_database"),
+                prohibited_uses=("proprietary_relicense",),
+                required_artifact_digests=(attribution_digest,),
+                escalation_when_ambiguous=True,
+            ),
+            LicenseObligation(
+                obligation_id="odbl.notice",
+                applies_at=all_stages,
+                permitted_uses=("analysis", "redistribute_open_database"),
+                prohibited_uses=("proprietary_relicense",),
+                required_artifact_digests=(notice_digest,),
+                escalation_when_ambiguous=True,
+            ),
+            LicenseObligation(
+                obligation_id="odbl.share-alike",
+                applies_at=public_stages,
+                permitted_uses=("analysis", "redistribute_open_database"),
+                prohibited_uses=("proprietary_relicense",),
+                required_artifact_digests=(share_alike_digest,),
+                escalation_when_ambiguous=True,
+            ),
+            LicenseObligation(
+                obligation_id="odbl.downstream-access",
+                applies_at=redistribution_stages,
+                permitted_uses=("redistribute_open_database",),
+                prohibited_uses=("proprietary_relicense",),
+                required_artifact_digests=(downstream_access_digest,),
+                escalation_when_ambiguous=True,
+            ),
+        ),
+    )
+
+
+def compare_recorded_sports_sources(
+    *,
+    fixture_root: Path,
+    observed_at: str,
+    intended_use: str,
+    openligadb_rights_evidence: RightsEvidence,
+    statsbomb_rights_evidence: RightsEvidence,
+    openligadb_attached_artifact_digests: tuple[str, ...],
+    statsbomb_attached_artifact_digests: tuple[str, ...],
+) -> SportsComparison:
+    """Compare recorded liveness/rights evidence and deterministically select one source.
+
+    ``fixture_root`` must hold ``source-evidence-manifest.json`` and every file that manifest
+    names. The manifest declares schema version ``recorded-source-evidence.v1`` and a
+    ``captured_at`` equal to ``observed_at``. Its ``sources`` list holds exactly two records, one
+    with source id ``openligadb-matches`` and one with ``statsbomb-open-data``. Each record names
+    a documentation file and an optional sample file that sit directly in ``fixture_root`` and
+    hash to the digests it records. The checked-in fixture is ``tests/fixtures/h3``; it ships with
+    the tests, not with the package.
+    """
+
+    manifest_path = fixture_root / "source-evidence-manifest.json"
+    manifest_raw = manifest_path.read_bytes()
+    manifest = _recorded_evidence_manifest(manifest_raw, fixture_root, observed_at)
+    sources = {item["source_id"]: item for item in manifest["sources"]}
+    openliga_record = sources["openligadb-matches"]
+    statsbomb_record = sources["statsbomb-open-data"]
+    openliga_file = fixture_root / openliga_record["documentation_path"]
+    statsbomb_file = fixture_root / statsbomb_record["documentation_path"]
+    openliga_digest = sha256_bytes(openliga_file.read_bytes())
+    statsbomb_digest = sha256_bytes(statsbomb_file.read_bytes())
+    openliga_evidence = EvidenceReference(
+        uri=OPENLIGADB_ORIGIN,
+        observed_at=observed_at,
+        content_sha256=openliga_digest,
+        media_type="text/plain",
+    )
+    statsbomb_evidence = EvidenceReference(
+        uri=STATSBOMB_ORIGIN,
+        observed_at=observed_at,
+        content_sha256=statsbomb_digest,
+        media_type="text/plain",
+    )
+    openliga_proposal = _proposal(
+        source_id="openligadb-matches",
+        proposal_id="proposal-openligadb",
+        display_name="OpenLigaDB current match results",
+        locator="https://api.openligadb.de/getmatchdata/bl1/2026",
+        observed_at=observed_at,
+        delay_seconds=120,
+        live_endpoint="live",
+        fitness_decision="selected",
+        evidence=openliga_evidence,
+    )
+    statsbomb_proposal = _proposal(
+        source_id="statsbomb-open-data",
+        proposal_id="proposal-statsbomb",
+        display_name="StatsBomb historical open data",
+        locator=STATSBOMB_ORIGIN,
+        observed_at=observed_at,
+        delay_seconds=86_400,
+        live_endpoint="delayed",
+        fitness_decision="rejected",
+        evidence=statsbomb_evidence,
+    )
+    openliga_observation = _observation(
+        source_id=openliga_proposal.source_id,
+        observed_at=observed_at,
+        live_status="live",
+        delay_seconds=120,
+        evidence=openliga_evidence,
+    )
+    statsbomb_observation = _observation(
+        source_id=statsbomb_proposal.source_id,
+        observed_at=observed_at,
+        live_status="delayed",
+        delay_seconds=86_400,
+        evidence=statsbomb_evidence,
+    )
+    openliga_report = build_fitness_report(
+        report_id="fitness.openligadb",
+        question_id="question-timely-match-results",
+        proposal=openliga_proposal,
+        observation=openliga_observation,
+        rights=openligadb_rights_evidence,
+        intended_use=intended_use,
+        attached_license_artifact_digests=openligadb_attached_artifact_digests,
+        signals=_passing_signals(openliga_evidence),
+        require_timely=True,
+        max_publication_delay_seconds=600,
+    )
+    statsbomb_report = build_fitness_report(
+        report_id="fitness.statsbomb",
+        question_id="question-timely-match-results",
+        proposal=statsbomb_proposal,
+        observation=statsbomb_observation,
+        rights=statsbomb_rights_evidence,
+        intended_use=intended_use,
+        attached_license_artifact_digests=statsbomb_attached_artifact_digests,
+        signals=_passing_signals(statsbomb_evidence),
+        require_timely=True,
+        max_publication_delay_seconds=600,
+    )
+    selected = select_one_source((openliga_report, statsbomb_report))
+    return SportsComparison(
+        openligadb_report_digest=openliga_report.digest,
+        statsbomb_report_digest=statsbomb_report.digest,
+        selected_source_id=selected.source_id,
+        selected_report_digest=selected.digest,
+        selected_observation_digest=selected.observation_digest,
+        selected_rights_digest=selected.rights_digest,
+        evidence_manifest_sha256=sha256_bytes(manifest_raw),
+        selected_sample_sha256=openliga_record["sample_sha256"],
+    )
+
+
+def _recorded_evidence_manifest(
+    raw: bytes,
+    fixture_root: Path,
+    observed_at: str,
+) -> dict[str, Any]:
+    value = parse_json(raw)
+    if not isinstance(value, dict) or set(value) != {
+        "schema_version",
+        "captured_at",
+        "sources",
+    }:
+        raise SourceContractError(
+            "RECORDED_EVIDENCE_MANIFEST",
+            "manifest",
+            "recorded evidence manifest fields are invalid",
+        )
+    if (
+        value["schema_version"] != "recorded-source-evidence.v1"
+        or value["captured_at"] != observed_at
+        or not isinstance(value["sources"], list)
+        or len(value["sources"]) != 2
+    ):
+        raise SourceContractError(
+            "RECORDED_EVIDENCE_MANIFEST",
+            "manifest",
+            "recorded evidence manifest identity or capture time is invalid",
+        )
+    expected_fields = {
+        "source_id",
+        "documentation_uri",
+        "documentation_path",
+        "documentation_sha256",
+        "sample_uri",
+        "sample_path",
+        "sample_sha256",
+        "recorded_response_status",
+        "recorded_media_type",
+        "rights_status",
+        "license",
+        "permitted_uses",
+        "required_controls",
+    }
+    records: dict[str, dict[str, Any]] = {}
+    for item in value["sources"]:
+        if not isinstance(item, dict) or set(item) != expected_fields:
+            raise SourceContractError(
+                "RECORDED_EVIDENCE_MANIFEST",
+                "manifest.sources",
+                "recorded source evidence fields are invalid",
+            )
+        source_id = item["source_id"]
+        if source_id in records or source_id not in {
+            "openligadb-matches",
+            "statsbomb-open-data",
+        }:
+            raise SourceContractError(
+                "RECORDED_EVIDENCE_MANIFEST",
+                "manifest.sources.source_id",
+                "recorded source identity is duplicate or unexpected",
+            )
+        documentation_path = item["documentation_path"]
+        if (
+            not isinstance(documentation_path, str)
+            or Path(documentation_path).name != documentation_path
+            or sha256_bytes((fixture_root / documentation_path).read_bytes())
+            != item["documentation_sha256"]
+        ):
+            raise SourceContractError(
+                "RECORDED_EVIDENCE_DIGEST",
+                "manifest.sources.documentation_sha256",
+                "recorded documentation bytes do not match the manifest",
+            )
+        sample_path = item["sample_path"]
+        if sample_path is None:
+            if item["sample_sha256"] is not None:
+                raise SourceContractError(
+                    "RECORDED_EVIDENCE_DIGEST",
+                    "manifest.sources.sample_sha256",
+                    "absent sample must not claim a digest",
+                )
+        elif (
+            not isinstance(sample_path, str)
+            or Path(sample_path).name != sample_path
+            or sha256_bytes((fixture_root / sample_path).read_bytes()) != item["sample_sha256"]
+        ):
+            raise SourceContractError(
+                "RECORDED_EVIDENCE_DIGEST",
+                "manifest.sources.sample_sha256",
+                "recorded sample bytes do not match the manifest",
+            )
+        records[source_id] = item
+    if set(records) != {"openligadb-matches", "statsbomb-open-data"}:
+        raise SourceContractError(
+            "RECORDED_EVIDENCE_MANIFEST",
+            "manifest.sources",
+            "both required sports evidence records are required",
+        )
+    return value
+
+
+def _proposal(
+    *,
+    source_id: str,
+    proposal_id: str,
+    display_name: str,
+    locator: str,
+    observed_at: str,
+    delay_seconds: int,
+    live_endpoint: str,
+    fitness_decision: str,
+    evidence: EvidenceReference,
+) -> SourceProposal:
+    return SourceProposal(
+        proposal_id=proposal_id,
+        question_id="question-timely-match-results",
+        source_id=source_id,
+        source_class="external_adapter",
+        display_name=display_name,
+        locator_kind="https_url",
+        locator=locator,
+        data_format="json",
+        observed_at=observed_at,
+        historical_coverage=TimeRange(
+            start_inclusive="2018-08-01T00:00:00Z",
+            end_exclusive="2026-07-18T00:00:00Z",
+        ),
+        live_endpoint=live_endpoint,
+        publication_delay_seconds=delay_seconds,
+        rights_status="conditional",
+        fitness_decision=fitness_decision,
+        evidence=(
+            ProposalEvidence(
+                uri=evidence.uri,
+                observed_at=evidence.observed_at,
+                content_sha256=evidence.content_sha256,
+            ),
+        ),
+    )
+
+
+def _observation(
+    *,
+    source_id: str,
+    observed_at: str,
+    live_status: str,
+    delay_seconds: int,
+    evidence: EvidenceReference,
+) -> SourceObservation:
+    return SourceObservation(
+        source_id=source_id,
+        observed_at=observed_at,
+        event_time_field="match_time",
+        available_at_field="available_at",
+        historical_start="2018-08-01T00:00:00Z",
+        historical_end="2026-07-17T00:00:00Z",
+        live_status=live_status,
+        publication_delay_seconds=delay_seconds,
+        update_frequency_seconds=300 if live_status == "live" else 86_400,
+        response_status=200,
+        evidence=(evidence,),
+    )
+
+
+def _passing_signals(evidence: EvidenceReference) -> FitnessSignals:
+    return FitnessSignals(
+        outcomes=tuple((dimension, True) for dimension in sorted(FITNESS_DIMENSIONS)),
+        summaries=tuple(
+            (dimension, f"recorded evidence supports {dimension}")
+            for dimension in sorted(FITNESS_DIMENSIONS)
+        ),
+        evidence=(evidence,),
+    )