Module staleness 

Product-staleness graceful degradation for time-varying GNSS products.

Time-varying products (IONEX TEC maps, rapid/predicted SP3 orbit/clock files) publish with latency and gaps, so the product for the exact requested epoch is not always on hand. A direct lookup against a missing epoch is a hard failure, which is brittle for real-time and operational use.

This module sits on top of the Ionex and Sp3 parsers and adds a selection layer that degrades gracefully instead of erroring: given a SET of available parsed products and a requested epoch (or epoch range), it returns a usable handle, falling back to the most-recent available product within a configurable staleness cap. Every result carries StalenessMetadata describing which source epoch was used, how stale it is, and the DegradationKind, so a degraded answer is never substituted silently. Only a request that exceeds the staleness cap fails, with a typed SelectionError.

Degradation paths

• Exact: a product covering the requested epoch is present. The original product is returned untouched and the downstream evaluation is bit-for-bit identical to calling the parser/interpolator directly. Staleness is zero.
• IONEX diurnal shift: when no product covers the requested day, the most-recent prior day’s grid is advanced by whole days onto the requested epoch (Ionex::with_map_epochs_shifted_days). TEC is approximately 24-hour periodic, so this is near-lossless for the boundary window. The grid values are unchanged; only the epoch axis moves.
• SP3 nearest-prior: when no product covers the requested epoch, the most-recent prior product is selected as-is, with the staleness measured from its last epoch.

Network

This layer is pure and no-network: it selects among products the caller has already parsed. Fetching the products is a per-binding concern.

Structs

IonexSelection

A selected IONEX product plus its staleness metadata.

Sp3Selection

A selected SP3 product plus its staleness metadata.

StalenessMetadata

Structured description of the product staleness behind a selection result.

StalenessPolicy

Configurable staleness cap for product selection.

Enums

DegradationKind

How a selected product’s source epoch relates to the requested epoch.

SelectionError

Error returned when no product can satisfy a request.

Constants

DEFAULT_MAX_STALENESS_DAYS

Default staleness cap, in whole days.

Functions

select_ionex

Select an IONEX product usable at requested_epoch_j2000_s, degrading to a diurnal-shifted prior product within policy when the exact day is absent.

select_ionex_over_range

Select an IONEX product usable across [start, end] (J2000 seconds).

select_sp3

Select an SP3 product usable at requested_epoch_j2000_s, degrading to the most-recent prior product within policy.

select_sp3_over_range

Select an SP3 product usable across [start, end] (J2000 seconds).