@spec decode(binary()) :: {:ok, [message()]} | {:error, term()}

Decode every CRC-valid RTCM 3 frame in a byte buffer.

@spec decode_frame(binary()) ::
  {:ok,
   %{
     message_number: integer(),
     frame_len: integer(),
     reserved: non_neg_integer(),
     body: binary()
   }}
  | {:error, term()}

Decode the single RTCM 3 frame that begins at the start of bytes.

Verifies the preamble and the CRC-24Q. Returns {:ok, %{message_number: n, frame_len: bytes, reserved: bits, body: binary}}, reserved being the six header bits between the preamble and the length as read, or {:error, reason} for a missing preamble, a truncated buffer, or a CRC mismatch. encode_frame_with_reserved/2 writes the body back with the same reserved bits.

@spec decode_message(binary()) :: {:ok, message()} | {:error, term()}

Decode one RTCM message body under the strict policy.

@spec decode_message_with_policy(binary(), policy()) ::
  {:ok, message(), [departure()]} | {:error, term()}

Decode one RTCM message body under policy, returning the departures read under :lenient (always empty under :strict, which refuses them).

@spec decode_messages(binary()) :: {:ok, [message()]} | {:error, term()}

Decode a complete RTCM 3 byte stream.

Every byte has to belong to a CRC-valid frame whose body decodes under the strict policy. Returns {:ok, [{type, fields}, ...]} in stream order, or {:error, text} naming what was not read: a skipped frame, or bytes outside CRC-valid frames (a stray byte, a CRC-24Q failure or a trailing partial frame). decode_stream/2 reads a noisy stream frame by frame and reports every skip.

@spec decode_stream(
  binary(),
  keyword()
) ::
  {:ok, %{messages: [message()], diagnostics: diagnostics()}} | {:error, term()}

Decode every CRC-valid RTCM 3 frame of a noisy stream and return messages plus stream diagnostics.

Frames whose CRC fails, whose body cannot be decoded, or that depart from the format under the :strict policy are skipped, and the scan resynchronizes on the next preamble. Diagnostics count the bytes passed over while resynchronizing (:resync_bytes) and the preambles whose frame failed its CRC-24Q (:crc_failures), list each skipped frame with its reason, and under :lenient list each departure read with its frame's byte offset.

Options: :policy (:strict or :lenient, default :strict).

@spec derive_lli(integer() | nil, integer() | nil, integer() | nil, boolean()) ::
  non_neg_integer()

Derive the RINEX LLI digit for one signal cell.

Pass elapsed_ms as nil for the first observation. When elapsed_ms is an integer, previous_min_lock_time_ms may be nil to represent a previous reserved indicator.

@spec encode(message()) :: {:ok, binary()} | {:error, term()}

Construct a supported RTCM 3 message and return its message body.

Refusals preserve the core error family and its typed payload.

@spec encode_frame(message() | binary()) :: {:ok, binary()} | {:error, term()}

Construct a supported RTCM 3 message and return its complete frame.

Refuses a message the wire format cannot state, or a body over the frame length limit, with the same typed reasons encode_message/1 returns.

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

Wrap a message body in an RTCM 3 frame whose six reserved header bits hold reserved, so a frame read with nonzero reserved bits is written back as it was read. Refuses a body over the frame length limit, or reserved wider than six bits, with the core's typed {:error, {:rtcm_encode_error, fields}} (reserved under the variant "frame_reserved_out_of_range").

@spec encode_message(message()) :: {:ok, binary()} | {:error, term()}

Construct a supported RTCM 3 message from a {type, fields} pair and encode it into a complete transport frame (preamble, length, body, CRC-24Q).

type is one of the supported message_type/0 atoms (:unsupported cannot be constructed). fields is a map of the raw transmitted fields, the same shape decode_messages/1 produces for that type (the derived :x_m/:y_m/:z_m station outputs are ignored when present, so a decoded map round-trips directly). Returns {:ok, frame_binary} or {:error, reason}. A message the wire format cannot state is refused rather than written as another satellite or signal. The core codec's refusals are {:error, {:rtcm_encode_error, fields}} with the variant under :variant: an MSM satellite id outside 1..64, a signal id outside 1..32, a satellite or cell listed twice or a signal whose satellite is not listed ("msm_mask"), and an ephemeris satellite field wider than the message's, four bits for QZSS 1044 and six for the others ("satellite_id_out_of_range"). A satellite or signal number outside 0..255, which the boundary cannot carry, is {:error, {:invalid_input, message}}.

The output frame feeds back through decode_messages/1, so construct -> encode -> decode reproduces the same message fields.

Core encoder and conversion refusals use {:rtcm_encode_error, %{variant: name, ...}} and {:rtcm_conversion_error, %{variant: name, ...}}; their maps retain the variant payload. Boundary validation failures remain {:invalid_input, text}.

@spec encode_with_policy(message(), policy()) ::
  {:ok, binary(), [departure()]} | {:error, term()}

Construct a supported RTCM 3 message and return its body written under policy, with the departures written under :lenient.

Under :lenient a message's :trailing_bits are written back after its last field, so a body read under :lenient re-encodes byte for byte; encode/1 refuses a nonempty :trailing_bits. Every other refusal of encode/1 applies under both policies.

@spec evaluate_ssr_vtec(message(), [number()], [number()], number(), number()) ::
  {:ok, map()} | {:error, {:vtec_evaluation, map()} | term()}

Evaluate a decoded or constructed :ssr_vtec message at receiver and transmit-frame satellite ECEF positions in metres.

The computation epoch is GPS seconds of day from the VTEC message's epoch, and the frequency is in hertz. Successful results include each layer's pierce-point coordinates, VTEC/STEC, mapping factor, and total code delay and carrier-phase advance. Model refusal is returned as a structured {:vtec_evaluation, details} error.

@spec lli_bits() :: %{loss_of_lock: 1, half_cycle: 2}

Return the RINEX LLI bit constants used by the RTCM MSM derivation helpers.

@spec message_number(binary()) :: {:ok, integer()} | {:error, term()}

Return the message number from one RTCM message body.

@spec minimum_lock_time_ms(String.t(), integer()) ::
  {:ok, non_neg_integer() | nil} | {:error, term()}

Minimum continuous-lock time in milliseconds for an MSM lock indicator.

kind is "msm4" or "msm7".

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

Elapsed milliseconds between two raw MSM epoch-time fields for one system.

@spec msm_lli([map()]) :: {:ok, [[map()]]} | {:error, term()}

Derive per-cell LLI rows by running a core lock-time tracker over MSM maps.

The input is a list of decoded MSM field maps, in stream order. The result is one list of %{satellite_id, signal_id, lli, min_lock_time_ms} maps per input message.

@spec msm_signal_rinex_code(String.t(), integer()) ::
  {:ok, String.t() | nil} | {:error, term()}

RINEX observation-code suffix for an MSM signal id, or nil if reserved.