@neilberkman/sidereon 0.12.0 → 0.14.0

package/pkg-node/sidereon.d.ts

@@ -305,6 +305,25 @@ export class BroadcastEphemeris {
      * J2000 seconds. Returns `undefined` when no usable record covers the query.
      */
     evaluate(satellite: string, t_j2000_s: number): BroadcastStoreEvaluation | undefined;
+    /**
+     * Query ECEF position and clock for parallel satellite and epoch arrays
+     * against this parsed broadcast ephemeris store.
+     *
+     * `satellites[i]` is evaluated at `epochsJ2000S[i]`, where epochs are
+     * seconds since J2000 in GPST for GNSS broadcast records. The returned
+     * plain object has aligned `positionsEcefM`, `clocksS`, `statuses`, and
+     * `elementResults` arrays.
+     */
+    observableStatesAtJ2000S(satellites: any, epochs_j2000_s: any): any;
+    /**
+     * Query ECEF position and clock for many satellites at one epoch against
+     * this parsed broadcast ephemeris store.
+     *
+     * `epochJ2000S` is seconds since J2000 in GPST. The returned object follows
+     * the same contract as
+     * [`observableStatesAtJ2000S`](Self::observable_states_at_j2000_s).
+     */
+    observableStatesAtSharedJ2000S(satellites: any, epoch_j2000_s: number): any;
     /**
      * Solve a receiver position from broadcast ephemeris ALONE: the supported
      * real-time / offline single-point-positioning mode. `request` is the same
@@ -1845,6 +1864,43 @@ export class GeoidGrid {
     undulationsRad(points_rad: Float64Array): Float64Array;
 }
 
+/**
+ * Geometry observability and covariance-validation diagnostics.
+ */
+export class GeometryQuality {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Singular-value condition number of the design matrix.
+     */
+    readonly conditionNumber: number;
+    /**
+     * Whether residuals or a propagated prior validated the covariance bound.
+     */
+    readonly covarianceValidated: boolean;
+    /**
+     * Geometric dilution of precision for the solved state.
+     */
+    readonly gdop: number;
+    /**
+     * Whether residual-based RAIM can test the solve.
+     */
+    readonly raimCheckable: boolean;
+    /**
+     * Rank of the design matrix used by the solve.
+     */
+    readonly rank: number;
+    /**
+     * Observation redundancy, `nObs - nParams`.
+     */
+    readonly redundancy: number;
+    /**
+     * Observability and validation tier.
+     */
+    readonly tier: ObservabilityTier;
+}
+
 /**
  * One GLONASS broadcast state-vector record. `toeUtcJ2000S` is UTC seconds past
  * J2000; position is PZ-90.11 ECEF metres, velocity m/s, acceleration m/s^2.
@@ -3257,6 +3313,34 @@ export class ObsPhaseShift {
     readonly system: GnssSystem;
 }
 
+/**
+ * Observability and validation tier for an estimation design.
+ *
+ * `ZeroRedundancy` means the design is full rank but has no residual degrees of
+ * freedom, so snapshot-solve covariance bounds are unvalidated unless a
+ * propagated prior is present. `Weak` means the design exceeded the configured
+ * condition-number or GDOP cutoff; the returned bounds are reported as computed
+ * and are not clamped.
+ */
+export enum ObservabilityTier {
+    /**
+     * At least one estimated parameter is not observable.
+     */
+    RankDeficient = 0,
+    /**
+     * Full rank with no residual degrees of freedom.
+     */
+    ZeroRedundancy = 1,
+    /**
+     * Full rank with residual degrees of freedom, but above a cutoff.
+     */
+    Weak = 2,
+    /**
+     * Full rank and within the configured cutoffs.
+     */
+    Nominal = 3,
+}
+
 /**
  * Optional observation-code allow-list for raw and carrier-phase rows. Build
  * with `new ObservationFilter()` then chain `.withSystem(system, codes)`.
@@ -4179,6 +4263,80 @@ export class PppFloatSolution {
     readonly ztdResidualM: number | undefined;
 }
 
+/**
+ * A reusable precise-ephemeris interpolant with cached per-satellite nodes.
+ *
+ * Build this handle once from a parsed [`Sp3`] product, raw precise samples, or
+ * a [`PreciseEphemerisSampleSource`], then reuse it for many state or range
+ * queries. The handle delegates to
+ * `sidereon_core::ephemeris::PreciseEphemerisInterpolant`; ECEF positions are
+ * metres, clocks are seconds, and query epochs are seconds since J2000 in the
+ * source time scale.
+ */
+export class PreciseEphemerisInterpolant {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Build a cached interpolant from an existing sample-backed precise source.
+     */
+    static fromPreciseEphemerisSamples(source: PreciseEphemerisSampleSource): PreciseEphemerisInterpolant;
+    /**
+     * Build a cached interpolant directly from precise samples.
+     *
+     * `samples` is the same array accepted by
+     * [`preciseEphemerisSamplesFromSamples`]: each item has `{ sat, epoch,
+     * positionEcefM, clockS?, clockEvent? }`, with epochs in seconds since
+     * J2000 and positions in ECEF metres. Throws a `TypeError` for malformed
+     * JS input and a `RangeError` for sample validation failures.
+     */
+    static fromSamples(samples: any): PreciseEphemerisInterpolant;
+    /**
+     * Build a cached interpolant from a parsed SP3 precise product.
+     *
+     * Nodes are copied from the product's native SP3 records. Query epochs are
+     * seconds since J2000 in the SP3 product time scale.
+     */
+    static fromSp3(sp3: Sp3): PreciseEphemerisInterpolant;
+    /**
+     * Query ECEF position and optional clock for parallel satellite and epoch
+     * arrays using this cached interpolant.
+     *
+     * `satellites[i]` is evaluated at `epochsJ2000S[i]`, where epochs are
+     * seconds since J2000 on this handle's time scale. The returned plain
+     * object has aligned `positionsEcefM`, `clocksS`, `statuses`, and
+     * `elementResults` arrays.
+     */
+    observableStatesAtJ2000S(satellites: any, epochs_j2000_s: any): any;
+    /**
+     * Query ECEF position and optional clock for many satellites at one epoch
+     * using this cached interpolant.
+     *
+     * `epochJ2000S` is seconds since J2000 on this handle's time scale. The
+     * returned object follows the same contract as
+     * [`observableStatesAtJ2000S`](Self::observable_states_at_j2000_s).
+     */
+    observableStatesAtSharedJ2000S(satellites: any, epoch_j2000_s: number): any;
+    /**
+     * Predict geometric ranges for many `(satellite, receiver, epoch)`
+     * requests using this cached interpolant.
+     *
+     * `requests` is an array of `{ sat, receiverEcefM, tRxJ2000S }` objects.
+     * Positions are ECEF metres and epochs are seconds since J2000 on this
+     * handle's time scale. The output matches [`Sp3.predictRanges`].
+     */
+    predictRanges(requests: any, options: any): any;
+    /**
+     * Satellite tokens this handle can interpolate, ascending.
+     */
+    readonly satellites: string[];
+    /**
+     * Source time-scale abbreviation used by this handle's J2000-second axis,
+     * such as `"GPST"`.
+     */
+    readonly timeScale: string;
+}
+
 /**
  * A precise-ephemeris source built from samples rather than parsed SP3 text.
  *
@@ -4190,6 +4348,26 @@ export class PreciseEphemerisSampleSource {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Query ECEF position and optional clock for parallel satellite and epoch
+     * arrays against this sample-backed precise source.
+     *
+     * `satellites[i]` is evaluated at `epochsJ2000S[i]`, where epochs are
+     * seconds since J2000 on the source time scale. The returned plain object
+     * has aligned `positionsEcefM`, `clocksS`, `statuses`, and
+     * `elementResults` arrays. Failed elements use the core missing-position
+     * sentinel and carry the scalar engine error in `elementResults[i].error`.
+     */
+    observableStatesAtJ2000S(satellites: any, epochs_j2000_s: any): any;
+    /**
+     * Query ECEF position and optional clock for many satellites at one epoch
+     * against this sample-backed precise source.
+     *
+     * `epochJ2000S` is seconds since J2000 on the source time scale. The
+     * returned plain object follows the same contract as
+     * [`observableStatesAtJ2000S`](Self::observable_states_at_j2000_s).
+     */
+    observableStatesAtSharedJ2000S(satellites: any, epoch_j2000_s: number): any;
     /**
      * Predict geometric ranges for many requests in one call. See the shared
      * [`predictRanges`](crate::precise_samples::predict_ranges_over) contract;
@@ -4657,6 +4835,11 @@ export class RtkFixedSolution {
      * The underlying float baseline as a `Float64Array` `[dx, dy, dz]`, metres.
      */
     readonly floatBaselineM: Float64Array;
+    /**
+     * Geometry observability and covariance-validation diagnostics for the
+     * float design used by the integer-fixed solve.
+     */
+    readonly geometryQuality: GeometryQuality;
     readonly integerCandidates: number;
     /**
      * Integer ambiguity ratio, or `undefined` when no ratio was computed.
@@ -4666,6 +4849,16 @@ export class RtkFixedSolution {
      * Integer ambiguity-fix status: `"Fixed"` or `"NotFixed"`.
      */
     readonly integerStatus: string;
+    /**
+     * Whether residual-based RAIM can test the float design used by the
+     * integer-fixed solve.
+     */
+    readonly raimCheckable: boolean;
+    /**
+     * Observation redundancy, `nObs - nParams`, for the float design used by
+     * the integer-fixed solve.
+     */
+    readonly redundancy: number;
 }
 
 /**
@@ -4685,9 +4878,24 @@ export class RtkFloatSolution {
     readonly baselineM: Float64Array;
     readonly codeRmsM: number;
     readonly converged: boolean;
+    /**
+     * Geometry observability and covariance-validation diagnostics for the
+     * final double-difference design. `ZeroRedundancy` bounds are unvalidated
+     * for snapshot solves, `Weak` bounds are unclamped, and rank-deficient
+     * designs are returned as a singular-geometry `Error`.
+     */
+    readonly geometryQuality: GeometryQuality;
     readonly iterations: number;
     readonly nObservations: number;
     readonly phaseRmsM: number;
+    /**
+     * Whether residual-based RAIM can test the float design.
+     */
+    readonly raimCheckable: boolean;
+    /**
+     * Observation redundancy, `nObs - nParams`, for the float design.
+     */
+    readonly redundancy: number;
     readonly weightedRmsM: number;
 }
 
@@ -4994,6 +5202,26 @@ export class Sp3 {
      * coverage gap (the engine refuses to extrapolate).
      */
     interpolate(satellite: string, j2000_seconds: Float64Array): Sp3Interpolation;
+    /**
+     * Query ECEF position and optional clock for parallel satellite and epoch
+     * arrays against this parsed SP3 product.
+     *
+     * `satellites[i]` is evaluated at `epochsJ2000S[i]`, where epochs are
+     * seconds since J2000 in the product time scale. The returned plain object
+     * has aligned `positionsEcefM`, `clocksS`, `statuses`, and
+     * `elementResults` arrays. Failed elements use the core missing-position
+     * sentinel and carry the scalar engine error in `elementResults[i].error`.
+     */
+    observableStatesAtJ2000S(satellites: any, epochs_j2000_s: any): any;
+    /**
+     * Query ECEF position and optional clock for many satellites at one epoch
+     * against this parsed SP3 product.
+     *
+     * `epochJ2000S` is seconds since J2000 in the product time scale. The
+     * returned object follows the same contract as
+     * [`observableStatesAtJ2000S`](Self::observable_states_at_j2000_s).
+     */
+    observableStatesAtSharedJ2000S(satellites: any, epoch_j2000_s: number): any;
     /**
      * Predict geometric ranges for many `(satellite, receiver, epoch)` requests
      * against this ephemeris in one call. `requests` is an array of
@@ -5494,10 +5722,25 @@ export class SppSolution {
      * for geodetic output, otherwise `undefined`.
      */
     readonly geodetic: Float64Array | undefined;
+    /**
+     * Geometry observability and covariance-validation diagnostics for this
+     * solved design. `ZeroRedundancy` marks unvalidated snapshot covariance
+     * bounds, `Weak` leaves large bounds unclamped, and rank-deficient designs
+     * are returned as a singular-geometry `Error` rather than a solution.
+     */
+    readonly geometryQuality: GeometryQuality;
     /**
      * ECEF position as a `Float64Array` `[x, y, z]`, metres.
      */
     readonly positionM: Float64Array;
+    /**
+     * Whether residual-based RAIM can test the accepted solve.
+     */
+    readonly raimCheckable: boolean;
+    /**
+     * Degrees of freedom in the accepted solve: `usedCount - (3 + clocks)`.
+     */
+    readonly redundancy: number;
     /**
      * Post-fit residuals, metres, index-aligned to `usedSats`.
      */
@@ -6120,6 +6363,39 @@ export function acquire(samples: Float64Array, prn: bigint, options: any): Acqui
  */
 export function allanDeviation(series: any, tau0_s: number, averaging_factors: any): any;
 
+/**
+ * Alpha-beta measurement update applied to a predicted scalar state.
+ *
+ * `predicted` is `{ level, rate }`, `measurement` has the same unit as
+ * `level`, `dt` is seconds, and `gains` is `{ alpha, beta }`.
+ */
+export function alphaBetaApplyMeasurement(predicted: any, measurement: number, dt: number, gains: any): any;
+
+/**
+ * Run one alpha-beta predict and measurement update.
+ *
+ * `state` is `{ level, rate }`, `measurement` has the same unit as `level`,
+ * `dt` is seconds, and `gains` is `{ alpha, beta }`. Returns `{ predicted,
+ * updated, innovation }`.
+ */
+export function alphaBetaFilterStep(state: any, measurement: number, dt: number, gains: any): any;
+
+/**
+ * Alpha-beta constant-rate prediction.
+ *
+ * `state` is `{ level, rate }` and `dt` is the positive propagation interval in
+ * seconds. Returns the predicted `{ level, rate }`.
+ */
+export function alphaBetaPredict(state: any, dt: number): any;
+
+/**
+ * Steady-state alpha-beta gains from a positive tracking index.
+ *
+ * Returns `{ alpha, beta }`, where `alpha` is the level gain and `beta` maps
+ * innovation to rate through `beta * innovation / dt`.
+ */
+export function alphaBetaSteadyStateGains(tracking_index: number): any;
+
 /**
  * On-sky angle in degrees between two direction vectors.
  */
@@ -6226,6 +6502,38 @@ export function carrierBandName(band: CarrierBand): string;
  */
 export function carrierFrequencyHz(system: GnssSystem, band: CarrierBand): number | undefined;
 
+/**
+ * CA-CFAR false alarm probability from searched-cell count, absolute
+ * threshold, and mean noise level.
+ */
+export function cfarCaFalseAlarmProbability(searched_cells: number, threshold: number, noise_level: number): number;
+
+/**
+ * CA-CFAR threshold multiplier from searched-cell count and target false alarm
+ * probability.
+ */
+export function cfarCaMultiplierFromPfa(searched_cells: number, false_alarm_probability: number): number;
+
+/**
+ * CA-CFAR false alarm probability from searched-cell count and multiplier.
+ */
+export function cfarCaPfaFromMultiplier(searched_cells: number, multiplier: number): number;
+
+/**
+ * CA-CFAR absolute threshold from searched-cell count, target false alarm
+ * probability, and mean noise level.
+ */
+export function cfarCaThreshold(searched_cells: number, false_alarm_probability: number, noise_level: number): number;
+
+/**
+ * Compute the closed-form Chan-Ho seed used by [`locateSource`].
+ *
+ * `mode` is `"toa"`, `"tdoa"`, or `{ mode: "tdoa", referenceSensor }`.
+ * Per-sensor speed overrides are not used by the closed-form equations, but
+ * they are used by [`locateSource`] during iterative refinement.
+ */
+export function chanHoInitialGuess(sensors: any, arrival_times_s: any, propagation_speed_m_s: number, mode: any): any;
+
 /**
  * Returns `true` when a diff has any findings.
  */
@@ -6633,6 +6941,19 @@ export function estimateDecay(drag: DragForce, request: any): any;
  */
 export function estimateDecayWithSpaceWeather(drag: DragForce, table: SpaceWeatherTable, request: any): any;
 
+/**
+ * Exponentially weighted moving-average update.
+ *
+ * `alpha` must be in `[0, 1]`; the returned value is
+ * `previous + alpha * (sample - previous)`.
+ */
+export function ewmaUpdate(previous: number, sample: number, alpha: number): number;
+
+/**
+ * EWMA update with `alpha = 1 / 2^shift`.
+ */
+export function ewmaUpdatePowerOfTwo(previous: number, sample: number, shift: number): number;
+
 /**
  * Find Moon elevation threshold crossings (moonrise / moonset) over a UTC
  * window.
@@ -7074,6 +7395,15 @@ export function j2000SecondsToCivil(seconds: bigint): CivilDateTime;
  */
 export function jarqueBera(x: Float64Array): any;
 
+/**
+ * Steady-state gains for a scalar constant-velocity Kalman filter.
+ *
+ * `trackingIndex`, `dt`, and `measurementVariance` must be positive. Returns
+ * `{ positionGain, rateGain }`; `rateGain * dt` equals the alpha-beta `beta`
+ * gain for the same tracking index.
+ */
+export function kalmanCvSteadyStateGains(tracking_index: number, dt: number, measurement_variance: number): any;
+
 /**
  * GPS broadcast Klobuchar ionospheric group delay in the model's native units
  * (positive metres).
@@ -7286,12 +7616,38 @@ export function loadRinexObs(bytes: Uint8Array): RinexObs;
  */
 export function loadSp3(bytes: Uint8Array): Sp3;
 
+/**
+ * Locate a source from sensor arrival times.
+ *
+ * `sensors` is an array of `{ positionM, propagationSpeedMS? }`; each
+ * `positionM` is a 2D or 3D Cartesian metre vector and all sensors must share
+ * the same dimension. `arrivalTimesS` is an aligned seconds array,
+ * `propagationSpeedMS` is the call-level speed in metres per second, and
+ * `options` may include `mode`, `referenceSensor`, `timingSigmaS`, `loss`,
+ * `fScaleS`, `ftol`, `xtol`, `gtol`, and `maxNfev`.
+ */
+export function locateSource(sensors: any, arrival_times_s: any, propagation_speed_m_s: number, options: any): any;
+
 export function lunarSolarEclipses(start_unix_us: bigint, end_unix_us: bigint, step_s: number, tolerance_s: number): any;
 
 export function lunarSolarEclipsesSpk(spk: Spk, start_unix_us: bigint, end_unix_us: bigint, step_s: number, tolerance_s: number): any;
 
 export function lvlhRotation(position_km: Float64Array, velocity_km_s: Float64Array): Float64Array;
 
+/**
+ * Gaussian consistency factor applied by [`madSpread`].
+ */
+export function madGaussianConsistency(): number;
+
+/**
+ * Median absolute deviation spread estimate.
+ *
+ * `values` is a JS number array. The returned spread is
+ * `MAD_GAUSSIAN_CONSISTENCY * median(abs(value - median(values)))`, floored by
+ * `scaleFloor`.
+ */
+export function madSpread(values: any, scale_floor: number): number;
+
 export function meanMotionCircular(radius_km: number): number;
 
 export function meanMotionFromState(position_km: Float64Array, velocity_km_s: Float64Array): number;
@@ -7425,6 +7781,28 @@ export function nequickGDelayM(_eval: any, frequency_hz: number): number;
  */
 export function nequickGStecTecu(_eval: any): number;
 
+/**
+ * Scalar normalized innovation squared statistic.
+ */
+export function nis(innovation: number, innovation_variance: number): number;
+
+/**
+ * Bar-Shalom expected NIS value for `dof` measurement degrees of freedom.
+ */
+export function nisExpectedValue(dof: number): number;
+
+/**
+ * Test a scalar innovation against a chi-square NIS gate.
+ *
+ * Returns `{ nis, threshold, inGate, dof }`, with `confidence` in `(0, 1)`.
+ */
+export function nisGate(innovation: number, innovation_variance: number, dof: number, confidence: number): any;
+
+/**
+ * Chi-square NIS gate threshold for `dof` and confidence probability.
+ */
+export function nisGateThreshold(dof: number, confidence: number): number;
+
 /**
  * Parse bytes and return grouped epoch snapshots directly.
  */
@@ -7455,11 +7833,31 @@ export function noiseAmplification(f1_hz: number, f2_hz: number): number;
  */
 export function normalCovariance(jacobian: Float64Array, m: number, n: number, variance_scale: number): Float64Array;
 
+/**
+ * Scalar normalized innovation `innovation / sqrt(innovationVariance)`.
+ */
+export function normalizedInnovation(innovation: number, innovation_variance: number): number;
+
 /**
  * Build the NTRIP connection request bytes for a config object.
  */
 export function ntripRequestBytes(config: any): Uint8Array;
 
+/**
+ * Stable string label for an [`ObservabilityTier`] enum value.
+ */
+export function observabilityTierLabel(tier: ObservabilityTier): string;
+
+/**
+ * Missing-position sentinel used in failed observable-state batch elements.
+ *
+ * The returned JS value is `[NaN, NaN, NaN]`, matching
+ * `sidereon_core::ephemeris::OBSERVABLE_STATE_MISSING_POSITION_ECEF_M`. Always
+ * check `elementResults[i].ok` or `statuses[i]` before using
+ * `positionsEcefM[i]`.
+ */
+export function observableStateMissingPositionEcefM(): any;
+
 /**
  * Predict observables for one satellite from a broadcast ephemeris store.
  * Delegates to `sidereon_core::observables::predict`.
@@ -8209,6 +8607,33 @@ export function solveVelocityBroadcast(broadcast: BroadcastEphemeris, observatio
  */
 export function solveWithFallback(precise: Sp3[], broadcast: BroadcastEphemeris, request: any, policy: any): SourcedSolution;
 
+/**
+ * Compute the timing Cramer-Rao lower bound for a proposed source position.
+ *
+ * The covariance is `(H^T H)^-1 * timingSigmaS^2`; position blocks are square
+ * metres and origin-time variance is square seconds.
+ */
+export function sourceCrlb(sensors: any, source_position_m: any, propagation_speed_m_s: number, timing_sigma_s: number): any;
+
+/**
+ * Compute timing DOP for a proposed source position.
+ *
+ * `sourcePositionM` is a 2D or 3D Cartesian metre vector in the same frame as
+ * the sensors. The returned DOP values multiply timing sigma in seconds to
+ * produce metres in the caller's Cartesian axes.
+ */
+export function sourceDop(sensors: any, source_position_m: any, propagation_speed_m_s: number): any;
+
+/**
+ * Return the plain mode object for TDOA solves against `referenceSensor`.
+ */
+export function sourceSolveModeTdoa(reference_sensor: number): any;
+
+/**
+ * Return the plain mode value for absolute time-of-arrival solves.
+ */
+export function sourceSolveModeToa(): string;
+
 /**
  * Extract a parsed SP3 product as the canonical precise-ephemeris samples, one
  * per real position record in ascending epoch order.