@neilberkman/sidereon 0.8.0

package/types/sidereon-extra.d.ts

@@ -0,0 +1,896 @@
+// Hand-written companion types for the shapes wasm-bindgen exposes as `any`.
+//
+// `Sp3.solveSpp(request)` takes a plain object; wasm-bindgen types its argument
+// as `any` because it deserializes through serde. This is the precise shape it
+// accepts. Import it alongside the generated types:
+//
+//   import { loadSp3 } from "@neilberkman/sidereon";
+//   import type { SppRequest } from "@neilberkman/sidereon/types";
+
+/** One pseudorange observation for an SPP solve. */
+export interface SppObservation {
+  /** RINEX/IGS satellite token, e.g. "G01", "E12", "C08". */
+  satelliteId: string;
+  /** Pseudorange in metres. */
+  pseudorangeM: number;
+}
+
+/** Which atmospheric corrections to apply. Both default to false. */
+export interface SppCorrections {
+  ionosphere?: boolean;
+  troposphere?: boolean;
+}
+
+/** GPS Klobuchar ionosphere coefficients (each a 4-element tuple). */
+export interface SppKlobuchar {
+  alpha?: [number, number, number, number];
+  beta?: [number, number, number, number];
+}
+
+/** Surface meteorology for the troposphere model. */
+export interface SppSurfaceMet {
+  pressureHpa: number;
+  temperatureK: number;
+  relativeHumidity: number;
+}
+
+/** The object passed to `Sp3.solveSpp`. */
+export interface SppRequest {
+  /** Pseudorange observations; at least one is required. */
+  observations: SppObservation[];
+  /** Receive epoch, seconds since J2000 in the ephemeris time scale. */
+  tRxJ2000S: number;
+  /** Receive second-of-day, seconds. */
+  tRxSecondOfDayS: number;
+  /** Day of year. */
+  dayOfYear: number;
+  /** Initial state guess [x, y, z, clock]; defaults to [0, 0, 0, 0]. */
+  initialGuess?: [number, number, number, number];
+  corrections?: SppCorrections;
+  klobuchar?: SppKlobuchar;
+  met?: SppSurfaceMet;
+  /**
+   * GLONASS FDMA channel numbers as `[slot, channel]` pairs, e.g.
+   * `[[1, 1], [2, -4]]`. `slot` is the GLONASS satellite slot/PRN and `channel`
+   * its FDMA frequency channel `k` (valid `[-7, +6]`). GLONASS is FDMA, so its
+   * per-satellite carrier is resolved from this map to scale the L1 Klobuchar
+   * ionosphere delay by `(f_L1 / f_k)^2`. Omit (or pass `[]`) when there is no
+   * GLONASS observation; every other constellation is unaffected. A GLONASS
+   * observation solved with `corrections.ionosphere` on but no entry here (or a
+   * channel outside `[-7, +6]`) is rejected with an `Error`. Channels are
+   * available from broadcast nav (`GlonassRecordJs.freqChannel`) or a RINEX obs
+   * header (`ObsHeader.glonassSlots`).
+   */
+  glonassChannels?: [number, number][];
+  /** Populate WGS84 lat/lon/height in the result. Defaults to true. */
+  withGeodetic?: boolean;
+}
+
+// --- Observable-domain plain-object inputs ----------------------------------
+//
+// The wasm-bindgen surface types these arguments as `any` because they cross
+// the boundary through serde. These are the precise shapes accepted. Import:
+//
+//   import { detectCycleSlips } from "@neilberkman/sidereon";
+//   import type { ArcEpoch } from "@neilberkman/sidereon/types";
+
+/** One epoch in a single-satellite carrier-phase arc. Phases are cycles, code
+ * values metres, carrier frequencies hertz, `gapTimeS` any comparable seconds
+ * coordinate. Any field may be omitted. */
+export interface ArcEpoch {
+  phi1Cycles?: number;
+  phi2Cycles?: number;
+  p1M?: number;
+  p2M?: number;
+  lli1?: number;
+  lli2?: number;
+  f1Hz?: number;
+  f2Hz?: number;
+  gapTimeS?: number;
+}
+
+/** Options controlling carrier-phase cycle-slip classification. */
+export interface CycleSlipOptions {
+  /** Geometry-free step threshold, metres. Defaults to 0.05. */
+  gfThresholdM?: number;
+  /** Melbourne-Wubbena step threshold, wide-lane cycles. Defaults to 4.0. */
+  mwThresholdCycles?: number;
+  /** Data-gap threshold, seconds. Defaults to 300.0. */
+  minArcGapS?: number;
+}
+
+/** One satellite observation for a receiver velocity solve. */
+export interface VelocityObservation {
+  /** RINEX satellite token, e.g. "G07". */
+  satelliteId: string;
+  /** Pseudorange rate (m/s) for range-rate solves, or Doppler (Hz) for Doppler. */
+  value: number;
+  /** Carrier frequency, hertz, used for Doppler conversion. */
+  carrierHz: number;
+  /** Satellite clock drift, seconds per second. Defaults to 0. */
+  satClockDriftSS?: number;
+}
+
+/** Options controlling receiver velocity solving. */
+export interface VelocitySolveOptions {
+  /** Observation value convention. Defaults to "range_rate". */
+  observable?: "range_rate" | "doppler";
+  /** Apply fixed-point light-time correction. Defaults to true. */
+  lightTime?: boolean;
+  /** Apply Earth-rotation Sagnac correction. Defaults to true. */
+  sagnac?: boolean;
+}
+
+/** One satellite/elevation row for sigma or weight construction. */
+export interface WeightEntry {
+  satelliteId: string;
+  /** Topocentric elevation, degrees. */
+  elevationDeg: number;
+  /** Optional carrier-to-noise density, dB-Hz. */
+  cn0Dbhz?: number;
+}
+
+/** Options for pseudorange variance weighting. */
+export interface PseudorangeVarianceOptions {
+  /** Zenith-floor term, metres. Defaults to 0.3. */
+  aM?: number;
+  /** Elevation-scaled term, metres. Defaults to 0.3. */
+  bM?: number;
+  /** Variance model. Defaults to "elevation". */
+  model?: "elevation" | "elevation_cn0";
+  /** Carrier-to-noise density, dB-Hz (required for "elevation_cn0"). */
+  cn0Dbhz?: number;
+  /** C/N0 variance scale, square metres. Defaults to 1.0. */
+  cn0ScaleM2?: number;
+}
+
+/** One satellite-keyed pseudorange for ionosphere-free combination. */
+export interface PseudorangeObservation {
+  satelliteId: string;
+  /** Pseudorange, metres. */
+  valueM: number;
+}
+
+/** A per-constellation RINEX band override for pseudorange combination. */
+export interface PseudorangeBandOverride {
+  /** Single RINEX system character, e.g. "G". */
+  system: string;
+  /** Band-1 RINEX observation code. */
+  band1: string;
+  /** Band-2 RINEX observation code. */
+  band2: string;
+}
+
+/** GPS C/A replica generation options. */
+export interface ReplicaOptions {
+  /** Sampling rate, hertz. Defaults to 2_046_000. */
+  sampleRateHz?: number;
+  /** Output sample count. Defaults to 2046. */
+  numSamples?: number;
+  /** Initial C/A code phase, chips. Defaults to 0. */
+  codePhaseChips?: number;
+  /** Code-rate Doppler, hertz. Defaults to 0. */
+  codeDopplerHz?: number;
+}
+
+/** Coherent GPS C/A correlation options. */
+export interface CorrelateOptions {
+  sampleRateHz?: number;
+  dopplerHz?: number;
+  codePhaseChips?: number;
+  codeDopplerHz?: number;
+}
+
+/** GPS C/A acquisition search options. */
+export interface AcquisitionOptions {
+  sampleRateHz?: number;
+  dopplerMinHz?: number;
+  dopplerMaxHz?: number;
+  dopplerStepHz?: number;
+}
+
+// --- Orbit propagation ------------------------------------------------------
+//
+// `propagateState(request)` deserializes its argument through serde, so
+// wasm-bindgen types it as `any`. This is the precise shape it accepts. Import:
+//
+//   import { propagateState } from "@neilberkman/sidereon";
+//   import type { PropagateStateRequest } from "@neilberkman/sidereon/types";
+
+/** Numerical state-propagation force model selector. */
+export type ForceModel = "two_body" | "two_body_j2";
+
+/** Numerical state-propagation integrator selector. */
+export type Integrator = "dp54" | "rk4";
+
+/** The object passed to `propagateState`. Position/velocity are length-3,
+ * km / km/s; `timesS` are absolute TDB epochs (seconds). */
+export interface PropagateStateRequest {
+  /** Initial-state epoch, TDB seconds. */
+  epochS: number;
+  /** Initial ECI position [x, y, z], km. */
+  positionKm: [number, number, number];
+  /** Initial ECI velocity [vx, vy, vz], km/s. */
+  velocityKmS: [number, number, number];
+  /** Output sample epochs, TDB seconds, monotonic in the propagation direction. */
+  timesS: number[];
+  /** Force model. Defaults to "two_body". */
+  forceModel?: ForceModel;
+  /** Integrator. Defaults to "dp54". */
+  integrator?: Integrator;
+  /** Absolute tolerance (DP54). Defaults to 1e-9. */
+  absTol?: number;
+  /** Relative tolerance (DP54). Defaults to 1e-12. */
+  relTol?: number;
+  /** Initial step, seconds. Defaults to 60. Must be positive. */
+  initialStepS?: number;
+  /** Minimum step, seconds. Defaults to 1e-6. */
+  minStepS?: number;
+  /** Maximum step, seconds. Defaults to 3600. */
+  maxStepS?: number;
+  /** Maximum integrator steps. Defaults to 1_000_000. */
+  maxSteps?: number;
+  /** Gravitational parameter, km^3/s^2. Defaults to Earth's MU_EARTH. */
+  muKm3S2?: number;
+}
+
+// --- RTK baseline solving ---------------------------------------------------
+//
+// `solveRtkFloat(config)` / `solveRtkFixed(config)` deserialize through serde.
+// These are the precise shapes accepted. Import:
+//
+//   import { solveRtkFloat } from "@neilberkman/sidereon";
+//   import type { RtkFloatConfig } from "@neilberkman/sidereon/types";
+
+/** RTK stochastic weighting model selector. */
+export type RtkStochasticModel = "simple" | "rtklib";
+
+/** One satellite's base/rover measurements for an RTK epoch. */
+export interface RtkSatMeasurement {
+  sat: string;
+  sdAmbiguityId: string;
+  baseCodeM: number;
+  basePhaseM: number;
+  roverCodeM: number;
+  roverPhaseM: number;
+  baseTxPos: [number, number, number];
+  roverTxPos: [number, number, number];
+  pos: [number, number, number];
+}
+
+/** One RTK epoch with reference and non-reference satellite rows. */
+export interface RtkEpoch {
+  references: RtkSatMeasurement[];
+  nonref: RtkSatMeasurement[];
+  dtS: number;
+  velocityMps?: [number, number, number];
+}
+
+/** RTK measurement weighting and correction model. */
+export interface RtkMeasurementModel {
+  codeSigmaM: number;
+  phaseSigmaM: number;
+  /** Apply the Earth-rotation Sagnac correction. Defaults to true. */
+  sagnac?: boolean;
+  /** Stochastic model. Defaults to "simple". */
+  stochastic?: RtkStochasticModel;
+  /** Elevation-weight measurements (simple model only). Defaults to false. */
+  elevationWeighting?: boolean;
+}
+
+/** Iteration controls for an RTK float solve. */
+export interface RtkFloatOptions {
+  positionTolM?: number;
+  ambiguityTolM?: number;
+  maxIterations?: number;
+}
+
+/** Iteration and integer-search controls for RTK fixed solving. */
+export interface RtkFixedOptions {
+  positionTolM?: number;
+  ambiguityTolM?: number;
+  maxIterations?: number;
+  ratioThreshold?: number;
+  partialAmbiguityResolution?: boolean;
+  partialMinAmbiguities?: number;
+}
+
+/** Residual validation controls for RTK fixed solving. */
+export interface RtkResidualValidationOptions {
+  /** Per-residual rejection threshold in sigma, or null/omitted to disable. */
+  thresholdSigma?: number | null;
+  maxExclusions?: number;
+}
+
+/** The object passed to `solveRtkFloat`. */
+export interface RtkFloatConfig {
+  epochs: RtkEpoch[];
+  /** Known base receiver ECEF position [x, y, z], metres. */
+  base: [number, number, number];
+  ambiguityIds: string[];
+  model: RtkMeasurementModel;
+  /** Rover-minus-base ECEF baseline seed, metres. Defaults to [0, 0, 0]. */
+  initialBaselineM?: [number, number, number];
+  options?: RtkFloatOptions;
+}
+
+/** The object passed to `solveRtkFixed`. */
+export interface RtkFixedConfig {
+  epochs: RtkEpoch[];
+  base: [number, number, number];
+  ambiguityIds: string[];
+  /** Ambiguity id -> satellite token. */
+  ambiguitySatellites: Record<string, string>;
+  /** Ambiguity id -> wavelength, metres. */
+  wavelengthsM: Record<string, number>;
+  /** Ambiguity id -> offset, metres. */
+  offsetsM: Record<string, number>;
+  model: RtkMeasurementModel;
+  floatOptions?: RtkFloatOptions;
+  fixedOptions?: RtkFixedOptions;
+  residualOptions?: RtkResidualValidationOptions;
+  /** Systems kept float-only (never integer-fixed), e.g. ["R"]. */
+  floatOnlySystems?: string[];
+  initialBaselineM?: [number, number, number];
+}
+
+// --- PPP solving ------------------------------------------------------------
+//
+// `solvePppFloat(sp3, epochs, initialState, config)` / `solvePppFixed(...)`
+// take serde-`any` arrays and objects. Import:
+//
+//   import { solvePppFloat } from "@neilberkman/sidereon";
+//   import type { PppEpoch, PppFloatConfig } from "@neilberkman/sidereon/types";
+
+/** Civil epoch timestamp for a PPP epoch. */
+export interface PppCivilDateTime {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/** One ionosphere-free code/phase observation in a PPP epoch. */
+export interface PppObservation {
+  satelliteId: string;
+  ambiguityId: string;
+  /** Ionosphere-free code, metres. */
+  codeM: number;
+  /** Ionosphere-free carrier phase, metres. */
+  phaseM: number;
+  freq1Hz?: number;
+  freq2Hz?: number;
+}
+
+/** One static PPP epoch. */
+export interface PppEpoch {
+  civil: PppCivilDateTime;
+  jdWhole: number;
+  jdFraction: number;
+  tRxJ2000S: number;
+  observations: PppObservation[];
+}
+
+/** Initial PPP state. */
+export interface PppFloatState {
+  positionM: [number, number, number];
+  /** Per-epoch receiver clocks, metres. */
+  clocksM: number[];
+  /** Ambiguity id -> initial ambiguity, metres. */
+  ambiguitiesM: Record<string, number>;
+  /** Initial zenith tropospheric delay, metres. Defaults to 0. */
+  ztdM?: number;
+}
+
+/** PPP measurement weights. */
+export interface PppMeasurementWeights {
+  code?: number;
+  phase?: number;
+  elevationWeighting?: boolean;
+}
+
+/** PPP troposphere controls. */
+export interface PppTroposphereOptions {
+  enabled?: boolean;
+  estimateZtd?: boolean;
+  pressureHpa?: number;
+  temperatureK?: number;
+  relativeHumidity?: number;
+}
+
+/** Iteration and convergence controls for PPP. */
+export interface PppFloatOptions {
+  maxIterations?: number;
+  positionToleranceM?: number;
+  clockToleranceM?: number;
+  ambiguityToleranceM?: number;
+  ztdToleranceM?: number;
+}
+
+/** The config object passed to `solvePppFloat`. */
+export interface PppFloatConfig {
+  weights?: PppMeasurementWeights;
+  tropo?: PppTroposphereOptions;
+  options?: PppFloatOptions;
+  residualScreen?: boolean;
+}
+
+/** Integer ambiguity controls for PPP fixed solving. */
+export interface PppFixedAmbiguityOptions {
+  /** Ambiguity id -> wavelength, metres. */
+  wavelengthsM: Record<string, number>;
+  /** Ambiguity id -> offset, metres. */
+  offsetsM: Record<string, number>;
+  ratioThreshold?: number;
+}
+
+/** The config object passed to `solvePppFixed`. */
+export interface PppFixedConfig {
+  ambiguity: PppFixedAmbiguityOptions;
+  weights?: PppMeasurementWeights;
+  tropo?: PppTroposphereOptions;
+  options?: PppFloatOptions;
+}
+
+// --- SP3 merge --------------------------------------------------------------
+//
+// `mergeSp3(sources, options?)` deserializes `options` through serde. Import:
+//
+//   import { mergeSp3 } from "@neilberkman/sidereon";
+//   import type { Sp3MergeOptions } from "@neilberkman/sidereon/types";
+
+/** How agreeing SP3 sources are combined in `mergeSp3`. */
+export type Sp3MergeCombine = "mean" | "median" | "precedence";
+
+/** The options object passed to `mergeSp3`. All fields optional. */
+export interface Sp3MergeOptions {
+  /** Max agreeing-source 3D position difference, metres. Defaults to 0.5. */
+  positionToleranceM?: number;
+  /** Max agreeing-source clock difference after alignment, seconds. Defaults to 5e-9. */
+  clockToleranceS?: number;
+  /** Minimum agreeing sources for a multi-source cell. Defaults to 2. */
+  minAgree?: number;
+  /** Minimum common clocked satellites for clock-datum alignment. Defaults to 5. */
+  clockMinCommon?: number;
+  /** Consensus combination policy. Defaults to "mean". */
+  combine?: Sp3MergeCombine;
+  /** Output epoch spacing, seconds, or null for the coarsest input grid. */
+  targetEpochIntervalS?: number | null;
+  /** Optional system filter as RINEX letters/names (e.g. ["G", "C"]). */
+  systems?: string[] | null;
+}
+
+// --- DOP series -------------------------------------------------------------
+//
+// `gnssDopSeries(sp3, stationEcefM, j2000Seconds, options?)` deserializes
+// `options` through serde. Import:
+//
+//   import { gnssDopSeries } from "@neilberkman/sidereon";
+//   import type { GnssDopSeriesOptions } from "@neilberkman/sidereon/types";
+
+/** DOP row weighting selector for `gnssDopSeries`. */
+export type DopWeighting = "unit" | "elevation";
+
+/** The options object passed to `gnssDopSeries`. All fields optional. */
+export interface GnssDopSeriesOptions {
+  /** Explicit satellite tokens (e.g. ["G01", "G02"]); omit for a visibility scan. */
+  satellites?: string[];
+  /** Minimum topocentric elevation, degrees. Defaults to 5. */
+  elevationMaskDeg?: number;
+  /** Constellation filter as RINEX letters/names (e.g. ["G"]). */
+  systems?: string[];
+  /** Row weighting policy. Defaults to "unit". */
+  weighting?: DopWeighting;
+  /** Apply light-time + Sagnac corrections forming the line of sight. Defaults to false. */
+  lightTime?: boolean;
+}
+
+// --- CDM construction -------------------------------------------------------
+//
+// `new CdmObject(positionKm, velocityKmS, covarianceRtn, meta?)` and
+// `new Cdm(object1, object2, meta?)` deserialize their `meta` object through
+// serde. Import:
+//
+//   import { Cdm, CdmObject } from "@neilberkman/sidereon";
+//   import type { CdmObjectMeta, CdmMeta } from "@neilberkman/sidereon/types";
+
+/** Optional metadata for a `CdmObject`. */
+export interface CdmObjectMeta {
+  objectDesignator?: string;
+  catalogName?: string;
+  objectName?: string;
+  internationalDesignator?: string;
+  objectType?: string;
+  refFrame?: string;
+}
+
+/** Optional message-level fields for a `Cdm`. */
+export interface CdmMeta {
+  creationDate?: string;
+  originator?: string;
+  messageId?: string;
+  tca?: string;
+  missDistanceM?: number;
+  relativeSpeedMS?: number;
+  collisionProbability?: number;
+  collisionProbabilityMethod?: string;
+  hardBodyRadiusM?: number;
+}
+
+// --- OMM construction -------------------------------------------------------
+//
+// `new Omm(epoch, meanMotion, ..., noradCatId, meta?)` deserializes its `meta`
+// object through serde. Import:
+//
+//   import { Omm } from "@neilberkman/sidereon";
+//   import type { OmmMeta } from "@neilberkman/sidereon/types";
+
+/** Optional OMM fields; each defaults to the CCSDS-standard value. */
+export interface OmmMeta {
+  ccsdsOmmVers?: string;
+  creationDate?: string;
+  originator?: string;
+  objectName?: string;
+  objectId?: string;
+  centerName?: string;
+  refFrame?: string;
+  timeSystem?: string;
+  meanElementTheory?: string;
+  ephemerisType?: number;
+  classificationType?: string;
+  elementSetNo?: number;
+  revAtEpoch?: number;
+  bstar?: number;
+  meanMotionDot?: number;
+  meanMotionDdot?: number;
+}
+
+// --- DGNSS ------------------------------------------------------------------
+//
+// `Sp3.dgnssCorrections(request)`, `Sp3.dgnssSolve(request)`, and
+// `dgnssApply(roverObservations, corrections)` deserialize their plain-object
+// arguments through serde, so wasm-bindgen types them as `any`. Import:
+//
+//   import { dgnssApply } from "@neilberkman/sidereon";
+//   import type { DgnssSolveRequest } from "@neilberkman/sidereon/types";
+
+/** One code (pseudorange) observation. */
+export interface DgnssCodeObservation {
+  satelliteId: string;
+  pseudorangeM: number;
+}
+
+/** One per-satellite pseudorange correction; the element type of the array
+ * returned by `Sp3.dgnssCorrections` and accepted by `dgnssApply`. */
+export interface DgnssCorrectionEntry {
+  satelliteId: string;
+  correctionM: number;
+}
+
+/** The object passed to `Sp3.dgnssCorrections`. */
+export interface DgnssCorrectionsRequest {
+  /** Surveyed base ECEF position [x, y, z], metres. */
+  basePositionM: [number, number, number];
+  baseObservations: DgnssCodeObservation[];
+  /** Receive epoch, seconds since J2000 in the ephemeris time scale. */
+  tRxJ2000S: number;
+}
+
+/** The object passed to `Sp3.dgnssSolve`. */
+export interface DgnssSolveRequest {
+  /** Surveyed base ECEF position [x, y, z], metres. */
+  basePositionM: [number, number, number];
+  baseObservations: DgnssCodeObservation[];
+  roverObservations: DgnssCodeObservation[];
+  tRxJ2000S: number;
+  tRxSecondOfDayS: number;
+  dayOfYear: number;
+  /** Initial state guess [x, y, z, clock]; defaults to [0, 0, 0, 0]. */
+  initialGuess?: [number, number, number, number];
+  /** Populate WGS84 lat/lon/height in the result. Defaults to true. */
+  withGeodetic?: boolean;
+}
+
+// --- Fault detection and exclusion (FDE) ------------------------------------
+//
+// `Sp3.fde(request)` deserializes its argument through serde. Import:
+//
+//   import { loadSp3 } from "@neilberkman/sidereon";
+//   import type { FdeRequest } from "@neilberkman/sidereon/types";
+
+/** One per-satellite RAIM residual weight. */
+export interface RaimWeightEntry {
+  satelliteId: string;
+  weight: number;
+}
+
+/** The object passed to `Sp3.fde`: the SPP solve inputs plus the RAIM /
+ * exclusion options. */
+export interface FdeRequest {
+  observations: SppObservation[];
+  tRxJ2000S: number;
+  tRxSecondOfDayS: number;
+  dayOfYear: number;
+  initialGuess?: [number, number, number, number];
+  corrections?: SppCorrections;
+  klobuchar?: SppKlobuchar;
+  met?: SppSurfaceMet;
+  glonassChannels?: [number, number][];
+  withGeodetic?: boolean;
+  /** RAIM false-alarm probability in the open interval (0, 1); defaults to the
+   * core RAIM default. */
+  pFa?: number;
+  /** Per-satellite RAIM weights; absent or empty means unit weights. */
+  weights?: RaimWeightEntry[];
+  /** Override for the number of distinct GNSS clock systems. */
+  nSystems?: number;
+  /** Maximum exclusions; defaults to max(observationCount - 4, 0). */
+  maxIterations?: number;
+  /** Optional PDOP ceiling applied to each candidate solution. */
+  maxPdop?: number;
+}
+
+// --- Broadcast-vs-precise comparison ----------------------------------------
+//
+// `BroadcastEphemeris.compareToSp3(...)` returns a plain object typed `any`.
+// Import:
+//
+//   import { loadRinexNav } from "@neilberkman/sidereon";
+//   import type { BroadcastCompareReport } from "@neilberkman/sidereon/types";
+
+/** Difference statistics for one satellite (or the overall set). Every metre
+ * field is `null` when no compared epoch populated it. */
+export interface BroadcastCompareStats {
+  count: number;
+  orbit3dRmsM: number | null;
+  orbit3dMaxM: number | null;
+  radialRmsM: number | null;
+  radialMaxM: number | null;
+  alongRmsM: number | null;
+  alongMaxM: number | null;
+  crossRmsM: number | null;
+  crossMaxM: number | null;
+  clockRmsM: number | null;
+  clockMaxM: number | null;
+  clockDatumRemovedRmsM: number | null;
+  clockDatumRemovedMaxM: number | null;
+}
+
+/** The report returned by `BroadcastEphemeris.compareToSp3`. */
+export interface BroadcastCompareReport {
+  overall: BroadcastCompareStats;
+  perSatellite: { satelliteId: string; stats: BroadcastCompareStats }[];
+  missing: { satelliteId: string; count: number }[];
+}
+
+// --- GNSS constellation identity catalog -------------------------------------
+//
+// The constellation surface is JSON-in / JSON-out: every function takes and
+// returns plain objects through serde, so wasm-bindgen types them as `any`.
+// These are the precise shapes. Import:
+//
+//   import { fromCelestrakJson, mergeNavcen } from "@neilberkman/sidereon";
+//   import type { ConstellationRecord } from "@neilberkman/sidereon/types";
+
+/** Lower-case constellation label, e.g. "gps". GPS is supported today. */
+export type ConstellationSystem =
+  | "gps"
+  | "glonass"
+  | "galileo"
+  | "beidou"
+  | "qzss"
+  | "navic"
+  | "sbas";
+
+/** CelesTrak `gps-ops` provenance preserved on a record. */
+export interface CelestrakSource {
+  /** CelesTrak GP group the record came from ("gps-ops"). */
+  group: string;
+  /** The OMM OBJECT_NAME. */
+  objectName?: string;
+  /** The OMM OBJECT_ID (international designator). */
+  objectId?: string;
+  /** The OMM EPOCH, ISO-8601. */
+  epoch?: string;
+  /** Block type parsed from the object name ("IIF", "IIR", "IIR-M", "III"). */
+  blockType?: string;
+}
+
+/** NAVCEN status provenance preserved on a record or recorded as a conflict. */
+export interface NavcenSource {
+  /** Space Vehicle Number. */
+  svn?: number;
+  blockType?: string;
+  plane?: string;
+  slot?: string;
+  clock?: string;
+  /** NANU type code ("FCSTSUMM", "UNUSABLE", "DECOM", ...). */
+  nanuType?: string;
+  nanuSubject?: string;
+  /** Whether the row carried an active NANU. */
+  activeNanu: boolean;
+}
+
+/** Per-source provenance kept on a record. */
+export interface RecordSource {
+  celestrak?: CelestrakSource;
+  /** NAVCEN overlay merged into this record. */
+  navcen?: NavcenSource;
+  /** A NAVCEN row that matched the PRN but was not merged (a PRN transition). */
+  navcenConflict?: NavcenSource;
+}
+
+/** A normalized GNSS satellite identity record, the element type of the array
+ * returned by `fromCelestrakJson` / `mergeNavcen` and accepted by the validate
+ * and diff functions. */
+export interface ConstellationRecord {
+  system: ConstellationSystem;
+  /** Within-constellation PRN. */
+  prn: number;
+  /** Space Vehicle Number, when known (CelesTrak alone leaves this absent). */
+  svn?: number;
+  /** NORAD catalog id. */
+  noradId: number;
+  /** Canonical SP3/RINEX satellite token ("G03"). */
+  sp3Id: string;
+  /** Present in the base identity source. */
+  active: boolean;
+  /** Advisory usability flag. */
+  usable: boolean;
+  source: RecordSource;
+}
+
+/** A parsed NAVCEN GPS constellation status row, the element type returned by
+ * `parseNavcen` and accepted by `mergeNavcen`. */
+export interface NavcenStatus {
+  system: ConstellationSystem;
+  prn: number;
+  svn?: number;
+  /** Usable per the active NANU (if any). */
+  usable: boolean;
+  activeNanu: boolean;
+  nanuType?: string;
+  nanuSubject?: string;
+  plane?: string;
+  slot?: string;
+  blockType?: string;
+  clock?: string;
+}
+
+/** The report returned by `validate` / `validateAgainstSp3Ids`. */
+export interface ConstellationValidation {
+  /** Active+usable catalog SP3 ids absent from the compared product. */
+  missingSp3Ids: string[];
+  /** PRNs that appear in more than one record. */
+  duplicatePrns: number[];
+  /** NORAD ids that appear in more than one record. */
+  duplicateNoradIds: number[];
+  /** PRNs that are inactive or unusable. */
+  inactiveUnusablePrns: number[];
+  /** SP3 ids in the product absent from the active+usable catalog. */
+  extraSp3Ids: string[];
+}
+
+/** A single field change on a PRN held across both diffed snapshots. */
+export interface ConstellationFieldChange<T> {
+  system: ConstellationSystem;
+  prn: number;
+  from: T;
+  to: T;
+}
+
+/** The change report returned by `diff` and tested by `changed`. */
+export interface ConstellationDiff {
+  /** PRNs present only in the current snapshot. */
+  added: ConstellationRecord[];
+  /** PRNs present only in the previous snapshot. */
+  removed: ConstellationRecord[];
+  noradReassigned: ConstellationFieldChange<number>[];
+  sp3IdChanged: ConstellationFieldChange<string>[];
+  svnChanged: ConstellationFieldChange<number | null>[];
+  activityChanged: ConstellationFieldChange<boolean>[];
+  usabilityChanged: ConstellationFieldChange<boolean>[];
+}
+
+// --- Product-staleness selection + broadcast fallback -----------------------
+//
+// `selectIonex` / `selectSp3` (+ `*OverRange`) and `solveWithFallback` take an
+// optional `policy` object typed `any`, and the selection/source metadata cross
+// out of the result handles as plain objects typed `any`. These are the precise
+// shapes. Import:
+//
+//   import { selectSp3, solveWithFallback } from "@neilberkman/sidereon";
+//   import type { StalenessPolicy, FixSource } from "@neilberkman/sidereon/types";
+
+/** The optional staleness cap passed to the selection and fallback functions.
+ * Set at most one of the two fields; omit the argument entirely for the engine
+ * default cap of 3 days. */
+export interface StalenessPolicy {
+  /** Maximum tolerated staleness, seconds. */
+  maxStalenessS?: number;
+  /** Maximum tolerated staleness, days. */
+  maxStalenessDays?: number;
+}
+
+/** How a selected product's source epoch relates to the requested epoch.
+ * `"exact"` is no degradation; `"nearestPrior"` is the SP3 nearest-prior path;
+ * `"diurnalShift"` is the IONEX whole-day persistence path. */
+export type DegradationKind = "exact" | "nearestPrior" | "diurnalShift";
+
+/** Staleness metadata attached to every selection and to a precise fix. Epochs
+ * are J2000 seconds; `stalenessS` is `requested - source` and never negative. */
+export interface StalenessMetadata {
+  kind: DegradationKind;
+  requestedEpochJ2000S: number;
+  sourceEpochJ2000S: number;
+  stalenessS: number;
+  stalenessDays: number;
+}
+
+/** The interpolated state returned by `Sp3Selection.positionAtJ2000Seconds`. */
+export interface Sp3SelectionState {
+  positionM: [number, number, number];
+  /** Clock offset, seconds, or `null` for the bad-clock sentinel. */
+  clockS: number | null;
+}
+
+/** The variant `name` of a selection failure. A selection function throws an
+ * `Error` whose `.name` is one of these and whose `.detail` is the matching
+ * `SelectionErrorDetail`. */
+export type SelectionErrorName =
+  | "EmptyProductSet"
+  | "InvalidRange"
+  | "NoPriorProduct"
+  | "BeyondStalenessCap"
+  | "InvalidProduct"
+  | "InvalidPolicy"
+  | "Overflow";
+
+/** The structured `.detail` attached to a thrown selection `Error`. Only the
+ * fields the variant carries are present. */
+export interface SelectionErrorDetail {
+  name: SelectionErrorName;
+  message: string;
+  requestedEpochJ2000S?: number;
+  startEpochJ2000S?: number;
+  endEpochJ2000S?: number;
+  sourceEpochJ2000S?: number;
+  stalenessS?: number;
+  maxStalenessS?: number;
+  context?: string;
+}
+
+/** The structured `.detail` attached to a thrown `solveWithFallback` `Error`.
+ * `name` names which path's solve failed and `message` carries the underlying
+ * solve error. */
+export interface FallbackErrorDetail {
+  name: "PreciseSolveError" | "BroadcastSolveError";
+  message: string;
+}
+
+/** Why `solveWithFallback` produced a fix from broadcast ephemeris. */
+export interface BroadcastReason {
+  kind: "preciseUnavailable" | "preciseDegradedUnusable";
+  /** The precise selection's rejection, for `"preciseUnavailable"`. */
+  selectionError: SelectionErrorDetail | null;
+  /** The tried precise product's staleness, for `"preciseDegradedUnusable"`. */
+  attemptedStaleness: StalenessMetadata | null;
+  /** The precise solve error that triggered the fallback, for
+   * `"preciseDegradedUnusable"`. */
+  preciseError: string | null;
+}
+
+/** Which ephemeris source produced a `SourcedSolution`, read from
+ * `SourcedSolution.source`. For a precise fix `staleness` is the product's
+ * metadata and `broadcastReason` is `null`; for a broadcast fix `staleness` is
+ * `null` and `broadcastReason` records why precise was not used. */
+export interface FixSource {
+  kind: "precise" | "broadcast";
+  isPrecise: boolean;
+  isBroadcast: boolean;
+  isPreciseExact: boolean;
+  staleness: StalenessMetadata | null;
+  broadcastReason: BroadcastReason | null;
+}