@neilberkman/sidereon 0.12.0 → 0.13.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
@@ -4179,6 +4198,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 +4283,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;
@@ -4994,6 +5107,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
@@ -6120,6 +6253,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 +6392,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 +6831,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 +7285,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 +7506,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 +7671,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 +7723,26 @@ 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;
 
+/**
+ * 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 +8492,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.