"""Dataset-first LiDAR ingress with explicit representation boundaries.

The gateway never treats a registered map increment as a native sensor scan.
It first preserves one source frame and its labels. Normalization and rolling
map construction are separate, provenance-bearing products.
"""

from __future__ import annotations

import json
import os
from dataclasses import dataclass
from pathlib import Path, PureWindowsPath
from typing import Any, Final, Literal

import numpy as np
import numpy.typing as npt

from k1link.datasets.goose_profile import DEFAULT_GOOSE_PATCHWORK_PROFILE

DATASET_GATEWAY_CATALOG_SCHEMA: Final = "missioncore.dataset-gateway-catalog/v3"
DATASET_ADMISSION_SCHEMA: Final = "missioncore.dataset-admission/v1"
DATASET_PREVIEW_SCHEMA: Final = "missioncore.dataset-native-scan-preview/v1"
DATASET_GROUND_PREVIEW_SCHEMA: Final = "missioncore.dataset-ground-comparison-preview/v2"
DATASET_ROOT_ENV: Final = "MISSIONCORE_DATASET_ROOT"
DATASET_ADMISSION_MANIFEST_ENV: Final = "MISSIONCORE_DATASET_ADMISSION_MANIFEST"
DATASET_PREVIEW_ENV: Final = "MISSIONCORE_DATASET_PREVIEW"
DATASET_GROUND_PREVIEW_ENV: Final = "MISSIONCORE_DATASET_GROUND_PREVIEW"
MAX_STATE_BYTES: Final = 64 * 1024
MAX_PREVIEW_BYTES: Final = 16 * 1024**2
Representation = Literal["native-scan", "normalized-scan", "rolling-local-map"]


class DatasetFrameError(ValueError):
    """A dataset frame cannot satisfy its declared lossless source contract."""


class DatasetAdmissionError(ValueError):
    """A worker admission artifact violates the path-free dataset contract."""


@dataclass(frozen=True)
class DatasetPointFrame:
    """One SemanticKITTI-compatible labeled LiDAR frame.

    GOOSE publishes one LiDAR revolution per ``.bin`` frame. Coordinates and
    remission stay source-native here; no vehicle transform or accumulation is
    silently applied.
    """

    points_xyz_m: npt.NDArray[np.float32]
    remission: npt.NDArray[np.float32]
    semantic_labels: npt.NDArray[np.uint16]
    instance_labels: npt.NDArray[np.uint16]
    representation: Representation = "native-scan"

    @property
    def point_count(self) -> int:
        return int(self.points_xyz_m.shape[0])


def read_semantic_kitti_frame(
    point_path: Path,
    label_path: Path,
    *,
    maximum_points: int = 2_000_000,
) -> DatasetPointFrame:
    """Read one GOOSE/SemanticKITTI XYZI + packed-label frame losslessly."""

    try:
        point_size = point_path.stat().st_size
        label_size = label_path.stat().st_size
        _validate_semantic_kitti_sizes(
            point_size,
            label_size,
            maximum_points=maximum_points,
        )
        point_bytes = point_path.read_bytes()
        label_bytes = label_path.read_bytes()
    except OSError as exc:
        raise DatasetFrameError("dataset point or label file is unavailable") from exc
    return decode_semantic_kitti_frame(
        point_bytes,
        label_bytes,
        maximum_points=maximum_points,
    )


def decode_semantic_kitti_frame(
    point_bytes: bytes,
    label_bytes: bytes,
    *,
    maximum_points: int = 2_000_000,
) -> DatasetPointFrame:
    """Decode one in-memory SemanticKITTI frame without extracting an archive."""

    point_size = len(point_bytes)
    label_size = len(label_bytes)
    point_count = _validate_semantic_kitti_sizes(
        point_size,
        label_size,
        maximum_points=maximum_points,
    )

    try:
        xyzi = np.frombuffer(point_bytes, dtype="<f4").reshape((-1, 4))
        packed_labels = np.frombuffer(label_bytes, dtype="<u4")
    except ValueError as exc:
        raise DatasetFrameError("dataset frame cannot be decoded") from exc
    if not np.isfinite(xyzi).all():
        raise DatasetFrameError("dataset point frame contains non-finite values")

    points = np.ascontiguousarray(xyzi[:, :3], dtype=np.float32)
    remission = np.ascontiguousarray(xyzi[:, 3], dtype=np.float32)
    semantic = np.ascontiguousarray(packed_labels & np.uint32(0xFFFF), dtype=np.uint16)
    instance = np.ascontiguousarray(packed_labels >> np.uint32(16), dtype=np.uint16)
    for values in (points, remission, semantic, instance):
        values.setflags(write=False)
    if points.shape[0] != point_count:
        raise DatasetFrameError("decoded point count differs from the admitted size")
    return DatasetPointFrame(points, remission, semantic, instance)


def _validate_semantic_kitti_sizes(
    point_size: int,
    label_size: int,
    *,
    maximum_points: int,
) -> int:
    if maximum_points <= 0:
        raise DatasetFrameError("maximum_points must be positive")
    if point_size == 0 or point_size % 16:
        raise DatasetFrameError("point frame must contain little-endian float32 XYZI tuples")
    if label_size % 4:
        raise DatasetFrameError("label frame must contain packed little-endian uint32 values")
    point_count = point_size // 16
    if point_count > maximum_points:
        raise DatasetFrameError("dataset point frame exceeds the configured safety limit")
    if label_size // 4 != point_count:
        raise DatasetFrameError("point and label counts do not match")
    return point_count


def _configured_dataset_root() -> Path | None:
    raw = os.environ.get(DATASET_ROOT_ENV, "").strip()
    return Path(raw).expanduser().absolute() if raw else None


def configured_dataset_admission_manifest() -> Path | None:
    raw = os.environ.get(DATASET_ADMISSION_MANIFEST_ENV, "").strip()
    return Path(raw).expanduser().absolute() if raw else None


def configured_dataset_preview() -> Path | None:
    raw = os.environ.get(DATASET_PREVIEW_ENV, "").strip()
    return Path(raw).expanduser().absolute() if raw else None


def configured_dataset_ground_preview() -> Path | None:
    raw = os.environ.get(DATASET_GROUND_PREVIEW_ENV, "").strip()
    return Path(raw).expanduser().absolute() if raw else None


def _is_worker_d_storage(root: Path | None) -> bool:
    if root is None:
        return False
    raw = str(root)
    windows = PureWindowsPath(raw)
    if windows.drive.upper() == "D:":
        return True
    normalized = raw.replace("\\", "/").rstrip("/").lower()
    return normalized == "/mnt/d/ndc_missioncore/datasets" or normalized.startswith(
        "/mnt/d/ndc_missioncore/datasets/"
    )


def dataset_gateway_catalog(
    dataset_root: Path | None = None,
    admission_manifest_path: Path | None = None,
    rellis_preview_path: Path | None = None,
) -> dict[str, object]:
    """Return the path-free, read-only ingress plan and current admission state."""

    root = dataset_root if dataset_root is not None else _configured_dataset_root()
    manifest_path = (
        admission_manifest_path
        if admission_manifest_path is not None
        else configured_dataset_admission_manifest()
    )
    admission: dict[str, Any] | None = None
    admission_error: str | None = None
    if manifest_path is not None:
        try:
            admission = read_dataset_admission_manifest(manifest_path)
        except DatasetAdmissionError:
            admission_error = "worker-manifest-invalid"
    locally_admitted = _is_worker_d_storage(root)
    worker_admitted = bool(admission and admission["storage"]["admitted"])
    storage_admitted = locally_admitted or worker_admitted
    rellis_preview: dict[str, Any] | None = None
    if rellis_preview_path is not None and rellis_preview_path.is_file():
        try:
            candidate = read_dataset_native_scan_preview(rellis_preview_path)
            if candidate.get("source_id") == "rellis-3d/v1.1":
                rellis_preview = candidate
        except DatasetAdmissionError:
            pass
    source_status = (
        str(admission["status"])
        if admission is not None
        else "ready-for-download"
        if storage_admitted
        else "blocked-storage-policy"
    )
    next_action = (
        str(admission["next_action"])
        if admission is not None
        else "repair-worker-admission-manifest"
        if admission_error is not None
        else "download-goose-validation-to-d"
        if storage_admitted
        else "configure-dataset-root-on-worker-d"
    )
    rellis_status = (
        "smoke-ready"
        if rellis_preview is not None
        else "ready-for-smoke"
        if storage_admitted
        else "blocked-storage-policy"
    )
    catalog_next_action = (
        "admit-rellis-ouster-semantickitti-to-worker-d"
        if rellis_preview is not None and source_status == "frame-ready"
        else "build-rellis-official-example-smoke"
        if source_status == "frame-ready"
        else next_action
    )
    return {
        "schema_version": DATASET_GATEWAY_CATALOG_SCHEMA,
        "access": "read-only",
        "storage": {
            "configured": root is not None or manifest_path is not None,
            "required_windows_root": r"D:\NDC_MISSIONCORE\datasets",
            "required_wsl_root": "/mnt/d/NDC_MISSIONCORE/datasets",
            "admitted": storage_admitted,
            "status": "ready" if storage_admitted else "blocked-storage-policy",
            "attestation": (
                "worker-manifest"
                if worker_admitted
                else "local-worker-path"
                if locally_admitted
                else "none"
            ),
            "manifest_valid": admission is not None,
            "path_exposed": False,
        },
        "sources": [
            {
                "source_id": "goose-3d/v2025-08-22",
                "source_kind": "goose",
                "display_name": "GOOSE 3D",
                "role": "primary-offroad-semantic-baseline",
                "license": "CC-BY-SA-4.0",
                "commercial_use": "allowed-with-share-alike",
                "format": "semantickitti-xyzi-label",
                "frame_semantics": "one-lidar-revolution",
                "sensor": "VLS-128",
                "platforms": ["MuCAR-3", "ALICE", "Spot"],
                "annotations": ["semantic-point", "instance-point"],
                "superclasses": [
                    "other",
                    "artificial-structures",
                    "artificial-ground",
                    "natural-ground",
                    "obstacle",
                    "vehicle",
                    "vegetation",
                    "human",
                    "sky",
                ],
                "download": {
                    "automatic": False,
                    "reason": "operator-admitted-large-artifact-only",
                    "smoke_example_mb": None,
                    "primary_scan_archive_gb": 3.3,
                    "label_archive_gb": None,
                    "poses_archive_gb": None,
                    "training_archive_gb": 27.0,
                    "validation_archive_gb": 3.3,
                    "test_archive_gb": 3.3,
                },
                "statistics": {
                    "fragment_count": 8,
                    "annotated_scan_count": 961,
                },
                "admission": {
                    "status": source_status,
                    "native_scan": "ready-after-download",
                    "normalized_scan": "requires-explicit-frame-and-mounting-contract",
                    "rolling_local_map": "requires-pose-timing-and-map-policy",
                    "archive": admission["archive"] if admission is not None else None,
                    "frame": admission["frame"] if admission is not None else None,
                },
            },
            {
                "source_id": "rellis-3d/v1.1",
                "source_kind": "rellis",
                "display_name": "RELLIS-3D",
                "role": "independent-offroad-cross-dataset-check",
                "license": "CC-BY-NC-SA-3.0",
                "commercial_use": "research-only-license-review-required",
                "format": "semantickitti-xyzi-label",
                "frame_semantics": "one-lidar-revolution",
                "sensor": "Ouster OS1 64",
                "platforms": ["Clearpath Warthog"],
                "annotations": ["semantic-point"],
                "superclasses": [
                    "ground",
                    "vegetation",
                    "structure",
                    "obstacle",
                    "vehicle",
                    "human",
                    "water",
                    "ignore",
                ],
                "download": {
                    "automatic": False,
                    "reason": "operator-admitted-large-artifact-only",
                    "smoke_example_mb": 24.0,
                    "primary_scan_archive_gb": 14.0,
                    "label_archive_gb": 0.174,
                    "poses_archive_gb": 0.174,
                    "training_archive_gb": None,
                    "validation_archive_gb": None,
                    "test_archive_gb": None,
                },
                "statistics": {
                    "fragment_count": 5,
                    "annotated_scan_count": 13_556,
                },
                "admission": {
                    "status": rellis_status,
                    "native_scan": (
                        "official-example-compatible"
                        if rellis_preview is not None
                        else "requires-official-example-smoke"
                    ),
                    "normalized_scan": "requires-explicit-frame-and-mounting-contract",
                    "rolling_local_map": "requires-poses-timing-and-map-policy",
                    "archive": None,
                    "frame": (
                        {
                            "frame_id": rellis_preview["frame_id"],
                            "point_count": rellis_preview["source_point_count"],
                            "semantic_class_count": len(rellis_preview["classes"]),
                            "ground_truth_ground_fraction": (
                                sum(rellis_preview["ground_truth_ground"])
                                / rellis_preview["point_count"]
                            ),
                            "preview_point_count": rellis_preview["point_count"],
                            "preview_sha256": None,
                            "preview_available": True,
                        }
                        if rellis_preview is not None
                        else None
                    ),
                },
            },
        ],
        "representations": [
            {
                "id": "native-scan",
                "title": "Одиночный исходный скан",
                "retains": ["xyz", "remission", "semantic-label", "instance-label"],
                "purpose": "dataset-ground-truth-and-sensor-domain",
                "accumulation": False,
            },
            {
                "id": "normalized-scan",
                "title": "Нормализованный sensor-frame скан",
                "retains": ["source-provenance", "point-alignment", "labels"],
                "purpose": "deskew-filter-inference-and-algorithm-comparison",
                "accumulation": False,
            },
            {
                "id": "rolling-local-map",
                "title": "Накопленная локальная карта",
                "retains": ["source-frame-ids", "pose-provenance", "age"],
                "purpose": "stable-operator-view-and-local-planning",
                "accumulation": True,
            },
        ],
        "pipeline": [
            {
                "stage": "decode-and-calibrate",
                "requires": ["native-packets-or-source-frame", "calibration"],
                "produces": "native-scan",
            },
            {
                "stage": "deskew",
                "requires": ["per-point-time", "imu-or-odometry"],
                "produces": "normalized-scan",
            },
            {
                "stage": "bounded-cleanup",
                "requires": ["range-policy", "self-mask", "outlier-policy", "voxel-policy"],
                "produces": "normalized-scan",
            },
            {
                "stage": "ground-and-object-inference",
                "requires": ["normalized-scan", "declared-sensor-height-and-geometry"],
                "produces": "point-aligned-predictions",
            },
            {
                "stage": "pose-registration-and-rolling-map",
                "requires": ["normalized-scan", "pose", "ttl", "voxel-deduplication"],
                "produces": "rolling-local-map",
            },
        ],
        "known_inputs": [
            {
                "source_id": "current-recorded-lidar/vendor-map",
                "representation": "vendor-mapped-increment",
                "native_scan": False,
                "per_point_time": False,
                "ring_or_line": False,
                "admitted_for_patchworkpp": False,
                "reason": "post-lio-map-product-cannot-be-reconstructed-as-a-native-scan",
            }
        ],
        "next_action": catalog_next_action,
    }


def read_dataset_admission_manifest(path: Path) -> dict[str, Any]:
    document = _bounded_json_object(path, MAX_STATE_BYTES, "dataset admission manifest")
    if (
        document.get("schema_version") != DATASET_ADMISSION_SCHEMA
        or document.get("source_id") != "goose-3d/v2025-08-22"
        or set(document)
        != {
            "schema_version",
            "source_id",
            "observed_at_utc",
            "status",
            "storage",
            "archive",
            "license",
            "frame",
            "next_action",
        }
    ):
        raise DatasetAdmissionError("dataset admission manifest identity is incompatible")
    status = document["status"]
    if status not in {"downloading", "downloaded", "verifying", "verified", "frame-ready"}:
        raise DatasetAdmissionError("dataset admission status is incompatible")
    storage = _object(document["storage"], "storage")
    if (
        set(storage) != {"policy", "admitted", "canonical_root", "path_exposed"}
        or storage.get("policy") != "worker-d-only"
        or storage.get("admitted") is not True
        or storage.get("canonical_root") is not True
        or storage.get("path_exposed") is not False
    ):
        raise DatasetAdmissionError("dataset storage admission is incompatible")
    archive = _object(document["archive"], "archive")
    if (
        set(archive)
        != {
            "filename",
            "source_url",
            "bytes_transferred",
            "total_bytes",
            "size_bytes",
            "sha256",
            "integrity",
            "vendor_checksum_available",
        }
        or archive.get("filename") != "goose_3d_val.zip"
        or archive.get("source_url") != "https://goose-dataset.de/storage/goose_3d_val.zip"
        or archive.get("vendor_checksum_available") is not False
    ):
        raise DatasetAdmissionError("dataset archive admission is incompatible")
    transferred = _nonnegative_integer(archive["bytes_transferred"], "bytes_transferred")
    total = _positive_integer(archive["total_bytes"], "total_bytes")
    if transferred > total:
        raise DatasetAdmissionError("dataset download progress is incompatible")
    size = archive["size_bytes"]
    digest = archive["sha256"]
    if size is not None:
        _positive_integer(size, "size_bytes")
    if digest is not None and (
        not isinstance(digest, str)
        or len(digest) != 64
        or any(character not in "0123456789abcdef" for character in digest)
    ):
        raise DatasetAdmissionError("dataset archive digest is incompatible")
    license_value = _object(document["license"], "license")
    if (
        set(license_value) != {"spdx", "artifact_present"}
        or license_value.get("spdx") != "CC-BY-SA-4.0"
        or not isinstance(license_value.get("artifact_present"), bool)
    ):
        raise DatasetAdmissionError("dataset license admission is incompatible")
    frame = document["frame"]
    if status == "frame-ready":
        _validate_frame_admission(_object(frame, "frame"))
    elif frame is not None:
        raise DatasetAdmissionError("dataset frame must be absent before frame-ready")
    for key in ("observed_at_utc", "next_action"):
        if not isinstance(document[key], str) or not document[key]:
            raise DatasetAdmissionError(f"{key} is incompatible")
    return document


def read_dataset_native_scan_preview(path: Path) -> dict[str, Any]:
    document = _bounded_json_object(path, MAX_PREVIEW_BYTES, "dataset preview")
    identity = (document.get("schema_version"), document.get("source_id"))
    if (
        identity
        not in {
            (DATASET_PREVIEW_SCHEMA, "goose-3d/v2025-08-22"),
            ("missioncore.dataset-native-scan-preview/v2", "rellis-3d/v1.1"),
        }
        or document.get("representation") != "native-scan"
        or document.get("sampling") != "deterministic-even-index"
    ):
        raise DatasetAdmissionError("dataset preview identity is incompatible")
    point_count = _positive_integer(document.get("point_count"), "point_count")
    source_point_count = _positive_integer(document.get("source_point_count"), "source_point_count")
    if point_count > 50_000 or point_count > source_point_count:
        raise DatasetAdmissionError("dataset preview point count is incompatible")
    points = document.get("points_xyz_m")
    remission = document.get("remission_0_to_255")
    semantic_ids = document.get("semantic_label_ids")
    semantic_rgb = document.get("semantic_rgb_0_to_255")
    ground = document.get("ground_truth_ground")
    evaluated = (
        document.get("evaluation_mask")
        if identity[1] == "rellis-3d/v1.1"
        else [1] * point_count
    )
    if (
        not isinstance(points, list)
        or len(points) != point_count
        or not isinstance(remission, list)
        or len(remission) != point_count
        or not isinstance(semantic_ids, list)
        or len(semantic_ids) != point_count
        or not isinstance(semantic_rgb, list)
        or len(semantic_rgb) != point_count * 3
        or not isinstance(ground, list)
        or len(ground) != point_count
        or not isinstance(evaluated, list)
        or len(evaluated) != point_count
    ):
        raise DatasetAdmissionError("dataset preview arrays are not point-aligned")
    for point in points:
        if (
            not isinstance(point, list)
            or len(point) != 3
            or any(
                not isinstance(value, (int, float))
                or isinstance(value, bool)
                or not np.isfinite(value)
                for value in point
            )
        ):
            raise DatasetAdmissionError("dataset preview point is incompatible")
    for values, maximum, label in (
        (remission, 255, "remission"),
        (semantic_ids, 65_535, "semantic label"),
        (semantic_rgb, 255, "semantic color"),
        (ground, 1, "ground mask"),
        (evaluated, 1, "evaluation mask"),
    ):
        if any(
            not isinstance(value, int) or isinstance(value, bool) or not 0 <= value <= maximum
            for value in values
        ):
            raise DatasetAdmissionError(f"dataset preview {label} is incompatible")
    classes = document.get("classes")
    if not isinstance(classes, list) or len(classes) > 64:
        raise DatasetAdmissionError("dataset preview class catalog is incompatible")
    safety = _object(document.get("safety"), "safety")
    expected_safety = {
        "visualization_only": True,
        "navigation_or_safety_accepted": False,
    }
    if identity[1] == "rellis-3d/v1.1":
        expected_safety["compatibility_smoke_only"] = True
    if safety != expected_safety:
        raise DatasetAdmissionError("dataset preview safety boundary is incompatible")
    if not isinstance(document.get("frame_id"), str) or not document["frame_id"]:
        raise DatasetAdmissionError("dataset preview frame id is incompatible")
    if identity[1] == "rellis-3d/v1.1":
        _validate_rellis_preview_metadata(document, classes)
    return document


def _validate_rellis_preview_metadata(
    document: dict[str, Any],
    classes: list[Any],
) -> None:
    coordinate_frame = _object(document.get("coordinate_frame"), "coordinate_frame")
    if coordinate_frame != {
        "frame_id": "sensor/lidar/os1",
        "handedness": "right",
        "x": "forward",
        "y": "left",
        "z": "up",
        "transform_applied": False,
    }:
        raise DatasetAdmissionError("RELLIS coordinate frame is incompatible")
    policy = _object(document.get("ground_policy"), "ground_policy")
    if (
        policy.get("schema_version") != "missioncore.rellis-ground-target-policy/v1"
        or set(policy) != {"schema_version", "ground", "non_ground", "ignore"}
        or any(
            not isinstance(policy.get(key), list)
            or any(not isinstance(value, str) or not value for value in policy[key])
            for key in ("ground", "non_ground", "ignore")
        )
    ):
        raise DatasetAdmissionError("RELLIS ground target policy is incompatible")
    for item in classes:
        value = _object(item, "class")
        if (
            value.get("ground_target") not in {"ground", "non-ground", "ignore"}
            or not isinstance(value.get("label_id"), int)
            or not isinstance(value.get("class_name"), str)
            or not isinstance(value.get("hex"), str)
            or not isinstance(value.get("source_point_count"), int)
        ):
            raise DatasetAdmissionError("RELLIS class catalog is incompatible")
    evidence = _object(document.get("source_evidence"), "source_evidence")
    if (
        set(evidence)
        != {
            "repository_url",
            "repository_commit",
            "label_config_sha256",
            "point_sha256",
            "label_sha256",
            "license",
        }
        or evidence.get("repository_url") != "https://github.com/unmannedlab/RELLIS-3D"
        or evidence.get("repository_commit")
        != "c17a118fcaed1559f03cc32cc3a91dedc557f8b8"
        or evidence.get("label_config_sha256")
        != "573379a232ac561805987466c391a61fd5ad338be7fb9c4c2842f3f28067e0ad"
        or evidence.get("point_sha256")
        != "ed81a9c3636d55b17d78058c72545d5d22419beecf174d50596d23ae178752af"
        or evidence.get("label_sha256")
        != "9b8c65b710873e931af4ac6dfc7d3dd2298696514ab721e50300bd55ad5b634e"
        or evidence.get("license") != "CC-BY-NC-SA-3.0"
    ):
        raise DatasetAdmissionError("RELLIS source evidence is incompatible")


def read_dataset_ground_preview(path: Path) -> dict[str, Any]:
    document = _bounded_json_object(path, MAX_PREVIEW_BYTES, "dataset ground preview")
    if (
        document.get("schema_version") != DATASET_GROUND_PREVIEW_SCHEMA
        or document.get("source_id") != "goose-3d/v2025-08-22"
        or document.get("sampling") != "deterministic-even-index"
    ):
        raise DatasetAdmissionError("dataset ground preview identity is incompatible")
    point_count = _positive_integer(document.get("point_count"), "point_count")
    if point_count > 50_000:
        raise DatasetAdmissionError("dataset ground preview point count is incompatible")
    for key in (
        "current_ground",
        "patchwork_ground",
        "patchwork_assigned",
        "ground_truth_ground",
        "evaluated",
        "current_disagreement",
        "patchwork_disagreement",
    ):
        values = document.get(key)
        if (
            not isinstance(values, list)
            or len(values) != point_count
            or any(
                not isinstance(value, int) or isinstance(value, bool) or value not in (0, 1)
                for value in values
            )
        ):
            raise DatasetAdmissionError(f"dataset ground preview {key} is incompatible")
    metrics_by_provider = _object(document.get("metrics"), "metrics")
    if set(metrics_by_provider) != {"current", "patchworkpp"}:
        raise DatasetAdmissionError("dataset ground provider metrics are incompatible")
    expected_metrics = {
        "true_positive",
        "false_positive",
        "false_negative",
        "true_negative",
        "precision",
        "recall",
        "f1",
        "ground_iou",
        "accuracy",
        "artificial_ground_recall",
        "natural_ground_recall",
        "obstacle_non_ground_recall",
    }
    for provider_id in ("current", "patchworkpp"):
        metrics = _object(metrics_by_provider[provider_id], f"metrics.{provider_id}")
        if set(metrics) != expected_metrics:
            raise DatasetAdmissionError("dataset ground metrics are incompatible")
        for key, value in metrics.items():
            if key in {"true_positive", "false_positive", "false_negative", "true_negative"}:
                _nonnegative_integer(value, f"metrics.{provider_id}.{key}")
            elif (
                not isinstance(value, (int, float))
                or isinstance(value, bool)
                or not np.isfinite(value)
                or not 0 <= value <= 1
            ):
                raise DatasetAdmissionError(
                    f"dataset ground metric {provider_id}.{key} is incompatible"
                )
    latency = _object(document.get("latency_ms"), "latency_ms")
    if set(latency) != {"current", "patchworkpp"}:
        raise DatasetAdmissionError("dataset ground latency providers are incompatible")
    for provider_id, value in latency.items():
        if (
            not isinstance(value, (int, float))
            or isinstance(value, bool)
            or not np.isfinite(value)
            or value < 0
        ):
            raise DatasetAdmissionError(f"dataset ground latency {provider_id} is incompatible")
    providers = _object(document.get("providers"), "providers")
    if set(providers) != {"current", "patchworkpp"}:
        raise DatasetAdmissionError("dataset ground providers are incompatible")
    current_provider = _object(providers["current"], "providers.current")
    if (
        set(current_provider) != {"provider_id", "implementation_sha256", "ground_truth"}
        or current_provider.get("provider_id") != "missioncore-local-percentile-ground/v1"
        or current_provider.get("ground_truth") is not False
    ):
        raise DatasetAdmissionError("dataset ground provider is incompatible")
    digest = current_provider.get("implementation_sha256")
    if (
        not isinstance(digest, str)
        or len(digest) != 64
        or any(character not in "0123456789abcdef" for character in digest)
    ):
        raise DatasetAdmissionError("dataset ground provider digest is incompatible")
    patchwork_provider = _object(providers["patchworkpp"], "providers.patchworkpp")
    if (
        set(patchwork_provider)
        != {
            "provider_id",
            "source_url",
            "source_tag",
            "source_commit",
            "binding_version",
            "binary_sha256",
            "platform",
            "machine",
            "ground_truth",
        }
        or patchwork_provider.get("provider_id") != "patchworkpp/v1.4.1"
        or patchwork_provider.get("source_tag") != "v1.4.1"
        or patchwork_provider.get("source_commit") != "3e6903a1d5537a4cc2ace897b0bbb98a92d6014c"
        or patchwork_provider.get("ground_truth") is not False
    ):
        raise DatasetAdmissionError("dataset Patchwork++ provider is incompatible")
    binary_digest = patchwork_provider.get("binary_sha256")
    if (
        not isinstance(binary_digest, str)
        or len(binary_digest) != 64
        or any(character not in "0123456789abcdef" for character in binary_digest)
    ):
        raise DatasetAdmissionError("dataset Patchwork++ binary digest is incompatible")
    assigned_fraction = document.get("patchwork_assigned_fraction")
    if (
        not isinstance(assigned_fraction, (int, float))
        or isinstance(assigned_fraction, bool)
        or not np.isfinite(assigned_fraction)
        or not 0 <= assigned_fraction <= 1
    ):
        raise DatasetAdmissionError("dataset Patchwork++ assigned fraction is incompatible")
    input_profile = _object(document.get("input_profile"), "input_profile")
    if input_profile != DEFAULT_GOOSE_PATCHWORK_PROFILE.to_dict():
        raise DatasetAdmissionError("dataset Patchwork++ input profile is incompatible")
    safety = _object(document.get("safety"), "safety")
    if safety != {
        "qualification_only": True,
        "navigation_or_safety_accepted": False,
    }:
        raise DatasetAdmissionError("dataset ground safety boundary is incompatible")
    if not isinstance(document.get("frame_id"), str) or not document["frame_id"]:
        raise DatasetAdmissionError("dataset ground frame id is incompatible")
    return document


def _validate_frame_admission(frame: dict[str, Any]) -> None:
    if (
        set(frame)
        != {
            "frame_id",
            "representation",
            "point_count",
            "semantic_class_count",
            "ground_truth_ground_points",
            "ground_truth_ground_fraction",
            "preview_point_count",
            "preview_sha256",
            "preview_available",
        }
        or frame.get("representation") != "native-scan"
        or frame.get("preview_available") is not True
    ):
        raise DatasetAdmissionError("dataset frame admission is incompatible")
    point_count = _positive_integer(frame["point_count"], "frame.point_count")
    ground_count = _nonnegative_integer(
        frame["ground_truth_ground_points"], "frame.ground_truth_ground_points"
    )
    if ground_count > point_count:
        raise DatasetAdmissionError("dataset ground-truth count is incompatible")
    for key in ("semantic_class_count", "preview_point_count"):
        value = _positive_integer(frame[key], key)
        if value > point_count:
            raise DatasetAdmissionError(f"{key} is incompatible")
    fraction = frame["ground_truth_ground_fraction"]
    if (
        not isinstance(fraction, (int, float))
        or isinstance(fraction, bool)
        or not 0 <= fraction <= 1
    ):
        raise DatasetAdmissionError("dataset ground-truth fraction is incompatible")
    digest = frame["preview_sha256"]
    if (
        not isinstance(digest, str)
        or len(digest) != 64
        or any(character not in "0123456789abcdef" for character in digest)
    ):
        raise DatasetAdmissionError("dataset preview digest is incompatible")
    if not isinstance(frame["frame_id"], str) or not frame["frame_id"]:
        raise DatasetAdmissionError("dataset frame id is incompatible")


def _bounded_json_object(path: Path, maximum_bytes: int, label: str) -> dict[str, Any]:
    try:
        if not path.is_file() or not 0 < path.stat().st_size <= maximum_bytes:
            raise DatasetAdmissionError(f"{label} size is incompatible")
        document = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise DatasetAdmissionError(f"{label} cannot be decoded") from exc
    return _object(document, label)


def _object(value: object, label: str) -> dict[str, Any]:
    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
        raise DatasetAdmissionError(f"{label} must be an object")
    return value


def _positive_integer(value: object, label: str) -> int:
    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
        raise DatasetAdmissionError(f"{label} must be a positive integer")
    return value


def _nonnegative_integer(value: object, label: str) -> int:
    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
        raise DatasetAdmissionError(f"{label} must be a non-negative integer")
    return value
