@spec date_from_gps_week_day(non_neg_integer(), integer()) ::
  {:ok, {integer(), integer(), integer()}}
  | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Convert a GPS week and day-of-week to a civil date, preserving range errors.

@spec distribution_location(
  Sidereon.GNSS.Distribution.ProductIdentity.t(),
  atom() | String.t()
) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Resolve an explicit distributor for an exact identity while retaining distributor, mirror, and era diagnostics.

@spec latest_ultra_issue(
  term(),
  NaiveDateTime.t() | DateTime.t() | tuple(),
  list() | nil
) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Return the latest ultra-rapid issue at or before a UTC instant.

available_issues is nil when availability is unknown, or a list of {date, issue} tuples such as {{2026, 1, 2}, "0000"} when it is known.

@spec newest_published_product(term(), term(), [{String.t(), String.t() | nil}]) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Select the newest matching product in a readable archive listing, retaining any catalog diagnostics.

@spec next_issue_due(term(), term(), NaiveDateTime.t() | DateTime.t() | tuple()) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Return the next nominal issue due while retaining typed catalog errors.

@spec open_mirror(term(), term()) ::
  {:ok, :ok} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Confirm that a center and product pair has a cataloged open mirror.

@spec parse_archive_listing(binary()) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Parse an archive listing without reducing an unreadable-listing failure to a legacy reason tuple.

@spec parse_skadi_tile_id(String.t()) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Parse a Skadi tile id while retaining invalid tile-id details.

@spec product_identity(
  term(),
  term(),
  Date.t() | NaiveDateTime.t() | tuple(),
  term() | nil,
  term() | nil
) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Resolve an exact product identity while retaining typed catalog errors.

@spec product_request(Sidereon.GNSS.Distribution.ProductIdentity.t(), [
  atom() | String.t()
]) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Validate an exact product request and its ordered distributor choices.

@spec product_solution_class(term(), term()) ::
  {:ok, String.t()}
  | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Return the solution class while retaining typed catalog errors.

This explicit query is useful when callers need the core error kind and fields. Sidereon.GNSS.Data.product_solution_class/2 keeps its legacy terms.

@spec skadi_tile_id(integer(), integer()) ::
  {:ok, String.t()}
  | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Derive a Skadi tile id while retaining invalid tile-index details.

@spec sp3_content_start_convention(
  term(),
  Date.t() | NaiveDateTime.t() | tuple(),
  term() | nil
) ::
  {:ok, {String.t(), integer()}}
  | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Return the SP3 first-content convention while retaining typed catalog errors.

The result on success is the core {value, offset_seconds} pair. Catalog failures include their kind, every variant-specific field, and exact message.

@spec station_obs_filename(String.t(), Date.t() | tuple(), String.t()) ::
  {:ok, String.t()}
  | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Return a station observation filename while retaining station and date validation diagnostics.

@spec terrain_tile_index(number(), number()) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Derive a terrain tile index while retaining invalid-coordinate details.

@spec ultra_issue_candidates(term(), NaiveDateTime.t() | DateTime.t() | tuple()) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Return ultra-rapid issue candidates for a date-time while retaining typed date and issue diagnostics.

@spec validate_product_identity(Sidereon.GNSS.Distribution.ProductIdentity.t()) ::
  {:ok, term()} | {:error, Sidereon.GNSS.Data.Catalog.CatalogError.t() | term()}

Validate a public product identity through the core catalog while retaining all typed field and filename diagnostics.