gridforge-spatial 0.1.0__py3-none-any.whl

gridforge/grid/spec.py

@@ -0,0 +1,209 @@
+"""Validated, deterministic canonical grid specifications."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from decimal import ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, Decimal, InvalidOperation
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pyproj import CRS
+
+from gridforge.errors import GridSpecError
+
+_SPEC_KEYS = {"crs", "cell_size", "bounds", "origin", "boundary_tolerance"}
+_BOUND_KEYS = {"min_x", "min_y", "max_x", "max_y"}
+_ORIGIN_KEYS = {"x", "y"}
+
+
+def _decimal(value: Any, label: str) -> Decimal:
+    if isinstance(value, bool):
+        raise GridSpecError(f"{label} must be a finite number")
+    try:
+        result = Decimal(str(value))
+    except (InvalidOperation, ValueError):
+        raise GridSpecError(f"{label} must be a finite number") from None
+    if not result.is_finite():
+        raise GridSpecError(f"{label} must be a finite number")
+    return result
+
+
+def _text(value: Decimal) -> str:
+    normalized = value.normalize()
+    if normalized == normalized.to_integral_value():
+        return str(normalized.quantize(Decimal(1)))
+    return format(normalized, "f")
+
+
+def _floor(value: Decimal) -> int:
+    return int(value.to_integral_value(rounding=ROUND_FLOOR))
+
+
+def _ceil(value: Decimal) -> int:
+    return int(value.to_integral_value(rounding=ROUND_CEILING))
+
+
+def _require_mapping(value: Any, label: str, allowed: set[str]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise GridSpecError(f"{label} must be a mapping")
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise GridSpecError(f"unknown {label} key(s): {', '.join(unknown)}")
+    return value
+
+
+@dataclass(frozen=True)
+class Bounds:
+    min_x: Decimal
+    min_y: Decimal
+    max_x: Decimal
+    max_y: Decimal
+
+
+@dataclass(frozen=True)
+class Origin:
+    x: Decimal
+    y: Decimal
+
+
+@dataclass(frozen=True)
+class GridSpec:
+    """A square grid anchored to an explicit top-left cell-corner origin.
+
+    Coordinates and ``cell_size`` use the units of the projected CRS. Row
+    indices increase south and column indices increase east. Requested bounds
+    include every cell with positive-area overlap, expanding out to cell edges.
+    """
+
+    crs: CRS
+    cell_size: Decimal
+    bounds: Bounds
+    origin: Origin
+    boundary_tolerance: Decimal = Decimal("1e-9")
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> GridSpec:
+        """Load a grid specification from a YAML file."""
+        try:
+            value = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+        except (OSError, yaml.YAMLError) as exc:
+            raise GridSpecError(f"cannot read grid specification {path}: {exc}") from exc
+        return cls.from_mapping(value)
+
+    @classmethod
+    def from_mapping(cls, value: Any) -> GridSpec:
+        """Parse and validate a mapping with explicit CRS, bounds, and origin."""
+        data = _require_mapping(value, "grid specification", _SPEC_KEYS)
+        missing = sorted(_SPEC_KEYS - {"boundary_tolerance"} - set(data))
+        if missing:
+            raise GridSpecError(f"missing grid specification key(s): {', '.join(missing)}")
+
+        try:
+            crs = CRS.from_user_input(data["crs"])
+        except Exception as exc:
+            raise GridSpecError(f"invalid CRS: {data['crs']!r}") from exc
+        if not crs.is_projected:
+            raise GridSpecError("canonical grid CRS must be projected")
+
+        cell_size = _decimal(data["cell_size"], "cell_size")
+        if cell_size <= 0:
+            raise GridSpecError("cell_size must be greater than zero")
+
+        bounds_data = _require_mapping(data["bounds"], "bounds", _BOUND_KEYS)
+        origin_data = _require_mapping(data["origin"], "origin", _ORIGIN_KEYS)
+        if set(bounds_data) != _BOUND_KEYS:
+            raise GridSpecError("bounds must define min_x, min_y, max_x, and max_y")
+        if set(origin_data) != _ORIGIN_KEYS:
+            raise GridSpecError("origin must define x and y")
+
+        bounds = Bounds(**{key: _decimal(bounds_data[key], f"bounds.{key}") for key in _BOUND_KEYS})
+        origin = Origin(
+            x=_decimal(origin_data["x"], "origin.x"),
+            y=_decimal(origin_data["y"], "origin.y"),
+        )
+        if bounds.min_x >= bounds.max_x or bounds.min_y >= bounds.max_y:
+            raise GridSpecError("bounds must have positive width and height")
+
+        tolerance = _decimal(data.get("boundary_tolerance", "1e-9"), "boundary_tolerance")
+        if tolerance < 0 or tolerance * 2 >= cell_size:
+            raise GridSpecError("boundary_tolerance must be nonnegative and less than half a cell")
+
+        return cls(crs, cell_size, bounds, origin, tolerance)
+
+    @property
+    def crs_id(self) -> str:
+        """Return a stable authority identifier or normalized WKT for the CRS."""
+        authority = self.crs.to_authority()
+        if authority:
+            return f"{authority[0]}:{authority[1]}"
+        return self.crs.to_wkt(version="WKT2_2019", pretty=False)
+
+    @property
+    def index_extent(self) -> tuple[int, int, int, int]:
+        """Return inclusive ``(row_start, row_end, col_start, col_end)``."""
+        row_start = _floor((self.origin.y - self.bounds.max_y) / self.cell_size)
+        row_end = _ceil((self.origin.y - self.bounds.min_y) / self.cell_size) - 1
+        col_start = _floor((self.bounds.min_x - self.origin.x) / self.cell_size)
+        col_end = _ceil((self.bounds.max_x - self.origin.x) / self.cell_size) - 1
+        return row_start, row_end, col_start, col_end
+
+    @property
+    def fingerprint(self) -> str:
+        """Hash the normalized CRS, grid spacing, origin, and indexed extent."""
+        row_start, row_end, col_start, col_end = self.index_extent
+        identity = {
+            "cell_size": _text(self.cell_size),
+            "col_extent": [col_start, col_end],
+            "crs": self.crs_id,
+            "origin": [_text(self.origin.x), _text(self.origin.y)],
+            "row_extent": [row_start, row_end],
+            "schema": "gridforge-grid-v1",
+        }
+        canonical = json.dumps(identity, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    def cell_index(self, x: float, y: float) -> tuple[int, int] | None:
+        """Return the containing ``(row, column)`` or ``None`` outside the grid.
+
+        Cells use ``[left, right) × (bottom, top]``. Coordinates within the
+        configured tolerance of an anchored grid line are snapped to that line.
+        """
+        try:
+            x_value = _decimal(x, "x")
+            y_value = _decimal(y, "y")
+        except GridSpecError:
+            return None
+        col_position = (x_value - self.origin.x) / self.cell_size
+        row_position = (self.origin.y - y_value) / self.cell_size
+        col_position = self._snap_index(col_position)
+        row_position = self._snap_index(row_position)
+        column = int(col_position.to_integral_value(rounding=ROUND_FLOOR))
+        row = int(row_position.to_integral_value(rounding=ROUND_FLOOR))
+        row_start, row_end, col_start, col_end = self.index_extent
+        if row_start <= row <= row_end and col_start <= column <= col_end:
+            return row, column
+        return None
+
+    def _snap_index(self, value: Decimal) -> Decimal:
+        nearest = value.to_integral_value(rounding=ROUND_HALF_UP)
+        if abs(value - nearest) * self.cell_size <= self.boundary_tolerance:
+            return nearest
+        return value
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return JSON-compatible normalized grid specification metadata."""
+        return {
+            "crs": self.crs_id,
+            "cell_size": _text(self.cell_size),
+            "bounds": {
+                "min_x": _text(self.bounds.min_x),
+                "min_y": _text(self.bounds.min_y),
+                "max_x": _text(self.bounds.max_x),
+                "max_y": _text(self.bounds.max_y),
+            },
+            "origin": {"x": _text(self.origin.x), "y": _text(self.origin.y)},
+            "boundary_tolerance": _text(self.boundary_tolerance),
+        }

gridforge/io/__init__.py

@@ -0,0 +1 @@
+"""Spatial dataset input and output helpers."""

gridforge/io/datasets.py

@@ -0,0 +1,317 @@
+"""Explicit-CRS inspection and loading for spatial source datasets."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Literal
+
+import geopandas as gpd
+import numpy as np
+import pandas as pd
+import pyarrow.parquet as pq
+import rasterio
+from pyproj import CRS
+from shapely.geometry import Point
+
+from gridforge.errors import DatasetError
+from gridforge.grid.spec import GridSpec
+
+_RASTER_SUFFIXES = {".tif", ".tiff", ".vrt", ".img", ".asc", ".bil", ".grd"}
+_VECTOR_SUFFIXES = {".geojson", ".json", ".gpkg", ".shp", ".gml", ".fgb"}
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    """Spatial metadata reported by :func:`inspect_dataset`."""
+
+    path: str
+    kind: Literal["vector", "table", "raster"]
+    geometry_type: str | None
+    crs: str
+    feature_count: int | None
+    band_count: int | None
+    bounds: tuple[float, float, float, float] | None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def _crs_label(crs: CRS) -> str:
+    authority = crs.to_authority()
+    return f"{authority[0]}:{authority[1]}" if authority else crs.to_wkt("WKT2_2019", pretty=False)
+
+
+def _resolved_crs(embedded: object | None, source_crs: str | CRS | None) -> CRS:
+    parsed_embedded: CRS | None = None
+    if embedded is not None:
+        try:
+            parsed_embedded = CRS.from_user_input(embedded)
+        except Exception as exc:
+            raise DatasetError(f"embedded source CRS is invalid: {embedded!r}") from exc
+    if parsed_embedded is None:
+        if source_crs is None:
+            raise DatasetError("source CRS is unknown; provide --source-crs explicitly")
+        try:
+            return CRS.from_user_input(source_crs)
+        except Exception as exc:
+            raise DatasetError(f"invalid explicit source CRS: {source_crs!r}") from exc
+    if source_crs is not None:
+        try:
+            requested = CRS.from_user_input(source_crs)
+        except Exception as exc:
+            raise DatasetError(f"invalid explicit source CRS: {source_crs!r}") from exc
+        if not parsed_embedded.equals(requested):
+            raise DatasetError("explicit source CRS conflicts with embedded CRS")
+    return parsed_embedded
+
+
+def _read_table(path: Path) -> pd.DataFrame:
+    try:
+        if path.suffix.lower() == ".csv":
+            return pd.read_csv(path)
+        if path.suffix.lower() == ".parquet":
+            return pd.read_parquet(path)
+    except Exception as exc:
+        raise DatasetError(f"cannot read tabular dataset {path}: {exc}") from exc
+    raise DatasetError(f"unsupported tabular input format: {path.suffix or '<none>'}")
+
+
+def _table_coordinates(
+    table: pd.DataFrame,
+    *,
+    x_column: str,
+    y_column: str,
+) -> tuple[np.ndarray, np.ndarray]:
+    missing = [name for name in (x_column, y_column) if name not in table.columns]
+    if missing:
+        raise DatasetError(f"point table is missing coordinate column(s): {', '.join(missing)}")
+    try:
+        x_values = pd.to_numeric(table[x_column], errors="raise").to_numpy(dtype=float)
+        y_values = pd.to_numeric(table[y_column], errors="raise").to_numpy(dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise DatasetError("point coordinates must be numeric") from exc
+    if not np.isfinite(x_values).all() or not np.isfinite(y_values).all():
+        raise DatasetError("point coordinates must be finite and non-null")
+    return x_values, y_values
+
+
+def _is_geoparquet(path: Path) -> bool:
+    if path.suffix.lower() != ".parquet":
+        return False
+    try:
+        metadata = pq.read_schema(path).metadata or {}
+    except Exception as exc:
+        raise DatasetError(f"cannot inspect Parquet dataset {path}: {exc}") from exc
+    return b"geo" in metadata
+
+
+def _read_geodataframe(path: Path) -> gpd.GeoDataFrame:
+    try:
+        if path.suffix.lower() == ".parquet" and _is_geoparquet(path):
+            return gpd.read_parquet(path)
+        if path.suffix.lower() in _VECTOR_SUFFIXES:
+            return gpd.read_file(path)
+    except Exception as exc:
+        raise DatasetError(f"cannot read vector dataset {path}: {exc}") from exc
+    raise DatasetError(f"unsupported vector input format: {path.suffix or '<none>'}")
+
+
+def _bounds_tuple(values: object) -> tuple[float, float, float, float] | None:
+    array = np.asarray(values, dtype=float)
+    if array.size != 4 or not np.isfinite(array).all():
+        return None
+    return tuple(float(value) for value in array)  # type: ignore[return-value]
+
+
+def inspect_dataset(
+    path: str | Path,
+    *,
+    source_crs: str | CRS | None = None,
+    x_column: str = "x",
+    y_column: str = "y",
+) -> DatasetInfo:
+    """Inspect vector, coordinate-table, or raster input without guessing CRS."""
+    input_path = Path(path)
+    suffix = input_path.suffix.lower()
+    if suffix in _RASTER_SUFFIXES:
+        try:
+            with rasterio.open(input_path) as dataset:
+                crs = _resolved_crs(dataset.crs, source_crs)
+                return DatasetInfo(
+                    str(input_path),
+                    "raster",
+                    "Raster",
+                    _crs_label(crs),
+                    None,
+                    dataset.count,
+                    _bounds_tuple(dataset.bounds),
+                )
+        except DatasetError:
+            raise
+        except Exception as exc:
+            raise DatasetError(f"cannot inspect raster dataset {input_path}: {exc}") from exc
+
+    if suffix == ".csv" or (suffix == ".parquet" and not _is_geoparquet(input_path)):
+        table = _read_table(input_path)
+        x_values, y_values = _table_coordinates(table, x_column=x_column, y_column=y_column)
+        crs = _resolved_crs(None, source_crs)
+        if not len(table):
+            bounds = None
+        else:
+            bounds = (
+                float(x_values.min()),
+                float(y_values.min()),
+                float(x_values.max()),
+                float(y_values.max()),
+            )
+        return DatasetInfo(
+            str(input_path), "table", "Point", _crs_label(crs), len(table), None, bounds
+        )
+
+    vector = _read_geodataframe(input_path)
+    crs = _resolved_crs(vector.crs, source_crs)
+    geometry_types = sorted({str(value) for value in vector.geometry.geom_type.dropna().unique()})
+    geometry_type = ", ".join(geometry_types) if geometry_types else None
+    bounds = _bounds_tuple(vector.total_bounds) if not vector.empty else None
+    return DatasetInfo(
+        str(input_path),
+        "vector",
+        geometry_type,
+        _crs_label(crs),
+        len(vector),
+        None,
+        bounds,
+    )
+
+
+def load_vector(
+    path: str | Path,
+    *,
+    source_crs: str | CRS | None = None,
+) -> gpd.GeoDataFrame:
+    """Load a supported vector file and require an explicit, consistent CRS."""
+    input_path = Path(path)
+    vector = _read_geodataframe(input_path)
+    crs = _resolved_crs(vector.crs, source_crs)
+    if vector.crs is None:
+        vector = vector.set_crs(crs)
+    return vector
+
+
+def load_points(
+    path: str | Path,
+    *,
+    x_column: str = "x",
+    y_column: str = "y",
+    source_crs: str | CRS | None = None,
+) -> gpd.GeoDataFrame:
+    """Load point geometry or an x/y table with an explicit source CRS."""
+    input_path = Path(path)
+    if input_path.suffix.lower() in {".csv", ".parquet"} and not _is_geoparquet(input_path):
+        table = _read_table(input_path)
+        crs = _resolved_crs(None, source_crs)
+        x_values, y_values = _table_coordinates(table, x_column=x_column, y_column=y_column)
+        result = gpd.GeoDataFrame(
+            table.copy(),
+            geometry=[Point(x, y) for x, y in zip(x_values, y_values, strict=True)],
+            crs=crs,
+        )
+    else:
+        result = load_vector(input_path, source_crs=source_crs)
+        if result.geometry.isna().any() or result.geometry.is_empty.any():
+            raise DatasetError("point dataset contains null or empty geometries")
+        if not result.geometry.geom_type.eq("Point").all():
+            raise DatasetError("point alignment requires Point geometries")
+    if result.geometry.isna().any() or result.geometry.is_empty.any():
+        raise DatasetError("point dataset contains null or empty geometries")
+    if not result.geometry.geom_type.eq("Point").all():
+        raise DatasetError("point alignment requires Point geometries")
+    return result
+
+
+def write_dataset(dataset: gpd.GeoDataFrame, path: str | Path) -> Path:
+    """Write one validated aligned dataset as GridForge GeoParquet.
+
+    Null feature values are retained as nodata and reported as warnings. A
+    dataset with structural, identity, geometry, or coverage errors is refused.
+    """
+    from gridforge.validation import validate_dataset
+
+    report = validate_dataset(dataset)
+    errors = [finding.message for finding in report.findings if finding.severity == "ERROR"]
+    if errors:
+        raise DatasetError("aligned dataset is invalid: " + "; ".join(errors[:3]))
+    spec_value = dataset.attrs.get("gridforge_spec")
+    if not isinstance(spec_value, dict):
+        raise DatasetError("aligned dataset is missing GridForge grid metadata")
+    try:
+        spec = GridSpec.from_mapping(spec_value)
+    except ValueError as exc:
+        raise DatasetError(f"aligned dataset grid metadata is invalid: {exc}") from exc
+    fingerprint = str(dataset["grid_fingerprint"].iloc[0])
+    if fingerprint != spec.fingerprint:
+        raise DatasetError("aligned dataset grid fingerprint does not match its specification")
+
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        dataset.to_parquet(output, index=False)
+        table = pq.read_table(output)
+        metadata = dict(table.schema.metadata or {})
+        metadata[b"gridforge:grid_fingerprint"] = fingerprint.encode("utf-8")
+        metadata[b"gridforge:grid_spec"] = json.dumps(
+            spec.to_dict(), ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        ).encode("utf-8")
+        operation = dataset.attrs.get("gridforge_operation")
+        if operation is not None:
+            metadata[b"gridforge:operation"] = json.dumps(
+                operation, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+            ).encode("utf-8")
+        pq.write_table(table.replace_schema_metadata(metadata), output, compression="zstd")
+    except Exception as exc:
+        raise DatasetError(f"cannot write aligned GeoParquet {output}: {exc}") from exc
+    return output
+
+
+def read_dataset(path: str | Path) -> gpd.GeoDataFrame:
+    """Read GridForge GeoParquet and restore its canonical grid identity."""
+    from gridforge.validation import validate_dataset
+
+    input_path = Path(path)
+    try:
+        dataset = gpd.read_parquet(input_path)
+        schema_metadata = pq.read_schema(input_path).metadata or {}
+    except Exception as exc:
+        raise DatasetError(f"cannot read aligned GeoParquet {input_path}: {exc}") from exc
+    metadata_fingerprint = schema_metadata.get(b"gridforge:grid_fingerprint")
+    metadata_spec = schema_metadata.get(b"gridforge:grid_spec")
+    if metadata_fingerprint is None or metadata_spec is None:
+        raise DatasetError("GeoParquet is missing GridForge grid metadata")
+    try:
+        spec_value = json.loads(metadata_spec.decode("utf-8"))
+        spec = GridSpec.from_mapping(spec_value)
+        fingerprint = metadata_fingerprint.decode("utf-8")
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
+        raise DatasetError("GridForge grid metadata is invalid") from exc
+    if spec.fingerprint != fingerprint:
+        raise DatasetError("GridForge grid metadata fingerprint does not match grid specification")
+    dataset.attrs["gridforge_spec"] = spec.to_dict()
+    operation = schema_metadata.get(b"gridforge:operation")
+    if operation is not None:
+        try:
+            dataset.attrs["gridforge_operation"] = json.loads(operation.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise DatasetError("GridForge operation metadata is invalid") from exc
+    if dataset.empty or "grid_fingerprint" not in dataset:
+        raise DatasetError("aligned dataset has no grid rows")
+    if not dataset["grid_fingerprint"].astype(str).eq(fingerprint).all():
+        raise DatasetError("aligned dataset grid fingerprint does not match metadata")
+    if dataset.crs is None or not spec.crs.equals(dataset.crs):
+        raise DatasetError("aligned dataset CRS does not match GridForge grid metadata")
+    report = validate_dataset(dataset)
+    errors = [finding.message for finding in report.findings if finding.severity == "ERROR"]
+    if errors:
+        raise DatasetError("aligned dataset is invalid: " + "; ".join(errors[:3]))
+    return dataset

gridforge/io/grid.py

@@ -0,0 +1,110 @@
+"""GeoParquet persistence for canonical grids."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import geopandas as gpd
+import pyarrow.parquet as pq
+
+from gridforge.errors import DatasetError
+from gridforge.grid.spec import GridSpec
+
+_GRID_COLUMNS = {
+    "grid_id",
+    "grid_fingerprint",
+    "row",
+    "column",
+    "left",
+    "bottom",
+    "right",
+    "top",
+    "geometry",
+}
+
+
+def write_grid(grid: gpd.GeoDataFrame, path: str | Path) -> Path:
+    """Write a canonical grid as GeoParquet with GridForge metadata."""
+    _validate_grid_schema(grid)
+    spec_value = grid.attrs.get("gridforge_spec")
+    if not isinstance(spec_value, dict):
+        raise DatasetError("grid is missing GridForge specification metadata")
+    try:
+        spec = GridSpec.from_mapping(spec_value)
+    except ValueError as exc:
+        raise DatasetError(f"grid specification metadata is invalid: {exc}") from exc
+    if grid.crs is None or not spec.crs.equals(grid.crs):
+        raise DatasetError("grid CRS does not match GridForge specification")
+    if not grid["grid_fingerprint"].astype(str).eq(spec.fingerprint).all():
+        raise DatasetError("grid fingerprint does not match GridForge specification")
+    from gridforge.validation import validate_grid
+
+    report = validate_grid(grid)
+    errors = [finding.message for finding in report.findings if finding.severity == "ERROR"]
+    if errors:
+        raise DatasetError("grid is invalid: " + "; ".join(errors[:3]))
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    grid.to_parquet(output, index=False)
+    table = pq.read_table(output)
+    metadata = dict(table.schema.metadata or {})
+    metadata[b"gridforge:grid_fingerprint"] = str(grid["grid_fingerprint"].iloc[0]).encode()
+    metadata[b"gridforge:grid_spec"] = json.dumps(
+        spec.to_dict(), sort_keys=True, separators=(",", ":")
+    ).encode()
+    pq.write_table(table.replace_schema_metadata(metadata), output, compression="zstd")
+    return output
+
+
+def read_grid(path: str | Path) -> gpd.GeoDataFrame:
+    """Read a GeoParquet grid and reject incomplete or ambiguous identity."""
+    input_path = Path(path)
+    try:
+        grid = gpd.read_parquet(input_path)
+        table = pq.read_table(input_path)
+    except Exception as exc:
+        raise DatasetError(f"cannot read grid GeoParquet {input_path}: {exc}") from exc
+    _validate_grid_schema(grid)
+    metadata_fingerprint = (table.schema.metadata or {}).get(b"gridforge:grid_fingerprint")
+    metadata_spec = (table.schema.metadata or {}).get(b"gridforge:grid_spec")
+    if metadata_fingerprint is None or metadata_spec is None:
+        raise DatasetError("GeoParquet is missing GridForge grid metadata")
+    try:
+        decoded_fingerprint = metadata_fingerprint.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise DatasetError("grid fingerprint metadata is invalid") from exc
+    if decoded_fingerprint != str(grid["grid_fingerprint"].iloc[0]):
+        raise DatasetError("grid fingerprint metadata does not match grid rows")
+    try:
+        grid.attrs["gridforge_spec"] = json.loads(metadata_spec.decode())
+        spec = GridSpec.from_mapping(grid.attrs["gridforge_spec"])
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
+        raise DatasetError("grid specification metadata is invalid") from exc
+    if spec.fingerprint != str(grid["grid_fingerprint"].iloc[0]):
+        raise DatasetError("grid specification does not match grid fingerprint")
+    from gridforge.validation import validate_grid
+
+    report = validate_grid(grid)
+    errors = [finding.message for finding in report.findings if finding.severity == "ERROR"]
+    if errors:
+        raise DatasetError("grid is invalid: " + "; ".join(errors[:3]))
+    return grid
+
+
+def _validate_grid_schema(grid: gpd.GeoDataFrame) -> None:
+    missing = sorted(_GRID_COLUMNS - set(grid.columns))
+    if missing:
+        raise DatasetError(f"grid is missing required columns: {', '.join(missing)}")
+    if grid.empty:
+        raise DatasetError("grid must contain at least one cell")
+    if grid.crs is None:
+        raise DatasetError("grid CRS is unknown")
+    if grid["grid_id"].isna().any() or grid["grid_id"].duplicated().any():
+        raise DatasetError("grid IDs must be non-null and unique")
+    fingerprints = grid["grid_fingerprint"].dropna().astype(str).unique()
+    if len(fingerprints) != 1 or grid["grid_fingerprint"].isna().any():
+        raise DatasetError("grid rows must have one non-null grid fingerprint")
+    expected = grid.sort_values(["row", "column"], kind="stable").index
+    if not grid.index.equals(expected):
+        raise DatasetError("grid rows must be sorted by row and column")