geointel/backend/app/services/temporal_analysis_service.py

from __future__ import annotations

from datetime import datetime, timezone
from typing import Any
from uuid import UUID

from geoalchemy2.functions import ST_Intersects, ST_MakeEnvelope
from geoalchemy2.shape import to_shape
from shapely.geometry import mapping
from sqlalchemy.orm import Session

from app.core.errors import AppError
from app.models import Area, Dataset, VectorFeature
from app.schemas.temporal import (
    TemporalComparisonRequest,
    TemporalComparisonResponse,
    TemporalDatasetRef,
    TemporalMetricComparison,
    TemporalObjectChanges,
    TemporalObservation,
    TemporalObservationMetric,
    TemporalSeriesDataset,
    TemporalSeriesRead,
)
from app.schemas.thematic_raster import ThematicRasterSelectionRequest
from app.services.vector_feature_service import VectorFeatureService
from app.services.walous_land_cover_service import WalousLandCoverService


class TemporalAnalysisService:
    IDENTITY_COMPARISON_LIMIT = 5_000
    GOVERNED_GRB_IDENTITY_OPERATORS = {
        "provision_regional_grb_buildings.py",
        "provision_regional_grb_context.py",
    }
    SUPPORTED_RASTER_TEMPORAL_SOURCES = {WalousLandCoverService.PROVIDER}

    @staticmethod
    def _canonical_observation_snapshots(datasets: list[Dataset]) -> list[Dataset]:
        by_observation: dict[datetime, Dataset] = {}
        for dataset in datasets:
            if dataset.observed_at is None:
                continue
            current = by_observation.get(dataset.observed_at)
            dataset_recency = max(
                (
                    value.timestamp()
                    for value in (dataset.imported_at, dataset.updated_at, dataset.created_at)
                    if value is not None
                ),
                default=0.0,
            )
            current_recency = max(
                (
                    value.timestamp()
                    for value in (
                        getattr(current, "imported_at", None),
                        getattr(current, "updated_at", None),
                        getattr(current, "created_at", None),
                    )
                    if value is not None
                ),
                default=0.0,
            )
            if current is None or (dataset_recency, str(dataset.id)) > (current_recency, str(current.id)):
                by_observation[dataset.observed_at] = dataset
        return sorted(by_observation.values(), key=lambda item: item.observed_at)

    @staticmethod
    def list_series(db: Session, project_id: UUID) -> list[TemporalSeriesRead]:
        rows = (
            db.query(Dataset)
            .filter(Dataset.project_id == project_id)
            .filter(Dataset.temporal_series_key.isnot(None))
            .filter(Dataset.observed_at.isnot(None))
            .order_by(Dataset.temporal_series_key.asc(), Dataset.observed_at.asc())
            .all()
        )
        grouped: dict[str, list[Dataset]] = {}
        for row in rows:
            if row.temporal_series_key:
                grouped.setdefault(row.temporal_series_key, []).append(row)

        result: list[TemporalSeriesRead] = []
        for key, datasets in grouped.items():
            datasets = TemporalAnalysisService._canonical_observation_snapshots(datasets)
            observed = [item.observed_at for item in datasets if item.observed_at is not None]
            if not observed:
                continue
            result.append(
                TemporalSeriesRead(
                    temporal_series_key=key,
                    source_name=datasets[-1].source_name,
                    reference_layer_name=datasets[-1].reference_layer_name,
                    dataset_count=len(datasets),
                    first_observed_at=min(observed),
                    last_observed_at=max(observed),
                    datasets=[
                        TemporalSeriesDataset(
                            id=item.id,
                            name=item.name,
                            observed_at=item.observed_at,
                            source_version=item.source_version,
                            feature_count=(item.metadata_json or {}).get("feature_count")
                            if isinstance(item.metadata_json, dict)
                            else None,
                        )
                        for item in datasets
                        if item.observed_at is not None
                    ],
                )
            )
        return result

    @staticmethod
    def compare(
        db: Session,
        *,
        project_id: UUID,
        payload: TemporalComparisonRequest,
    ) -> TemporalComparisonResponse:
        if payload.earlier_dataset_id == payload.later_dataset_id:
            raise AppError(
                code="INVALID_TEMPORAL_COMPARISON",
                message="Choose two different dataset snapshots",
                status_code=400,
            )
        earlier = TemporalAnalysisService._get_temporal_dataset(db, project_id, payload.earlier_dataset_id, "Earlier")
        later = TemporalAnalysisService._get_temporal_dataset(db, project_id, payload.later_dataset_id, "Later")
        if earlier.temporal_series_key != later.temporal_series_key:
            raise AppError(
                code="INCOMPATIBLE_TEMPORAL_SERIES",
                message="Dataset snapshots must belong to the same temporal series",
                details={
                    "earlier_series": earlier.temporal_series_key,
                    "later_series": later.temporal_series_key,
                },
                status_code=400,
            )
        if earlier.observed_at >= later.observed_at:
            raise AppError(
                code="INVALID_TEMPORAL_ORDER",
                message="Earlier snapshot must have an observation date before the later snapshot",
                status_code=400,
            )

        if earlier.dataset_type == "raster" or later.dataset_type == "raster":
            return TemporalAnalysisService._compare_walous_rasters(
                db,
                project_id=project_id,
                payload=payload,
                earlier=earlier,
                later=later,
            )

        bbox = payload.bbox.model_dump()
        selection_area = TemporalAnalysisService._get_selection_area(db, project_id, payload.area_id)
        selection_geometry = None
        selection_covers_full_area = False
        if selection_area is not None:
            selection_geometry, selection_covers_full_area = VectorFeatureService.constrain_bbox_to_area(
                bbox,
                selection_area.geometry,
            )

        def is_preclipped_to_selection_area(dataset: Dataset) -> bool:
            return bool(
                selection_area
                and VectorFeatureService.can_use_full_area_fast_path(dataset, selection_area.id)
            )

        summaries: dict[UUID, dict[str, Any]] = {}

        def summarize(dataset: Dataset, *, disclose_selection_edge: bool = True) -> dict[str, Any]:
            cached = summaries.get(dataset.id)
            if cached is not None:
                return cached
            kwargs: dict[str, Any] = {
                "dataset": dataset,
                "bbox": bbox,
                "disclose_selection_edge": disclose_selection_edge,
            }
            if selection_area is not None:
                dataset_is_preclipped = is_preclipped_to_selection_area(dataset)
                kwargs["selection_geometry"] = None if dataset_is_preclipped else selection_geometry
                kwargs["full_dataset_area"] = selection_covers_full_area and dataset_is_preclipped
            summary = VectorFeatureService.summarize_features_by_bbox(db, **kwargs)
            summaries[dataset.id] = summary
            return summary

        earlier_summary = summarize(earlier)
        later_summary = summarize(later)
        metric_comparisons = TemporalAnalysisService._compare_summary_metrics(earlier_summary, later_summary)
        if not metric_comparisons:
            raise AppError(
                code="INCOMPATIBLE_TEMPORAL_AGGREGATION",
                message="Dataset snapshots use incompatible aggregation semantics",
                status_code=400,
            )
        primary_key = str(later_summary.get("primary_metric_key") or metric_comparisons[0].metric_key)
        primary_metric = next(
            (metric for metric in metric_comparisons if metric.metric_key == primary_key),
            metric_comparisons[0],
        )
        warnings = [
            warning
            for warning in {earlier_summary.get("warning"), later_summary.get("warning")}
            if warning
        ]

        object_changes, geojson, identity_warnings = TemporalAnalysisService._compare_identity_features(
            db,
            earlier=earlier,
            later=later,
            bbox=bbox,
            preview_limit=payload.preview_limit,
            selection_geometry=(
                None
                if is_preclipped_to_selection_area(earlier) and is_preclipped_to_selection_area(later)
                else selection_geometry
            ),
            earlier_full_dataset_area=(
                selection_covers_full_area
                and is_preclipped_to_selection_area(earlier)
                if selection_area is not None
                else False
            ),
            later_full_dataset_area=(
                selection_covers_full_area
                and is_preclipped_to_selection_area(later)
                if selection_area is not None
                else False
            ),
        )
        warnings.extend(identity_warnings)
        timeline = TemporalAnalysisService._build_timeline(
            db,
            project_id=project_id,
            series_key=earlier.temporal_series_key,
            fallback_datasets=[earlier, later],
            # A timeline point shows values only, so the per-snapshot
            # selection-edge query would be a round trip nobody reads.
            summarize=lambda dataset: summarize(dataset, disclose_selection_edge=False),
        )

        return TemporalComparisonResponse(
            temporal_series_key=earlier.temporal_series_key,
            earlier=TemporalDatasetRef(
                id=earlier.id,
                name=earlier.name,
                observed_at=earlier.observed_at,
                source_version=earlier.source_version,
            ),
            later=TemporalDatasetRef(
                id=later.id,
                name=later.name,
                observed_at=later.observed_at,
                source_version=later.source_version,
            ),
            selection_bbox=payload.bbox,
            selection_area_id=selection_area.id if selection_area is not None else None,
            metric=primary_metric,
            metrics=metric_comparisons,
            timeline=timeline,
            object_changes=object_changes,
            geojson=geojson,
            warnings=warnings,
            generated_at=datetime.now(timezone.utc),
        )

    @staticmethod
    def _get_selection_area(db: Session, project_id: UUID, area_id: UUID | None) -> Area | None:
        if area_id is None:
            return None
        area = db.get(Area, area_id)
        if area is None or area.project_id != project_id:
            raise AppError(code="AREA_NOT_FOUND", message="Area not found", status_code=404)
        return area

    @staticmethod
    def _compare_walous_rasters(
        db: Session,
        *,
        project_id: UUID,
        payload: TemporalComparisonRequest,
        earlier: Dataset,
        later: Dataset,
    ) -> TemporalComparisonResponse:
        if {
            earlier.dataset_type,
            later.dataset_type,
        } != {"raster"} or earlier.source_name != WalousLandCoverService.PROVIDER or later.source_name != WalousLandCoverService.PROVIDER:
            raise AppError(
                code="INCOMPATIBLE_TEMPORAL_DATASET_TYPES",
                message="Raster evolution currently supports only two governed WALOUS land-cover snapshots",
                status_code=400,
            )

        request = ThematicRasterSelectionRequest(bbox=payload.bbox, area_id=payload.area_id)
        summaries: dict[UUID, dict[str, Any]] = {}

        def summarize(dataset: Dataset) -> dict[str, Any]:
            cached = summaries.get(dataset.id)
            if cached is not None:
                return cached
            result = WalousLandCoverService.analyze(db, project_id, dataset.id, request)
            summary = dict(result["summary"])
            summary["warning"] = result.get("limitation_message")
            summaries[dataset.id] = summary
            return summary

        earlier_summary = summarize(earlier)
        later_summary = summarize(later)
        metric_comparisons = TemporalAnalysisService._compare_summary_metrics(earlier_summary, later_summary)
        if not metric_comparisons:
            raise AppError(
                code="INCOMPATIBLE_TEMPORAL_AGGREGATION",
                message="WALOUS snapshots use incompatible aggregation semantics",
                status_code=400,
            )
        primary_key = str(later_summary.get("primary_metric_key") or metric_comparisons[0].metric_key)
        primary_metric = next(
            (metric for metric in metric_comparisons if metric.metric_key == primary_key),
            metric_comparisons[0],
        )
        timeline = TemporalAnalysisService._build_timeline(
            db,
            project_id=project_id,
            series_key=str(earlier.temporal_series_key),
            fallback_datasets=[earlier, later],
            summarize=summarize,
        )
        warnings = [
            "WALOUS-evolutie vergelijkt celgebaseerde landbedekkingsoppervlakten; individuele objectwijzigingen zijn niet beschikbaar.",
        ]
        for summary in (earlier_summary, later_summary):
            limitation = str(summary.get("warning") or "").strip()
            if limitation and limitation not in warnings:
                warnings.append(limitation)
        return TemporalComparisonResponse(
            temporal_series_key=str(earlier.temporal_series_key),
            earlier=TemporalDatasetRef(
                id=earlier.id,
                name=earlier.name,
                observed_at=earlier.observed_at,
                source_version=earlier.source_version,
            ),
            later=TemporalDatasetRef(
                id=later.id,
                name=later.name,
                observed_at=later.observed_at,
                source_version=later.source_version,
            ),
            selection_bbox=payload.bbox,
            selection_area_id=payload.area_id,
            metric=primary_metric,
            metrics=metric_comparisons,
            timeline=timeline,
            object_changes=TemporalObjectChanges(available=False),
            geojson={"type": "FeatureCollection", "features": []},
            warnings=warnings,
            generated_at=datetime.now(timezone.utc),
        )

    @staticmethod
    def _summary_metrics(summary: dict[str, Any]) -> list[dict[str, Any]]:
        configured = summary.get("metrics")
        if isinstance(configured, list) and configured:
            return [item for item in configured if isinstance(item, dict)]
        return [
            {
                "metric_key": summary.get("primary_metric_key") or "primary",
                "metric_label": summary["metric_label"],
                "metric_value": summary["metric_value"],
                "metric_unit": summary["metric_unit"],
                "aggregation_method": summary["aggregation_method"],
                "is_estimate": summary.get("is_estimate", False),
                "warning": summary.get("warning"),
            }
        ]

    @staticmethod
    def _compare_summary_metrics(
        earlier_summary: dict[str, Any],
        later_summary: dict[str, Any],
    ) -> list[TemporalMetricComparison]:
        earlier_metrics = {
            str(item.get("metric_key") or item.get("aggregation_method") or "primary"): item
            for item in TemporalAnalysisService._summary_metrics(earlier_summary)
        }
        comparisons: list[TemporalMetricComparison] = []
        for later_metric in TemporalAnalysisService._summary_metrics(later_summary):
            key = str(later_metric.get("metric_key") or later_metric.get("aggregation_method") or "primary")
            earlier_metric = earlier_metrics.get(key)
            if earlier_metric is None:
                continue
            if (
                earlier_metric.get("aggregation_method") != later_metric.get("aggregation_method")
                or earlier_metric.get("metric_unit") != later_metric.get("metric_unit")
            ):
                continue
            earlier_value = float(earlier_metric.get("metric_value") or 0.0)
            later_value = float(later_metric.get("metric_value") or 0.0)
            absolute_change = later_value - earlier_value
            warning = later_metric.get("warning") or earlier_metric.get("warning")
            comparisons.append(
                TemporalMetricComparison(
                    metric_key=key,
                    label=str(later_metric.get("metric_label") or key),
                    unit=str(later_metric.get("metric_unit") or ""),
                    aggregation_method=str(later_metric.get("aggregation_method") or "feature_count"),
                    earlier_value=earlier_value,
                    later_value=later_value,
                    absolute_change=absolute_change,
                    percent_change=(absolute_change / earlier_value * 100.0) if earlier_value else None,
                    is_estimate=bool(earlier_metric.get("is_estimate") or later_metric.get("is_estimate")),
                    warning=str(warning) if warning else None,
                )
            )
        return comparisons

    @staticmethod
    def _build_timeline(
        db: Session,
        *,
        project_id: UUID,
        series_key: str,
        fallback_datasets: list[Dataset],
        summarize,
    ) -> list[TemporalObservation]:
        if hasattr(db, "query"):
            datasets = (
                db.query(Dataset)
                .filter(Dataset.project_id == project_id)
                .filter(Dataset.temporal_series_key == series_key)
                .filter(Dataset.observed_at.isnot(None))
                .order_by(Dataset.observed_at.asc())
                .all()
            )
        else:
            datasets = fallback_datasets
        ordered = TemporalAnalysisService._canonical_observation_snapshots(datasets)
        observations: list[TemporalObservation] = []
        for dataset in ordered:
            if dataset.observed_at is None:
                continue
            metrics = [
                TemporalObservationMetric(
                    metric_key=str(item.get("metric_key") or item.get("aggregation_method") or "primary"),
                    label=str(item.get("metric_label") or "Meting"),
                    value=float(item.get("metric_value") or 0.0),
                    unit=str(item.get("metric_unit") or ""),
                    aggregation_method=str(item.get("aggregation_method") or "feature_count"),
                    is_estimate=bool(item.get("is_estimate")),
                )
                for item in TemporalAnalysisService._summary_metrics(summarize(dataset))
            ]
            observations.append(
                TemporalObservation(
                    dataset=TemporalDatasetRef(
                        id=dataset.id,
                        name=dataset.name,
                        observed_at=dataset.observed_at,
                        source_version=dataset.source_version,
                    ),
                    metrics=metrics,
                )
            )
        return observations

    @staticmethod
    def _get_temporal_dataset(db: Session, project_id: UUID, dataset_id: UUID, label: str) -> Dataset:
        dataset = db.get(Dataset, dataset_id)
        if not dataset or dataset.project_id != project_id:
            raise AppError(code="DATASET_NOT_FOUND", message=f"{label} dataset not found", status_code=404)
        supported_vector = dataset.dataset_type in {"vector", "geojson"}
        supported_raster = (
            dataset.dataset_type == "raster"
            and dataset.source_name in TemporalAnalysisService.SUPPORTED_RASTER_TEMPORAL_SOURCES
        )
        if not supported_vector and not supported_raster:
            raise AppError(
                code="TEMPORAL_DATASET_NOT_SUPPORTED",
                message="Temporal comparison requires a vector series or a governed WALOUS raster series",
                status_code=400,
            )
        if not dataset.temporal_series_key or not dataset.observed_at:
            raise AppError(
                code="TEMPORAL_METADATA_MISSING",
                message=f"{label} dataset has no explicit temporal series and observation date",
                status_code=400,
            )
        return dataset

    @staticmethod
    def _compare_identity_features(
        db: Session,
        *,
        earlier: Dataset,
        later: Dataset,
        bbox: dict[str, Any],
        preview_limit: int,
        selection_geometry: Any | None = None,
        earlier_full_dataset_area: bool = False,
        later_full_dataset_area: bool = False,
    ) -> tuple[TemporalObjectChanges, dict[str, Any], list[str]]:
        later_config = later.source_metadata if isinstance(later.source_metadata, dict) else {}
        earlier_identity = TemporalAnalysisService._identity_contract(earlier)
        later_identity = TemporalAnalysisService._identity_contract(later)
        if earlier_identity is None or later_identity is None or earlier_identity != later_identity:
            return (
                TemporalObjectChanges(available=False),
                {"type": "FeatureCollection", "features": []},
                ["Wijzigingen van individuele objecten kunnen voor deze bron niet betrouwbaar worden gevolgd."],
            )

        normalized_bbox = VectorFeatureService._normalize_selection_bbox(bbox)
        selection_shape = selection_geometry
        if selection_shape is None:
            selection_shape = ST_MakeEnvelope(
                normalized_bbox["min_x"],
                normalized_bbox["min_y"],
                normalized_bbox["max_x"],
                normalized_bbox["max_y"],
                4326,
            )

        def load(dataset_id: UUID, full_dataset_area: bool) -> list[VectorFeature]:
            query = db.query(VectorFeature).filter(VectorFeature.dataset_id == dataset_id)
            if not full_dataset_area:
                query = query.filter(ST_Intersects(VectorFeature.geometry, selection_shape))
            return (
                query.order_by(VectorFeature.source_feature_id.asc())
                .limit(TemporalAnalysisService.IDENTITY_COMPARISON_LIMIT + 1)
                .all()
            )

        earlier_rows = load(earlier.id, earlier_full_dataset_area)
        later_rows = load(later.id, later_full_dataset_area)
        if (
            len(earlier_rows) > TemporalAnalysisService.IDENTITY_COMPARISON_LIMIT
            or len(later_rows) > TemporalAnalysisService.IDENTITY_COMPARISON_LIMIT
        ):
            return (
                TemporalObjectChanges(available=False),
                {"type": "FeatureCollection", "features": []},
                ["Object-level preview was skipped because the selection exceeds the 5,000 feature safety limit."],
            )

        identity_prefixes = earlier_identity[1]
        if not TemporalAnalysisService._rows_match_identity_contract(earlier_rows, identity_prefixes) or not (
            TemporalAnalysisService._rows_match_identity_contract(later_rows, identity_prefixes)
        ):
            return (
                TemporalObjectChanges(available=False),
                {"type": "FeatureCollection", "features": []},
                ["De geselecteerde objecten bevatten geen volledig verifieerbare stabiele bronidentiteit."],
            )

        earlier_by_id = {str(row.source_feature_id): row for row in earlier_rows if row.source_feature_id}
        later_by_id = {str(row.source_feature_id): row for row in later_rows if row.source_feature_id}
        earlier_ids = set(earlier_by_id)
        later_ids = set(later_by_id)
        added_ids = sorted(later_ids - earlier_ids)
        removed_ids = sorted(earlier_ids - later_ids)
        common_ids = sorted(earlier_ids & later_ids)
        comparison_property = str(later_config.get("comparison_property") or "").strip() or None
        modified_ids: list[str] = []
        unchanged_ids: list[str] = []

        for feature_id in common_ids:
            earlier_row = earlier_by_id[feature_id]
            later_row = later_by_id[feature_id]
            geometry_changed = not to_shape(earlier_row.geometry).equals(to_shape(later_row.geometry))
            value_changed = False
            if comparison_property:
                value_changed = (earlier_row.properties_json or {}).get(comparison_property) != (
                    later_row.properties_json or {}
                ).get(comparison_property)
            (modified_ids if geometry_changed or value_changed else unchanged_ids).append(feature_id)

        features: list[dict[str, Any]] = []
        for change_type, feature_ids, rows in (
            ("added", added_ids, later_by_id),
            ("removed", removed_ids, earlier_by_id),
            ("modified", modified_ids, later_by_id),
        ):
            for feature_id in feature_ids:
                if len(features) >= preview_limit:
                    break
                row = rows[feature_id]
                properties = dict(row.properties_json or {})
                properties.update(
                    {
                        "change_type": change_type,
                        "source_feature_id": feature_id,
                        "earlier_dataset_id": str(earlier.id),
                        "later_dataset_id": str(later.id),
                    }
                )
                if change_type == "modified" and comparison_property:
                    before = (earlier_by_id[feature_id].properties_json or {}).get(comparison_property)
                    after = (later_by_id[feature_id].properties_json or {}).get(comparison_property)
                    properties.update({"value_before": before, "value_after": after})
                    if isinstance(before, (int, float)) and isinstance(after, (int, float)):
                        properties["value_delta"] = after - before
                features.append(
                    {
                        "type": "Feature",
                        "id": str(row.id),
                        "geometry": mapping(to_shape(row.geometry)),
                        "properties": properties,
                    }
                )

        warnings: list[str] = []
        total_changes = len(added_ids) + len(removed_ids) + len(modified_ids)
        if total_changes > preview_limit:
            warnings.append(
                f"The map shows the first {preview_limit} of {total_changes} changed features; counts remain complete."
            )
        return (
            TemporalObjectChanges(
                available=True,
                added_count=len(added_ids),
                removed_count=len(removed_ids),
                modified_count=len(modified_ids),
                unchanged_count=len(unchanged_ids),
            ),
            {"type": "FeatureCollection", "features": features},
            warnings,
        )

    @staticmethod
    def _identity_contract(dataset: Dataset) -> tuple[str, tuple[str, ...]] | None:
        source_metadata = dataset.source_metadata if isinstance(dataset.source_metadata, dict) else {}
        declared_stable = source_metadata.get("identity_stable")
        if declared_stable is False:
            return None

        configured_prefixes = source_metadata.get("identity_prefixes")
        prefixes = tuple(
            sorted(
                {
                    str(value).strip()
                    for value in configured_prefixes
                    if str(value).strip()
                }
            )
        ) if isinstance(configured_prefixes, list) else ()
        if declared_stable is True:
            return str(source_metadata.get("identity_scheme") or "declared_source_feature_id"), prefixes

        provenance = dataset.provenance_metadata if isinstance(dataset.provenance_metadata, dict) else {}
        if (
            dataset.source_name != "grb"
            or not str(dataset.temporal_series_key or "").startswith("grb:")
            or source_metadata.get("authority_level") != "authoritative"
            or not TemporalAnalysisService._has_governed_grb_area_contract(
                source_metadata,
                provenance,
            )
            or provenance.get("operator_tool") not in TemporalAnalysisService.GOVERNED_GRB_IDENTITY_OPERATORS
            or provenance.get("reference_truncated") is not False
        ):
            return None

        if dataset.reference_layer_name == "buildings" and source_metadata.get("collection") == "GRB/GBG":
            prefixes = ("GBG.",)
        else:
            collections = source_metadata.get("collections")
            if not isinstance(collections, list) or not collections:
                return None
            prefixes = tuple(sorted(f"{str(collection)}:{str(collection)}." for collection in collections))
        return "grb_ogc_feature_id", prefixes

    @staticmethod
    def _has_governed_grb_area_contract(
        source_metadata: dict[str, Any],
        provenance: dict[str, Any],
    ) -> bool:
        if source_metadata.get("geometry_clipped_to_area") is True:
            return True

        partition_checksums = provenance.get("partition_checksums")
        artifact_checksum = str(provenance.get("artifact_sha256") or "")
        has_valid_checksum = len(artifact_checksum) == 64 and all(
            character in "0123456789abcdefABCDEF" for character in artifact_checksum
        )
        has_valid_partition_checksums = (
            isinstance(partition_checksums, dict)
            and len(partition_checksums) == 28
            and all(
                len(str(checksum)) == 64
                and all(character in "0123456789abcdefABCDEF" for character in str(checksum))
                for checksum in partition_checksums.values()
            )
        )
        return (
            source_metadata.get("coverage_scope") == "kempen-transport-region"
            and source_metadata.get("scope_type") == "transport_region"
            and source_metadata.get("member_count") == 28
            and source_metadata.get("partition_count") == 28
            and source_metadata.get("partition_strategy")
            in {
                "municipality_bbox_maximum_boundary_intersection",
                "municipality_bbox_maximum_same_dimension_intersection",
            }
            and bool(provenance.get("manifest_path"))
            and bool(provenance.get("source_url") or provenance.get("source_urls"))
            and has_valid_checksum
            and has_valid_partition_checksums
        )

    @staticmethod
    def _rows_match_identity_contract(rows: list[VectorFeature], prefixes: tuple[str, ...]) -> bool:
        identities = [str(row.source_feature_id or "").strip() for row in rows]
        if any(not identity for identity in identities) or len(set(identities)) != len(identities):
            return False
        return not prefixes or all(identity.startswith(prefixes) for identity in identities)