@spec artifact_bytes(
  Sidereon.GNSS.SP3.t() | t(),
  keyword()
) :: {:ok, binary()} | {:error, term()}

Build canonical precise-interpolant artifact bytes from a parsed SP3 product or fitted interpolant.

The returned binary is deterministic for a deterministic source and can be persisted by the caller. open/1 reads the same bytes back into an evaluation handle. A numeric :gap_threshold_factor at or below 1.0 returns the typed PreciseEphemeris.interpolation_error() map.

Options:

• :gap_threshold_factor - override the position-interpolation gap threshold factor recorded in the artifact header.

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

Return canonical artifact bytes for this handle.

Opened artifacts return the same bytes supplied to open/1 or from_bytes/1; fitted interpolants serialize through the core artifact builder.

@spec byte_len(t()) :: {:ok, non_neg_integer()} | {:error, term()}

Return the artifact byte length.

@spec checksum64(binary() | t()) :: {:ok, non_neg_integer()} | {:error, term()}

Alias for checksum/1, matching the Python artifact checksum64 accessor.

@spec checksum(binary() | t()) :: {:ok, non_neg_integer()} | {:error, term()}

Return the artifact checksum.

Pass artifact bytes to compute their checksum directly. Passing an opened artifact handle returns the checksum of the resource's backing bytes. Passing a fitted interpolant builds artifact bytes first and then checksums them.

@spec clock_relativity_for_state_at_epoch_query(
  source(),
  String.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t(),
  {number(), number(), number()}
) :: :not_applicable | :unavailable | {:term, float()} | {:error, term()}

Evaluate clock relativity for a state at its exact epoch query.

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

Return who computed the checksum carried by an opened artifact handle.

@spec ephemeris_variance_at_epoch_queries(
  source(),
  String.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t()
) :: float() | nil | {:error, term()}

Read source variance at independent exact state and selection queries.

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

Alias for open/1, matching the Python artifact from_bytes constructor.

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

Read precise-interpolant artifact bytes from disk and open them.

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

Open a precise-interpolant artifact using a caller-attested checksum.

The file is memory-mapped read-only. Construction validates its header, index, dimensions, lengths, and payload layout without hashing payloads. The claim must equal the checksum declared by the header; a mismatch fails immediately and never falls back to hashing.

@spec from_precise_ephemeris_samples(
  Sidereon.GNSS.PreciseEphemeris.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Build a cached interpolant from a sample-backed precise ephemeris source.

This reuses the already validated Sidereon.GNSS.PreciseEphemeris handle and copies its prepared interpolation nodes. A numeric :gap_threshold_factor at or below 1.0 returns the typed PreciseEphemeris.interpolation_error() map.

Options:

• :gap_threshold_factor - override the position-interpolation gap threshold factor (default inherits from source).

A numeric factor at or below 1.0 returns the typed PreciseEphemeris.interpolation_error() map.

@spec from_samples(
  [Sidereon.GNSS.PreciseEphemerisSample.t()],
  keyword()
) :: {:ok, t()} | {:error, Sidereon.GNSS.PreciseEphemeris.construction_error()}

Build a cached interpolant directly from precise ephemeris samples.

Samples are Sidereon.GNSS.PreciseEphemerisSample structs. They must use one time scale, be grouped into at least two strictly increasing epochs per satellite, and carry finite positions and clocks. Validation reasons match Sidereon.GNSS.PreciseEphemeris.from_samples/1.

Options:

• :gap_threshold_factor - multiple of nominal node spacing above which consecutive records mark a coverage gap (default 1.5, must be > 1.0).

A numeric factor at or below 1.0 returns the typed PreciseEphemeris.interpolation_error() map.

@spec from_samples_with_accuracy(
  [Sidereon.GNSS.PreciseEphemerisSample.t()],
  [Sidereon.GNSS.PreciseEphemerisAccuracySample.t()],
  keyword()
) :: {:ok, t()} | {:error, Sidereon.GNSS.PreciseEphemeris.construction_error()}

Build a cached interpolant from samples and aligned accuracy sidecars.

A numeric :gap_threshold_factor at or below 1.0 returns the typed PreciseEphemeris.interpolation_error() map.

@spec from_sp3(
  Sidereon.GNSS.SP3.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Build a cached interpolant from a parsed SP3 product.

The SP3 product is already parsed and held by the BEAM. This function copies its interpolation nodes into a second read-only handle. Returns {:ok, %Sidereon.GNSS.PreciseEphemeris.Interpolant{}}.

Options:

• :gap_threshold_factor - override the position-interpolation gap threshold factor (default inherits from product).

A numeric factor at or below 1.0 returns the typed PreciseEphemeris.interpolation_error() map.

@spec gap_threshold_factor(t()) :: float()

Return the position-interpolation gap threshold factor carried by this interpolant or opened artifact.

@spec observable_states_at_j2000_s(source(), [String.t()], [number()]) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}

Alias for states_at_j2000_s/3.

@spec observable_states_at_j2000_s_detailed(source(), [String.t()], [number()]) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}

Alias for states_at_j2000_s_detailed/3.

@spec observable_states_at_shared_j2000_s(source(), [String.t()], number()) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}

Alias for states_at_shared_j2000_s/3.

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

Open precise-interpolant artifact bytes into an evaluation handle.

The BEAM binary is copied into the native resource so the resource can outlive the caller's binary safely. Inside the resource, the core artifact reader borrows its numeric arrays from the owned byte span for repeated evaluation. Corrupt and truncated artifacts return typed {:error, reason} values.

@spec position_at_epoch_query(
  source(),
  String.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t()
) ::
  {:ok, Sidereon.GNSS.SP3.State.t()} | {:error, term()}

Evaluate a satellite state at an exact epoch query without rounding its absolute epoch.

@spec position_at_j2000_seconds(source(), String.t(), number()) ::
  {:ok, Sidereon.GNSS.SP3.State.t()} | {:error, term()}

Evaluate one satellite position and clock at a J2000-second epoch.

@spec satellite_ids(t()) :: [String.t()]

Return the satellite ids available in the cached interpolant.

The ids are canonical SP3/RINEX tokens such as "G01" and are sorted in core satellite order.

@spec satellites(t()) :: [String.t()]

Alias for satellite_ids/1, matching the Python/WASM satellites accessor.

@spec selected_state_at_epoch_queries(
  source(),
  String.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t()
) :: {:ok, nil | map()} | {:error, term()}

Read a selected source state while retaining exact state and selection queries.

@spec states_at_j2000_s(source(), [String.t()], [number()]) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}

Evaluate states for parallel satellite and epoch arrays.

satellites[i] is evaluated at epochs_j2000_s[i]. The lists must have the same length. The returned StateBatch is index-aligned with the inputs and preserves each scalar result in batch.results.

@spec states_at_j2000_s_detailed(source(), [String.t()], [number()]) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}

Evaluate states for parallel satellite and epoch arrays, retaining structured core error details for failed rows. The legacy states_at_j2000_s/3 return format is unchanged.

@spec states_at_shared_j2000_s(source(), [String.t()], number()) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}

Evaluate states for many satellites at one shared J2000-second epoch.

The returned StateBatch is index-aligned with satellites. Missing data is represented per element rather than failing the whole call.

@spec time_scale(t()) :: String.t()

Return the source time-scale abbreviation, such as "GPST".

@spec transmit_clock_at_epoch_queries(
  source(),
  String.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t(),
  Sidereon.GNSS.Time.ExactEpochQuery.t()
) :: {:ok, nil | map()} | {:error, term()}

Read a transmission-placement clock at exact state and selection queries.

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

Verify the file-level and per-satellite payload checksums.

On success, digest_provenance/1 returns :verified.