@spec checksum64(t() | binary()) :: non_neg_integer()

Return a checksum for a parsed store handle or terrain store bytes.

@spec digest_provenance(t()) :: digest_provenance()

Return who computed the checksum carried by this terrain handle.

@spec dted_tree_to_mmap_store(String.t()) ::
  {:ok, binary()} | {:error, terrain_store_error() | term()}

Convert a DTED tile tree into terrain store bytes.

@spec ellipsoidal_height_m(t(), number(), number(), keyword()) ::
  {:ok, Sidereon.Terrain.MmapTerrain.EllipsoidalHeightM.t()}
  | {:error, terrain_datum_error() | term()}

Return WGS84 ellipsoidal terrain height using the embedded EGM96 1-degree grid.

@spec ellipsoidal_height_m_with_model(
  t(),
  number(),
  number(),
  Sidereon.Terrain.MmapTerrain.TerrainGeoidModel.t() | :egm96_one_degree,
  keyword()
) ::
  {:ok, Sidereon.Terrain.MmapTerrain.EllipsoidalHeightM.t()}
  | {:error, terrain_datum_error() | term()}

Return WGS84 ellipsoidal terrain height with an explicit geoid model.

Passing TerrainGeoidModel.egm96_fifteen_minute/1 requires a loaded Egm96FifteenMinuteGeoid; it never falls back to the embedded 1-degree grid.

@spec ellipsoidal_height_m_with_options(t(), number(), number(), keyword()) ::
  {:ok, Sidereon.Terrain.MmapTerrain.EllipsoidalHeightM.t()}
  | {:error, terrain_datum_error() | term()}

Return WGS84 ellipsoidal terrain height with lookup options.

@spec from_bytes(binary()) :: {:ok, t()} | {:error, terrain_store_error() | term()}

Parse terrain store bytes into a reader handle.

@spec from_path(String.t()) :: {:ok, t()} | {:error, terrain_store_error() | term()}

Open a terrain store file as a reader handle.

The file is memory-mapped read-only and the reader owns the mapping, so opening a store does not cost its size in process memory. The mapping is demand-paged: a reader querying a geographically local region faults in only the pages covering those tiles, and construction parses the header, datum tag, and tile index and nothing else.

@spec from_path_attested(String.t(), non_neg_integer()) ::
  {:ok, t()}
  | {:error, terrain_store_error() | {:invalid_checksum64, term()} | term()}

Open a terrain store file using a caller-attested full-store checksum.

The file is memory-mapped read-only. Construction validates its header, datum tag, tile index, dimensions, and payload bounds without hashing tile payloads. The claim is returned by checksum64/1 until verify/1 succeeds.

@spec from_vec(binary()) :: {:ok, t()} | {:error, terrain_store_error() | term()}

Parse owned terrain store bytes into a reader handle.

@spec height_batch(t(), [{number(), number()}], keyword()) ::
  [ok: Sidereon.Terrain.MmapTerrain.OrthometricHeightM.t(), error: term()]
  | {:error, term()}

Evaluate (longitude_deg, latitude_deg) points as orthometric heights.

@spec height_m(t(), number(), number(), keyword()) ::
  {:ok, Sidereon.Terrain.MmapTerrain.OrthometricHeightM.t()} | {:error, term()}

Return orthometric terrain height at (longitude_deg, latitude_deg).

@spec height_m_with_options(t(), number(), number(), keyword()) ::
  {:ok, Sidereon.Terrain.MmapTerrain.OrthometricHeightM.t()} | {:error, term()}

Return orthometric terrain height at (longitude_deg, latitude_deg) with lookup options.

@spec orthometric_height_batch(t(), [{number(), number()}], keyword()) ::
  [ok: Sidereon.Terrain.MmapTerrain.OrthometricHeightM.t(), error: term()]
  | {:error, term()}

Evaluate (longitude_deg, latitude_deg) points as typed orthometric heights.

@spec orthometric_height_m(t(), number(), number(), keyword()) ::
  {:ok, Sidereon.Terrain.MmapTerrain.OrthometricHeightM.t()} | {:error, term()}

Return typed orthometric terrain height at (longitude_deg, latitude_deg).

@spec orthometric_height_m_with_options(t(), number(), number(), keyword()) ::
  {:ok, Sidereon.Terrain.MmapTerrain.OrthometricHeightM.t()} | {:error, term()}

Return typed orthometric terrain height with lookup options.

@spec terrain_store_checksum64(binary()) :: non_neg_integer()

Return the FNV-1a checksum for terrain store bytes.

@spec tile_index(t()) :: [Sidereon.Terrain.MmapTerrain.TerrainStoreTileIndex.t()]

Return parsed tile index records.

@spec to_bytes(t()) :: binary()

Return canonical terrain store bytes from a parsed handle.

@spec verify(t()) :: :ok | {:error, terrain_store_error() | term()}

Verify tile payloads and any caller-attested full-store checksum.

On success, digest_provenance/1 returns :verified.

@spec vertical_datum(t()) :: Sidereon.Terrain.MmapTerrain.VerticalDatum.t()

Return the file-level vertical datum.

@spec write_dted_tree_to_mmap_store(String.t(), String.t()) ::
  :ok | {:error, terrain_store_error() | term()}

Convert a DTED tile tree and write terrain store bytes to out_path.