@mearman/doppler 0.0.0 → 1.0.0

package/dist-cli/doppler.mjs

@@ -0,0 +1,3085 @@
+#!/usr/bin/env node
+import { closeSync, openSync, readFileSync, readdirSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { z } from "zod";
+import { gunzipSync } from "node:zlib";
+import { join } from "node:path";
+// src/physics/atmosphere.ts
+/** Adiabatic index of dry air. */
+const GAMMA_DRY_AIR = 1.4;
+/** Specific gas constant for dry air in J/(kg*K). */
+const R_DRY_AIR = 287.058;
+/** Absolute zero offset in Celsius. */
+const KELVIN_OFFSET = 273.15;
+/** Lowest air temperature in kelvin that `speedOfSoundAtTempMps` evaluates, below any temperature found in the troposphere (about -93 degrees Celsius), so that an implausible input cannot drive the speed of sound towards zero. */
+const MIN_AIR_TEMPERATURE_KELVIN = 180;
+/**
+* Computes the local phase speed of sound in meters per second at a given temperature in Celsius.
+* @param tempCelsius - Ambient air temperature in degrees Celsius.
+* @returns Speed of sound in m/s.
+*/
+function speedOfSoundAtTempMps(tempCelsius) {
+	const tempKelvin = Math.max(MIN_AIR_TEMPERATURE_KELVIN, tempCelsius + KELVIN_OFFSET);
+	return Math.sqrt(GAMMA_DRY_AIR * R_DRY_AIR * tempKelvin);
+}
+// src/physics/geo.ts
+/** WGS84 equatorial radius in meters. */
+const WGS84_A = 6378137;
+/** WGS84 first eccentricity squared. */
+const WGS84_E2 = .00669437999014;
+/** Latitude of either pole in degrees, the bound of the valid latitude range. */
+const POLE_LATITUDE_DEG = 90;
+/** Degrees to radians conversion factor. */
+const DEG_TO_RAD = Math.PI / 180;
+/** Radians to degrees conversion factor. */
+const RAD_TO_DEG = 180 / Math.PI;
+/**
+* Mean length of one degree of latitude in metres on the WGS84 ellipsoid, the constant term of the cosine series `MEAN - COS2 * cos(2 * lat) + COS4 * cos(4 * lat)`.
+* Source: "Geographic coordinate system", section "Length of a degree" (https://en.wikipedia.org/wiki/Geographic_coordinate_system#Length_of_a_degree).
+*/
+const METERS_PER_DEG_LAT_MEAN = 111132.92;
+/** Amplitude of the second-harmonic term of the metres-per-degree-of-latitude series, in metres per degree. */
+const METERS_PER_DEG_LAT_COS2 = 559.82;
+/** Amplitude of the fourth-harmonic term of the metres-per-degree-of-latitude series, in metres per degree. */
+const METERS_PER_DEG_LAT_COS4 = 1.175;
+/** Harmonic order of the second latitude term. */
+const LAT_FOURTH_HARMONIC = 4;
+/**
+* Fundamental amplitude of the length of one degree of longitude in metres on the WGS84 ellipsoid, as a cosine series in the latitude: `LON_COS1 * cos(lat) - LON_COS3 * cos(3 * lat)`.
+* Source: "Geographic coordinate system", section "Length of a degree" (https://en.wikipedia.org/wiki/Geographic_coordinate_system#Length_of_a_degree).
+*/
+const METERS_PER_DEG_LON_COS1 = 111412.84;
+/** Amplitude of the third-harmonic term of the metres-per-degree-of-longitude series, in metres per degree. */
+const METERS_PER_DEG_LON_COS3 = 93.5;
+/** Harmonic order of the longitude series correction term. */
+const LON_THIRD_HARMONIC = 3;
+/** Floor on the metres per degree of longitude in metres per degree, so that an offset at a pole divides by a small positive length instead of zero. */
+const MIN_METERS_PER_DEG_LON = .001;
+/**
+* Converts a geodetic coordinate (latitude, longitude, altitude) to Earth-Centered, Earth-Fixed (ECEF) Cartesian coordinates in meters.
+* @param point - Geodetic coordinate on or above WGS84.
+* @returns ECEF vector in meters.
+*/
+function geoToEcef(point) {
+	const latRad = point.lat * DEG_TO_RAD;
+	const lonRad = point.lon * DEG_TO_RAD;
+	const sinLat = Math.sin(latRad);
+	const cosLat = Math.cos(latRad);
+	const sinLon = Math.sin(lonRad);
+	const cosLon = Math.cos(lonRad);
+	const primeVerticalRadius = WGS84_A / Math.sqrt(1 - WGS84_E2 * sinLat * sinLat);
+	return {
+		x: (primeVerticalRadius + point.altMeters) * cosLat * cosLon,
+		y: (primeVerticalRadius + point.altMeters) * cosLat * sinLon,
+		z: (primeVerticalRadius * .99330562000986 + point.altMeters) * sinLat
+	};
+}
+/**
+* Converts a global displacement between two geodetic points into local East-North-Up (ENU) meters relative to the origin point.
+* @param origin - Reference observer coordinate.
+* @param target - Target aircraft or ground coordinate.
+* @returns Local tangent-plane ENU vector in meters (x = East, y = North, z = Up).
+*/
+function geoToLocalEnu(origin, target) {
+	const originEcef = geoToEcef(origin);
+	const targetEcef = geoToEcef(target);
+	const dx = targetEcef.x - originEcef.x;
+	const dy = targetEcef.y - originEcef.y;
+	const dz = targetEcef.z - originEcef.z;
+	const latRad = origin.lat * DEG_TO_RAD;
+	const lonRad = origin.lon * DEG_TO_RAD;
+	const sinLat = Math.sin(latRad);
+	const cosLat = Math.cos(latRad);
+	const sinLon = Math.sin(lonRad);
+	const cosLon = Math.cos(lonRad);
+	return {
+		x: -sinLon * dx + cosLon * dy,
+		y: -sinLat * cosLon * dx - sinLat * sinLon * dy + cosLat * dz,
+		z: cosLat * cosLon * dx + cosLat * sinLon * dy + sinLat * dz
+	};
+}
+/**
+* Projects a local East-North-Up (ENU) offset in meters from a reference geodetic origin back to geodetic coordinates.
+* @param origin - Reference coordinate.
+* @param enuOffset - Offset in local meters (x = East, y = North, z = Up).
+* @returns Resulting geodetic coordinate.
+*/
+function localEnuToGeo(origin, enuOffset) {
+	const latRad = origin.lat * DEG_TO_RAD;
+	const metersPerDegLat = METERS_PER_DEG_LAT_MEAN - METERS_PER_DEG_LAT_COS2 * Math.cos(2 * latRad) + METERS_PER_DEG_LAT_COS4 * Math.cos(LAT_FOURTH_HARMONIC * latRad);
+	const metersPerDegLon = Math.max(MIN_METERS_PER_DEG_LON, METERS_PER_DEG_LON_COS1 * Math.cos(latRad) - METERS_PER_DEG_LON_COS3 * Math.cos(LON_THIRD_HARMONIC * latRad));
+	return {
+		lat: Math.max(-90, Math.min(POLE_LATITUDE_DEG, origin.lat + enuOffset.y / metersPerDegLat)),
+		lon: ((origin.lon + enuOffset.x / metersPerDegLon + 180) % 360 + 360) % 360 - 180,
+		altMeters: origin.altMeters + enuOffset.z
+	};
+}
+/** Highest resolution tier that uses the coarse cell size. */
+const COARSE_RESOLUTION_MAX = 4;
+/** Highest resolution tier that uses the medium cell size; tiers above it use the fine cell size. */
+const MEDIUM_RESOLUTION_MAX = 6;
+/** Cell side in degrees for the coarse tier (about 20 km). */
+const COARSE_CELL_STEP_DEG = .2;
+/** Cell side in degrees for the medium tier (about 3.5 km). */
+const MEDIUM_CELL_STEP_DEG = .032;
+/** Cell side in degrees for the fine tier (about 500 m). */
+const FINE_CELL_STEP_DEG = .005;
+/** Fraction of a cell side from a cell's lower edge to its centre. */
+const CELL_CENTRE_FRACTION = .5;
+/** Squared distance below which a terrain sample counts as coincident with the query point, in the squared units of the weighting distance in `interpolateTerrainElevationMeters`. */
+const COINCIDENT_SAMPLE_DISTANCE_SQ = 1e-12;
+/**
+* Looks up the side of a spatial cell for a resolution tier.
+* @param resolution - Grid resolution tier.
+* @returns Cell side in degrees.
+*/
+function cellStepDeg(resolution) {
+	if (resolution <= COARSE_RESOLUTION_MAX) return COARSE_CELL_STEP_DEG;
+	return resolution <= MEDIUM_RESOLUTION_MAX ? MEDIUM_CELL_STEP_DEG : FINE_CELL_STEP_DEG;
+}
+/**
+* Computes the 3D Euclidean slant distance in meters between two geodetic coordinates.
+* @param a - First 3D point.
+* @param b - Second 3D point.
+* @returns Slant distance in meters.
+*/
+function slantDistanceMeters(a, b) {
+	const ea = geoToEcef(a);
+	const eb = geoToEcef(b);
+	return Math.hypot(ea.x - eb.x, ea.y - eb.y, ea.z - eb.z);
+}
+/**
+* Encodes a latitude/longitude coordinate into a deterministic hierarchical spatial cell identifier at a given resolution step.
+* @param lat - Latitude in degrees.
+* @param lon - Longitude in degrees.
+* @param resolution - Grid resolution tier (4 = ~20km, 6 = ~3.5km, 8 = ~500m).
+* @returns Deterministic cell string identifier.
+*/
+function encodeSpatialCell(lat, lon, resolution = 6) {
+	const stepDeg = cellStepDeg(resolution);
+	const latIdx = Math.floor((lat + POLE_LATITUDE_DEG) / stepDeg);
+	const lonIdx = Math.floor((lon + 180) / stepDeg);
+	return `h3r${String(resolution)}_${String(latIdx)}_${String(lonIdx)}`;
+}
+/**
+* Decodes a spatial cell identifier back to its center latitude and longitude in degrees.
+* @param cellId - Spatial cell identifier produced by `encodeSpatialCell`.
+* @returns Center latitude and longitude in degrees.
+*/
+function decodeSpatialCellCenter(cellId) {
+	const match = /^h3r(\d+)_(-?\d+)_(-?\d+)$/.exec(cellId);
+	if (match === null) throw new Error(`Invalid spatial cell identifier: ${cellId}`);
+	const resolution = Number(match[1]);
+	const latIdx = Number(match[2]);
+	const lonIdx = Number(match[3]);
+	const stepDeg = cellStepDeg(resolution);
+	return {
+		lat: -90 + (latIdx + CELL_CENTRE_FRACTION) * stepDeg,
+		lon: -180 + (lonIdx + CELL_CENTRE_FRACTION) * stepDeg
+	};
+}
+/**
+* Evaluates terrain elevation at a target coordinate via inverse-distance-weighted interpolation over a DEM grid.
+* @param lat - Target latitude in degrees.
+* @param lon - Target longitude in degrees.
+* @param demGrid - Sparse or regular grid of elevation samples.
+* @returns Interpolated terrain elevation in meters above sea level.
+*/
+function interpolateTerrainElevationMeters(lat, lon, demGrid) {
+	if (demGrid.length === 0) return 0;
+	let weightedSum = 0;
+	let weightTotal = 0;
+	for (const sample of demGrid) {
+		const dLat = (lat - sample.lat) * RAD_TO_DEG;
+		const dLon = (lon - sample.lon) * RAD_TO_DEG;
+		const distSq = dLat * dLat + dLon * dLon;
+		if (distSq < COINCIDENT_SAMPLE_DISTANCE_SQ) return sample.altMeters;
+		const weight = 1 / distSq;
+		weightedSum += sample.altMeters * weight;
+		weightTotal += weight;
+	}
+	return weightTotal > 0 ? weightedSum / weightTotal : 0;
+}
+// src/physics/retarded-time.ts
+/** Smallest margin `c^2 - v^2` in m^2/s^2 accepted by `solveRetardedDelaySec`; a source this close to the speed of sound makes the quadratic's leading coefficient vanish, so it is treated as outside the subsonic domain. */
+const MIN_SUBSONIC_MARGIN_SQ = .001;
+/** Shortest segment duration in seconds used as the divisor of a segment's velocity, so a zero-length segment cannot divide by zero. */
+const MIN_SEGMENT_DURATION_SEC$1 = .001;
+/** Squared speed in m^2/s^2 below which a segment counts as stationary, so the closest-approach offset is zero instead of a division by a near-zero speed. */
+const MIN_SEGMENT_SPEED_SQ = 1e-6;
+/** Slant distance in metres below which the radial velocity is taken as zero, because the line of sight is undefined at the source position. */
+const MIN_RADIAL_DIRECTION_DISTANCE_METERS = .001;
+/**
+* Solves the exact subsonic Liénard-Wiechert retarded-time propagation delay `Δt = t_obs - t_emit` in closed form for a uniform linear trajectory segment.
+*
+* Given an aircraft position `r(t_emit) = r(t_obs) - v * Δt`, the acoustic propagation condition
+* `c^2 * Δt^2 = || r(t_obs) - x_obs - v * Δt ||^2` is a quadratic equation in `Δt`:
+* `(c^2 - v^2) * Δt^2 + 2 * (Δr · v) * Δt - ||Δr||^2 = 0`
+* @param deltaPosEnu - Displacement vector `r(t_obs) - x_obs` in local ENU meters at reception time `t_obs`.
+* @param velocityEnu - Aircraft velocity vector in local ENU meters per second.
+* @param soundSpeedMps - Local speed of sound in meters per second.
+* @returns Exact retarded propagation delay `Δt >= 0` in seconds.
+*/
+function solveRetardedDelaySec(deltaPosEnu, velocityEnu, soundSpeedMps) {
+	const vSq = velocityEnu.x * velocityEnu.x + velocityEnu.y * velocityEnu.y + velocityEnu.z * velocityEnu.z;
+	const cSq = soundSpeedMps * soundSpeedMps;
+	const cSqMinusVSq = cSq - vSq;
+	if (cSqMinusVSq <= MIN_SUBSONIC_MARGIN_SQ) throw new Error(`Supersonic or sonic source speed (v^2=${String(vSq)}, c^2=${String(cSq)}) is outside subsonic domain`);
+	const rSq = deltaPosEnu.x * deltaPosEnu.x + deltaPosEnu.y * deltaPosEnu.y + deltaPosEnu.z * deltaPosEnu.z;
+	const vDotR = velocityEnu.x * deltaPosEnu.x + velocityEnu.y * deltaPosEnu.y + velocityEnu.z * deltaPosEnu.z;
+	const discriminant = cSqMinusVSq * rSq + vDotR * vDotR;
+	return (-vDotR + Math.sqrt(Math.max(0, discriminant))) / cSqMinusVSq;
+}
+/**
+* Computes the analytical Closest Point of Approach (CPA) emission time, delayed reception time, and 3D slant distance for an observer relative to a linear flight segment.
+* @param observer - Candidate ground observer 3D coordinate.
+* @param segment - Linear flight segment.
+* @param soundSpeedMps - Effective speed of sound in m/s.
+* @returns Emission CPA timestamp, delayed observer CPA timestamp, and minimum 3D slant distance in meters.
+*/
+function computeSegmentCpa(observer, segment, soundSpeedMps = 343) {
+	const duration = Math.max(MIN_SEGMENT_DURATION_SEC$1, segment.endEpochSec - segment.startEpochSec);
+	const startEnu = geoToLocalEnu(observer, segment.startGeo);
+	const endEnu = geoToLocalEnu(observer, segment.endGeo);
+	const vx = (endEnu.x - startEnu.x) / duration;
+	const vy = (endEnu.y - startEnu.y) / duration;
+	const vz = (endEnu.z - startEnu.z) / duration;
+	const vSq = vx * vx + vy * vy + vz * vz;
+	const unclampedOffsetSec = vSq > MIN_SEGMENT_SPEED_SQ ? -(startEnu.x * vx + startEnu.y * vy + startEnu.z * vz) / vSq : 0;
+	const cpaOffsetSec = Math.max(0, Math.min(duration, unclampedOffsetSec));
+	const cpaPosX = startEnu.x + vx * cpaOffsetSec;
+	const cpaPosY = startEnu.y + vy * cpaOffsetSec;
+	const cpaPosZ = startEnu.z + vz * cpaOffsetSec;
+	const cpaSlantMeters = Math.hypot(cpaPosX, cpaPosY, cpaPosZ);
+	const cpaEmitEpochSec = segment.startEpochSec + cpaOffsetSec;
+	return {
+		cpaEmitEpochSec,
+		cpaDelayedEpochSec: cpaEmitEpochSec + cpaSlantMeters / soundSpeedMps,
+		cpaSlantMeters
+	};
+}
+/**
+* Synthesizes the exact retarded-time Doppler curve observed on the ground for a linear flight segment at specified reception timestamps.
+* @param observer - Ground observer 3D coordinate.
+* @param segment - Linear flight segment.
+* @param options - Base frequency, observation timestamps, and optional sound speed.
+* @returns Evaluated retarded acoustic trajectory at each reception timestamp.
+*/
+function synthesizeRetardedDopplerCurve(observer, segment, options) {
+	const { baseFreqHz, obsEpochTimesSec, soundSpeedMps = 343 } = options;
+	const duration = Math.max(MIN_SEGMENT_DURATION_SEC$1, segment.endEpochSec - segment.startEpochSec);
+	const startEnu = geoToLocalEnu(observer, segment.startGeo);
+	const endEnu = geoToLocalEnu(observer, segment.endGeo);
+	const velocityEnu = {
+		x: (endEnu.x - startEnu.x) / duration,
+		y: (endEnu.y - startEnu.y) / duration,
+		z: (endEnu.z - startEnu.z) / duration
+	};
+	return obsEpochTimesSec.map((obsTimeSec) => {
+		const dtFromStart = obsTimeSec - segment.startEpochSec;
+		const delaySec = solveRetardedDelaySec({
+			x: startEnu.x + velocityEnu.x * dtFromStart,
+			y: startEnu.y + velocityEnu.y * dtFromStart,
+			z: startEnu.z + velocityEnu.z * dtFromStart
+		}, velocityEnu, soundSpeedMps);
+		const emitTimeSec = obsTimeSec - delaySec;
+		const emitDtFromStart = emitTimeSec - segment.startEpochSec;
+		const emitPosEnu = {
+			x: startEnu.x + velocityEnu.x * emitDtFromStart,
+			y: startEnu.y + velocityEnu.y * emitDtFromStart,
+			z: startEnu.z + velocityEnu.z * emitDtFromStart
+		};
+		const slantDistanceMeters = Math.hypot(emitPosEnu.x, emitPosEnu.y, emitPosEnu.z);
+		const radialVelocityMps = slantDistanceMeters > MIN_RADIAL_DIRECTION_DISTANCE_METERS ? -(emitPosEnu.x * velocityEnu.x + emitPosEnu.y * velocityEnu.y + emitPosEnu.z * velocityEnu.z) / slantDistanceMeters : 0;
+		return {
+			obsTimeSec,
+			emitTimeSec,
+			delaySec,
+			slantDistanceMeters,
+			radialVelocityMps,
+			observedFreqHz: baseFreqHz * (soundSpeedMps / (soundSpeedMps - radialVelocityMps))
+		};
+	});
+}
+// src/dsp/constants.ts
+/**
+* Sample rate in Hz of the decimated audio that every analysis stage consumes. Its Nyquist limit of 1000 Hz sits above the top of the analysis band while keeping each FFT short.
+*/
+const ANALYSIS_SAMPLE_RATE_HZ = 2e3;
+/**
+* Smallest FFT length in samples used for Electric Network Frequency (ENF) detection. At the analysis rate it resolves bins of about 0.49 Hz, fine enough to separate 50 Hz from 60 Hz with room for the neighbouring bins.
+*/
+const ENF_MIN_FFT_SIZE = 4096;
+/**
+* Power in dB substituted for a spectrum bin that does not exist, far below any recorded level so that it never wins a maximum.
+*/
+const MISSING_BIN_POWER_DB = -120;
+/**
+* Noise floor in dB reported when a search band holds no background bins to take a median of.
+*/
+const NO_BACKGROUND_NOISE_FLOOR_DB = -100;
+// src/dsp/fft.ts
+/**
+* One full turn in radians (a complete circle, 2 pi): the phase span of the twiddle factors of a transform and of the Hann window.
+*/
+const FULL_TURN_RADIANS = 2 * Math.PI;
+/**
+* Hann window coefficient scale: the window is `0.5 * (1 - cos(2 pi i / (N - 1)))`, a raised cosine that tapers both ends of the frame to zero.
+*/
+const HANN_SCALE = .5;
+/**
+* Smallest squared magnitude passed to the logarithm, so that an all-zero bin reports -200 dB instead of negative infinity. Squared magnitude is a power, so the floor is 10 * log10(1e-20) = -200 dB.
+*/
+const POWER_FLOOR = 1e-20;
+/**
+* Decibels per decade of a power ratio: `10 * log10(power)`.
+*/
+const DB_PER_POWER_DECADE = 10;
+/**
+* Computes a Radix-2 Cooley-Tukey Complex Fast Fourier Transform without modifying its inputs: the samples are gathered into freshly allocated arrays in bit-reversed order and the butterflies run on those arrays.
+* @param real - Real components array of power-of-two length N.
+* @param imag - Imaginary components array of the same length N.
+* @returns The forward transform (negative-exponent convention, unnormalised) as new arrays.
+* @throws When N is not a positive power of two or the two arrays differ in length.
+*/
+function fft(real, imag) {
+	const n = real.length;
+	if (n === 0 || (n & n - 1) !== 0 || imag.length !== n) throw new Error(`FFT length must be a positive power of two with matching real/imag lengths, got ${String(n)}`);
+	const outReal = new Float64Array(n);
+	const outImag = new Float64Array(n);
+	let j = 0;
+	for (let i = 0; i < n; i += 1) {
+		outReal[i] = real[j] ?? 0;
+		outImag[i] = imag[j] ?? 0;
+		let bit = n >> 1;
+		while (bit >= 1 && (j & bit) !== 0) {
+			j ^= bit;
+			bit >>= 1;
+		}
+		j |= bit;
+	}
+	for (let len = 2; len <= n; len <<= 1) {
+		const halfLen = len >> 1;
+		const angleStep = -FULL_TURN_RADIANS / len;
+		const wStepR = Math.cos(angleStep);
+		const wStepI = Math.sin(angleStep);
+		for (let i = 0; i < n; i += len) {
+			let wR = 1;
+			let wI = 0;
+			for (let k = 0; k < halfLen; k += 1) {
+				const evenIdx = i + k;
+				const oddIdx = evenIdx + halfLen;
+				const oddR = outReal[oddIdx] ?? 0;
+				const oddI = outImag[oddIdx] ?? 0;
+				const tR = wR * oddR - wI * oddI;
+				const tI = wR * oddI + wI * oddR;
+				const evenR = outReal[evenIdx] ?? 0;
+				const evenI = outImag[evenIdx] ?? 0;
+				outReal[oddIdx] = evenR - tR;
+				outImag[oddIdx] = evenI - tI;
+				outReal[evenIdx] = evenR + tR;
+				outImag[evenIdx] = evenI + tI;
+				const nextWR = wR * wStepR - wI * wStepI;
+				wI = wR * wStepI + wI * wStepR;
+				wR = nextWR;
+			}
+		}
+	}
+	return {
+		real: outReal,
+		imag: outImag
+	};
+}
+/**
+* Computes the one-sided Hann-windowed power spectrum in decibels for a real-valued frame.
+* @param samples - Input time-domain samples.
+* @param fftSize - Power-of-two FFT size (zero-padded if `samples.length < fftSize`).
+* @returns One-sided power spectrum in dB (`length = fftSize / 2 + 1`).
+*/
+function computeHannPowerSpectrumDb(samples, fftSize) {
+	const windowed = new Float64Array(fftSize);
+	const winLen = Math.min(samples.length, fftSize);
+	for (let i = 0; i < winLen; i += 1) {
+		const hann = HANN_SCALE * (1 - Math.cos(FULL_TURN_RADIANS * i / Math.max(1, winLen - 1)));
+		windowed[i] = (samples[i] ?? 0) * hann;
+	}
+	const { real, imag } = fft(windowed, new Float64Array(fftSize));
+	const numBins = (fftSize >> 1) + 1;
+	const powerDb = new Float64Array(numBins);
+	const norm = 1 / Math.max(1, winLen);
+	for (let bin = 0; bin < numBins; bin += 1) {
+		const r = (real[bin] ?? 0) * norm;
+		const im = (imag[bin] ?? 0) * norm;
+		const magSq = Math.max(POWER_FLOOR, r * r + im * im);
+		powerDb[bin] = DB_PER_POWER_DECADE * Math.log10(magSq);
+	}
+	return powerDb;
+}
+// src/dsp/side-channels.ts
+/**
+* Detects passive 50.00 Hz vs 60.00 Hz Electrical Network Frequency (ENF) mains hum in an audio buffer to split the global search space by power-grid hemisphere.
+* @param samples - Audio samples.
+* @param sampleRateHz - Sample rate in Hz.
+* @returns Detected ENF nominal grid (50 Hz, 60 Hz, or unknown), SNR, and geographic region hint.
+*/
+function detectEnfSignature(samples, sampleRateHz) {
+	let fftSize = ENF_MIN_FFT_SIZE;
+	while (fftSize * 2 <= samples.length && fftSize < 16384) fftSize <<= 1;
+	if (samples.length < 512) return {
+		detected: false,
+		nominalHz: "unknown",
+		measuredFreqHz: 0,
+		snrDb: 0,
+		regionHint: "Insufficient audio length for ENF analysis"
+	};
+	const spectrumDb = computeHannPowerSpectrumDb(samples, fftSize);
+	const binStepHz = sampleRateHz / fftSize;
+	const bin50 = Math.round(50 / binStepHz);
+	const bin60 = Math.round(60 / binStepHz);
+	const power50Db = Math.max(spectrumDb[bin50 - 1] ?? -120, spectrumDb[bin50] ?? -120, spectrumDb[bin50 + 1] ?? -120);
+	const power60Db = Math.max(spectrumDb[bin60 - 1] ?? -120, spectrumDb[bin60] ?? -120, spectrumDb[bin60 + 1] ?? -120);
+	const bgValues = [];
+	const startBin = Math.max(1, Math.floor(42 / binStepHz));
+	const endBin = Math.min((fftSize >> 1) - 1, Math.ceil(68 / binStepHz));
+	for (let b = startBin; b <= endBin; b += 1) {
+		const hz = b * binStepHz;
+		if (Math.abs(hz - 50) > 1.8 && Math.abs(hz - 60) > 1.8) {
+			const val = spectrumDb[b];
+			if (val !== void 0) bgValues.push(val);
+		}
+	}
+	bgValues.sort((a, b) => a - b);
+	const noiseFloorDb = bgValues.length > 0 ? bgValues[bgValues.length >> 1] ?? -100 : NO_BACKGROUND_NOISE_FLOOR_DB;
+	const snr50 = power50Db - noiseFloorDb;
+	const snr60 = power60Db - noiseFloorDb;
+	if (snr50 >= 6 && snr50 > snr60 + 2) return {
+		detected: true,
+		nominalHz: "50",
+		measuredFreqHz: 50,
+		snrDb: snr50,
+		regionHint: "50 Hz Grid (Europe, UK, Asia, Africa, Australia, E. Japan)"
+	};
+	if (snr60 >= 6 && snr60 > snr50 + 2) return {
+		detected: true,
+		nominalHz: "60",
+		measuredFreqHz: 60,
+		snrDb: snr60,
+		regionHint: "60 Hz Grid (North America, South Korea, Taiwan, W. Japan)"
+	};
+	return {
+		detected: false,
+		nominalHz: "unknown",
+		measuredFreqHz: 0,
+		snrDb: Math.max(0, snr50, snr60),
+		regionHint: "No dominant 50/60 Hz mains hum detected"
+	};
+}
+// src/dsp/channels.ts
+/**
+* Averages equal-length audio channels into one mono signal.
+* @param channels - One sample array per channel; at least one, all of the same length.
+* @returns The mono signal. A single channel is returned as a copy, never the caller's array.
+*/
+function downmixToMono(channels) {
+	const [first] = channels;
+	if (first === void 0) throw new Error("downmixToMono needs at least one channel");
+	const mono = new Float32Array(first.length);
+	for (const channel of channels) {
+		if (channel.length !== first.length) throw new Error("downmixToMono needs channels of equal length");
+		for (let index = 0; index < channel.length; index += 1) mono[index] = (mono[index] ?? 0) + (channel[index] ?? 0);
+	}
+	const count = channels.length;
+	if (count > 1) for (let index = 0; index < mono.length; index += 1) mono[index] = (mono[index] ?? 0) / count;
+	return mono;
+}
+// src/dsp/wav.ts
+/** WAVE format tags (RIFF `fmt ` chunk) this decoder understands. */
+const FORMAT_PCM = 1;
+const FORMAT_FLOAT = 3;
+/** Extensible format: the real tag is the first two bytes of the sub-format GUID. */
+const FORMAT_EXTENSIBLE = 65534;
+/** Offset of the sub-format tag inside an extensible `fmt ` chunk body (after the 16-byte base, size, valid bits and channel mask). */
+const EXTENSIBLE_SUBFORMAT_OFFSET = 24;
+/** Smallest `fmt ` chunk body: tag, channels, rate, byte rate, block align, bits. */
+const MIN_FMT_BODY_BYTES = 16;
+/** Offset of the 16-bit channel count inside a `fmt ` chunk body, after the 16-bit tag. */
+const FMT_CHANNELS_OFFSET = 2;
+/** Offset of the 32-bit sample rate inside a `fmt ` chunk body. */
+const FMT_SAMPLE_RATE_OFFSET = 4;
+/** Offset of the 16-bit bits per sample inside a `fmt ` chunk body. */
+const FMT_BITS_PER_SAMPLE_OFFSET = 14;
+/** Bytes of a four-character code: a chunk id or the RIFF form type. */
+const FOUR_CC_BYTES = 4;
+/** Bytes of a chunk header: four-character id and a 32-bit size. */
+const CHUNK_HEADER_BYTES = 8;
+/** Bytes of the RIFF preamble: `RIFF`, size and `WAVE`. */
+const RIFF_PREAMBLE_BYTES = 12;
+/** Bits in a byte. */
+const BITS_PER_BYTE = 8;
+/** Bit depth of unsigned 8-bit PCM. */
+const PCM_BITS_UINT8 = 8;
+/** Bit depth of signed 16-bit PCM. */
+const PCM_BITS_INT16 = 16;
+/** Bit depth of signed 24-bit PCM. */
+const PCM_BITS_INT24 = 24;
+/** Bit depth of signed 32-bit PCM. */
+const PCM_BITS_INT32 = 32;
+/** Bit depth of single-precision float samples. */
+const FLOAT_BITS_SINGLE = 32;
+/** Bit depth of double-precision float samples. */
+const FLOAT_BITS_DOUBLE = 64;
+/** Magnitude of the most negative signed integer of a bit depth, which maps to -1.0. */
+const signedFullScale = (bits) => 2 ** (bits - 1);
+/** Unsigned 8-bit PCM value that is silence, and the divisor that maps its offset from silence to `[-1, 1)`. */
+const UINT8_MIDPOINT = signedFullScale(PCM_BITS_UINT8);
+/** Divisor that maps a signed 16-bit sample to `[-1, 1)`. */
+const INT16_FULL_SCALE = signedFullScale(PCM_BITS_INT16);
+/** Divisor that maps a signed 24-bit sample to `[-1, 1)`. */
+const INT24_FULL_SCALE = signedFullScale(PCM_BITS_INT24);
+/** Divisor that maps a signed 32-bit sample to `[-1, 1)`. */
+const INT32_FULL_SCALE = signedFullScale(PCM_BITS_INT32);
+function fourCc(view, offset) {
+	return String.fromCharCode(...Array.from({ length: FOUR_CC_BYTES }, (_, index) => view.getUint8(offset + index)));
+}
+function readFormat(view, bodyOffset, bodySize) {
+	if (bodySize < MIN_FMT_BODY_BYTES) throw new Error(`WAV fmt chunk is ${String(bodySize)} bytes, shorter than the ${String(MIN_FMT_BODY_BYTES)} required`);
+	let tag = view.getUint16(bodyOffset, true);
+	if (tag === FORMAT_EXTENSIBLE) {
+		if (bodySize < 26) throw new Error("WAV extensible fmt chunk is too short to name its sub-format");
+		tag = view.getUint16(bodyOffset + EXTENSIBLE_SUBFORMAT_OFFSET, true);
+	}
+	return {
+		tag,
+		channels: view.getUint16(bodyOffset + FMT_CHANNELS_OFFSET, true),
+		sampleRateHz: view.getUint32(bodyOffset + FMT_SAMPLE_RATE_OFFSET, true),
+		bitsPerSample: view.getUint16(bodyOffset + FMT_BITS_PER_SAMPLE_OFFSET, true)
+	};
+}
+/**
+* Reads one sample as a float in `[-1, 1]`.
+* @param view - The file bytes.
+* @param position - Byte offset of the sample.
+* @param format - The decoded `fmt ` chunk.
+* @returns The sample value.
+* @throws When the tag and bit depth are not a supported combination.
+*/
+function readSample(view, position, format) {
+	const { tag, bitsPerSample } = format;
+	if (tag === FORMAT_FLOAT) {
+		if (bitsPerSample === FLOAT_BITS_SINGLE) return view.getFloat32(position, true);
+		if (bitsPerSample === FLOAT_BITS_DOUBLE) return view.getFloat64(position, true);
+	} else if (tag === FORMAT_PCM) switch (bitsPerSample) {
+		case PCM_BITS_UINT8: return (view.getUint8(position) - UINT8_MIDPOINT) / UINT8_MIDPOINT;
+		case PCM_BITS_INT16: return view.getInt16(position, true) / INT16_FULL_SCALE;
+		case PCM_BITS_INT24: return (view.getInt8(position + 2) << 16 | view.getUint8(position + 1) << BITS_PER_BYTE | view.getUint8(position)) / INT24_FULL_SCALE;
+		case PCM_BITS_INT32: return view.getInt32(position, true) / INT32_FULL_SCALE;
+	}
+	throw new Error(`Unsupported WAV sample format: tag ${String(tag)}, ${String(bitsPerSample)} bits`);
+}
+/**
+* Decodes a RIFF WAVE byte buffer into mono samples and its sample rate. Chunks are located by walking the chunk list, so metadata chunks (`JUNK`, `bext`, `LIST`) before `fmt ` or `data` are skipped, and an odd-sized chunk's pad byte is honoured. Multi-channel audio is averaged to mono.
+* @param wavBytes - Raw `.wav` file bytes.
+* @returns Decoded mono samples in `[-1, 1]` and the sample rate in Hz.
+* @throws When the buffer is not RIFF/WAVE, has no `fmt ` or `data` chunk, declares no channels, or uses an unsupported tag or bit depth (8, 16, 24 and 32-bit integer PCM and 32 and 64-bit float are supported).
+*/
+function decodeWavBytes(wavBytes) {
+	if (wavBytes.byteLength < RIFF_PREAMBLE_BYTES) throw new Error(`WAV buffer is shorter than the ${String(RIFF_PREAMBLE_BYTES)}-byte RIFF preamble`);
+	const view = new DataView(wavBytes.buffer, wavBytes.byteOffset, wavBytes.byteLength);
+	const riff = fourCc(view, 0);
+	if (riff !== "RIFF") throw new Error(`Expected RIFF header, got ${riff}`);
+	const form = fourCc(view, CHUNK_HEADER_BYTES);
+	if (form !== "WAVE") throw new Error(`Expected WAVE form, got ${form}`);
+	let format;
+	let dataOffset;
+	let dataLength = 0;
+	let cursor = RIFF_PREAMBLE_BYTES;
+	while (cursor + CHUNK_HEADER_BYTES <= wavBytes.byteLength) {
+		const chunkId = fourCc(view, cursor);
+		const chunkSize = view.getUint32(cursor + FOUR_CC_BYTES, true);
+		const bodyOffset = cursor + CHUNK_HEADER_BYTES;
+		if (chunkId === "fmt ") format = readFormat(view, bodyOffset, Math.min(chunkSize, wavBytes.byteLength - bodyOffset));
+		else if (chunkId === "data") {
+			dataOffset = bodyOffset;
+			dataLength = Math.min(chunkSize, wavBytes.byteLength - bodyOffset);
+		}
+		if (format !== void 0 && dataOffset !== void 0) break;
+		cursor = bodyOffset + chunkSize + chunkSize % 2;
+	}
+	if (format === void 0) throw new Error("WAV file has no fmt chunk");
+	if (dataOffset === void 0) throw new Error("WAV file has no data chunk");
+	if (format.channels < 1) throw new Error("WAV file declares no channels");
+	const bytesPerSample = format.bitsPerSample / BITS_PER_BYTE;
+	const frameStride = format.channels * bytesPerSample;
+	const numFrames = Math.floor(dataLength / frameStride);
+	const channels = Array.from({ length: format.channels }, () => new Float32Array(numFrames));
+	for (let frame = 0; frame < numFrames; frame += 1) for (let channel = 0; channel < format.channels; channel += 1) {
+		const target = channels[channel];
+		if (target !== void 0) target[frame] = readSample(view, dataOffset + frame * frameStride + channel * bytesPerSample, format);
+	}
+	return {
+		samples: downmixToMono(channels),
+		sampleRateHz: format.sampleRateHz
+	};
+}
+// src/solver/constellation.ts
+/** Width in m/s of a groundspeed bucket in a constellation key. A design choice: a wider bucket tolerates more speed measurement error and admits more false pair matches. */
+const SPEED_BUCKET_MPS = 3;
+/** Width in seconds of a closest-approach time-offset bucket in a constellation key. A design choice with the same trade-off as the speed bucket. */
+const DELTA_BUCKET_SEC = 5;
+/** Largest closest-approach slant distance in metres at which a segment is paired within a cell: the acoustic range of an aircraft. */
+const MAX_PAIR_SLANT_METERS = 1e4;
+/** Shortest closest-approach time offset in seconds between two flyovers that forms a pair. */
+const MIN_PAIR_DELTA_SEC = 10;
+/** Longest closest-approach time offset in seconds between two flyovers that forms a pair (40 minutes). */
+const MAX_PAIR_DELTA_SEC = 2400;
+/** Seconds in a UTC day. */
+const SECONDS_PER_DAY = 86400;
+/** Seconds in an hour. */
+const SECONDS_PER_HOUR = 3600;
+/** Hours in a UTC day, the default end of an hour window. */
+const HOURS_PER_DAY$1 = 24;
+/** Westernmost longitude in degrees of the region classed as 60 Hz mains (the Americas). */
+const AMERICAS_MIN_LON_DEG = -170;
+/** Easternmost longitude in degrees of the region classed as 60 Hz mains (the Americas). */
+const AMERICAS_MAX_LON_DEG = -30;
+/**
+* Quantises two groundspeeds and a time offset into the integer buckets of a constellation key.
+* @param speedAMps - Groundspeed of first flyover in m/s.
+* @param speedBMps - Groundspeed of second flyover in m/s.
+* @param deltaSec - Time offset `t_CPA_B - t_CPA_A` in seconds.
+* @returns The speed A, speed B and time-offset bucket indices.
+*/
+function quantiseConstellation(speedAMps, speedBMps, deltaSec) {
+	return [
+		Math.round(speedAMps / SPEED_BUCKET_MPS),
+		Math.round(speedBMps / SPEED_BUCKET_MPS),
+		Math.round(deltaSec / DELTA_BUCKET_SEC)
+	];
+}
+/**
+* Computes a quantized Shazam-style constellation hash key from two aircraft groundspeeds and their delayed CPA time offset.
+* @param speedAMps - Groundspeed of first flyover in m/s.
+* @param speedBMps - Groundspeed of second flyover in m/s.
+* @param deltaSec - Time offset `t_CPA_B - t_CPA_A` in seconds.
+* @returns Quantized constellation hash key string.
+*/
+function formatConstellationKey(speedAMps, speedBMps, deltaSec) {
+	const [qSpeedA, qSpeedB, qDelta] = quantiseConstellation(speedAMps, speedBMps, deltaSec);
+	return `v${String(qSpeedA)}_v${String(qSpeedB)}_dt${String(qDelta)}`;
+}
+/**
+* Generates neighbouring constellation hash keys within measurement tolerance (`QUERY_BUCKET_SPAN` buckets either side on each of the speed and time axes) to prevent boundary quantization misses.
+* @param speedAMps - Inferred speed of first flyover in m/s.
+* @param speedBMps - Inferred speed of second flyover in m/s.
+* @param deltaSec - Measured CPA offset in seconds.
+* @returns Set of candidate constellation hash keys.
+*/
+function expandConstellationQueryKeys(speedAMps, speedBMps, deltaSec) {
+	const [baseA, baseB, baseDt] = quantiseConstellation(speedAMps, speedBMps, deltaSec);
+	const keys = /* @__PURE__ */ new Set();
+	for (let da = -2; da <= 2; da += 1) for (let db = -2; db <= 2; db += 1) for (let ddt = -2; ddt <= 2; ddt += 1) keys.add(`v${String(baseA + da)}_v${String(baseB + db)}_dt${String(baseDt + ddt)}`);
+	return keys;
+}
+/**
+* Builds the Shazam-style Constellation Index from a collection of 4D linear flight segments.
+* Pairs any two non-jet segments passing within acoustic range (`MAX_PAIR_SLANT_METERS`) of the same cell, with closest-approach times between `MIN_PAIR_DELTA_SEC` and `MAX_PAIR_DELTA_SEC` apart, on the same date.
+* @param segments - Linear flight segments.
+* @param options - DEM elevation grid samples and speed of sound.
+* @returns Array of indexed constellation pair entries.
+*/
+function buildConstellationIndex(segments, options = {}) {
+	const { demGrid = [], soundSpeedMps = 343 } = options;
+	const nonJet = segments.filter((s) => s.category !== "jet");
+	const byCellAndDate = /* @__PURE__ */ new Map();
+	for (const seg of nonJet) {
+		const groupKey = `${seg.dateIso}|${seg.h3Cell}`;
+		const existing = byCellAndDate.get(groupKey);
+		if (existing !== void 0) existing.push(seg);
+		else byCellAndDate.set(groupKey, [seg]);
+	}
+	const entries = [];
+	for (const [, group] of byCellAndDate) {
+		if (group.length < 2) continue;
+		const firstSeg = group[0];
+		if (firstSeg === void 0) continue;
+		const center = decodeSpatialCellCenter(firstSeg.h3Cell);
+		const groundAlt = interpolateTerrainElevationMeters(center.lat, center.lon, demGrid);
+		const cellObserver = {
+			lat: center.lat,
+			lon: center.lon,
+			altMeters: groundAlt
+		};
+		const cpas = group.map((seg) => ({
+			seg,
+			cpa: computeSegmentCpa(cellObserver, seg, soundSpeedMps)
+		})).filter((item) => item.cpa.cpaSlantMeters <= MAX_PAIR_SLANT_METERS).sort((a, b) => a.cpa.cpaDelayedEpochSec - b.cpa.cpaDelayedEpochSec);
+		for (let i = 0; i < cpas.length; i += 1) for (let j = i + 1; j < cpas.length; j += 1) {
+			const a = cpas[i];
+			const b = cpas[j];
+			if (a === void 0 || b === void 0 || a.seg.flightId === b.seg.flightId) continue;
+			const deltaSec = b.cpa.cpaDelayedEpochSec - a.cpa.cpaDelayedEpochSec;
+			if (deltaSec < MIN_PAIR_DELTA_SEC || deltaSec > MAX_PAIR_DELTA_SEC) continue;
+			const hashKey = formatConstellationKey(a.seg.groundspeedMps, b.seg.groundspeedMps, deltaSec);
+			entries.push({
+				hashKey,
+				dateIso: a.seg.dateIso,
+				h3Cell: a.seg.h3Cell,
+				centerLat: center.lat,
+				centerLon: center.lon,
+				segmentIdA: a.seg.id,
+				segmentIdB: b.seg.id,
+				speedAMps: a.seg.groundspeedMps,
+				speedBMps: b.seg.groundspeedMps,
+				cpaDelayedEpochSecA: a.cpa.cpaDelayedEpochSec,
+				cpaDelayedEpochSecB: b.cpa.cpaDelayedEpochSec,
+				deltaSec
+			});
+		}
+	}
+	return entries;
+}
+/**
+* Checks whether a geographic coordinate and UTC epoch timestamp satisfy all active multi-axis user and side-channel constraints (Space, Date, Time of Day, and 50/60 Hz ENF power grid).
+* @param target - Candidate coordinate, date, and epoch timestamp.
+* @param constraints - Active multi-axis search constraints (any undefined field is treated as unconstrained `*`).
+* @returns `true` if the candidate satisfies all specified constraints.
+*/
+function matchesSearchConstraints(target, constraints) {
+	const { lat, lon, dateIso, epochSec } = target;
+	if (constraints.minLat !== void 0 && lat < constraints.minLat) return false;
+	if (constraints.maxLat !== void 0 && lat > constraints.maxLat) return false;
+	if (constraints.minLon !== void 0 && lon < constraints.minLon) return false;
+	if (constraints.maxLon !== void 0 && lon > constraints.maxLon) return false;
+	if (constraints.dateFromIso !== void 0 && dateIso < constraints.dateFromIso) return false;
+	if (constraints.dateToIso !== void 0 && dateIso > constraints.dateToIso) return false;
+	if (constraints.utcHourStart !== void 0 || constraints.utcHourEnd !== void 0) {
+		const utcHour = (epochSec % SECONDS_PER_DAY + SECONDS_PER_DAY) % SECONDS_PER_DAY / SECONDS_PER_HOUR;
+		const startH = constraints.utcHourStart ?? 0;
+		const endH = constraints.utcHourEnd ?? HOURS_PER_DAY$1;
+		if (startH <= endH) {
+			if (utcHour < startH || utcHour > endH) return false;
+		} else if (utcHour < startH && utcHour > endH) return false;
+	}
+	if (constraints.enfNominalHz !== void 0) {
+		const isAmericasLon = lon >= AMERICAS_MIN_LON_DEG && lon <= AMERICAS_MAX_LON_DEG;
+		if (constraints.enfNominalHz === "60" && !isAmericasLon) return false;
+		if (constraints.enfNominalHz === "50" && isAmericasLon) return false;
+	}
+	return true;
+}
+// src/bundled.ts
+/**
+* Reference ground truth observer location used for offline demonstration and regression testing.
+* Oxford, UK (51.7520° N, 1.2577° W, elevation 64 m).
+*/
+const BUNDLED_GROUND_TRUTH = {
+	lat: 51.752,
+	lon: -1.2577,
+	altMeters: 64
+};
+/**
+* Realistic piecewise-linear flight segments crossing the bundled reference region.
+*/
+const BUNDLED_SEGMENTS = [
+	{
+		id: "flyover_alpha",
+		flightId: "G-BOAC",
+		icao24: "4009a1",
+		typeCode: "C172",
+		category: "piston",
+		dateIso: "2026-09-08",
+		startEpochSec: 17889e5,
+		endEpochSec: 1788900180,
+		startGeo: localEnuToGeo(BUNDLED_GROUND_TRUTH, {
+			x: -6e3,
+			y: -1200,
+			z: 950
+		}),
+		endGeo: localEnuToGeo(BUNDLED_GROUND_TRUTH, {
+			x: 6e3,
+			y: -800,
+			z: 980
+		}),
+		groundspeedMps: 66.8,
+		h3Cell: encodeSpatialCell(BUNDLED_GROUND_TRUTH.lat, BUNDLED_GROUND_TRUTH.lon, 6)
+	},
+	{
+		id: "flyover_bravo",
+		flightId: "G-KEST",
+		icao24: "4011ef",
+		typeCode: "PA28",
+		category: "piston",
+		dateIso: "2026-09-08",
+		startEpochSec: 1788900920,
+		endEpochSec: 1788901100,
+		startGeo: localEnuToGeo(BUNDLED_GROUND_TRUTH, {
+			x: 1400,
+			y: -7e3,
+			z: 1200
+		}),
+		endGeo: localEnuToGeo(BUNDLED_GROUND_TRUTH, {
+			x: 800,
+			y: 7e3,
+			z: 1250
+		}),
+		groundspeedMps: 77.9,
+		h3Cell: encodeSpatialCell(BUNDLED_GROUND_TRUTH.lat, BUNDLED_GROUND_TRUTH.lon, 6)
+	},
+	{
+		id: "flyover_charlie",
+		flightId: "G-ROTN",
+		icao24: "4022bc",
+		typeCode: "DA42",
+		category: "turboprop",
+		dateIso: "2026-09-08",
+		startEpochSec: 1788901850,
+		endEpochSec: 1788902030,
+		startGeo: localEnuToGeo(BUNDLED_GROUND_TRUTH, {
+			x: -5e3,
+			y: 5e3,
+			z: 1400
+		}),
+		endGeo: localEnuToGeo(BUNDLED_GROUND_TRUTH, {
+			x: 5e3,
+			y: -5e3,
+			z: 1350
+		}),
+		groundspeedMps: 78.5,
+		h3Cell: encodeSpatialCell(BUNDLED_GROUND_TRUTH.lat, BUNDLED_GROUND_TRUTH.lon, 6)
+	}
+];
+/**
+* Regional DEM grid surrounding the reference location.
+*/
+const BUNDLED_DEM_GRID = [
+	{
+		lat: 51.7,
+		lon: -1.3,
+		altMeters: 60
+	},
+	{
+		lat: 51.7,
+		lon: -1.2,
+		altMeters: 62
+	},
+	{
+		lat: 51.8,
+		lon: -1.3,
+		altMeters: 75
+	},
+	{
+		lat: 51.8,
+		lon: -1.2,
+		altMeters: 68
+	},
+	{
+		lat: 51.752,
+		lon: -1.2577,
+		altMeters: 64
+	}
+];
+/**
+* Complete bundled DopplerDataset object available synchronously without network requests.
+*/
+const BUNDLED_DATASET = {
+	version: "1.0.0-bundled",
+	generatedAtIso: "2026-09-08T00:00:00Z",
+	segments: BUNDLED_SEGMENTS,
+	constellations: buildConstellationIndex(BUNDLED_SEGMENTS, { demGrid: BUNDLED_DEM_GRID }),
+	elevationGrid: BUNDLED_DEM_GRID
+};
+// src/dsp/decimate.ts
+/**
+* Width of a Blackman window's transition band as a multiple of the sampling rate divided by the tap count: `transition = 5.5 * rate / taps`.
+*/
+const BLACKMAN_TRANSITION_FACTOR = 5.5;
+/**
+* Share of the output sample rate kept as passband. The filter is flat to this fraction of the output rate and must be fully attenuated from the output rate less this fraction, the lowest frequency that folds back into the passband.
+*/
+const PASSBAND_FRACTION = .4;
+/**
+* Constant term of the Blackman window.
+*/
+const BLACKMAN_A0 = .42;
+/**
+* Amplitude of the fundamental cosine of the Blackman window.
+*/
+const BLACKMAN_A1 = .5;
+/**
+* Amplitude of the second-harmonic cosine of the Blackman window.
+*/
+const BLACKMAN_A2 = .08;
+/**
+* Smallest absolute kernel sum that is still normalised by; a sum below it means the kernel carries no usable gain, so it is left as designed rather than amplified by a near-zero divisor.
+*/
+const MIN_KERNEL_SUM = 1e-12;
+/**
+* Designs a normalized Blackman-windowed sinc low-pass FIR filter kernel.
+* @param cutoffHz - Low-pass cutoff frequency in Hz.
+* @param sampleRateHz - Input sample rate in Hz.
+* @param numTaps - Odd number of FIR filter taps.
+* @returns Normalized FIR filter coefficients.
+*/
+function designLowPassFirKernel(cutoffHz, sampleRateHz, numTaps = 97) {
+	const taps = numTaps % 2 === 1 ? numTaps : numTaps + 1;
+	const kernel = new Float64Array(taps);
+	const center = (taps - 1) / 2;
+	const normalizedCutoff = cutoffHz / sampleRateHz;
+	let sum = 0;
+	for (let i = 0; i < taps; i += 1) {
+		const n = i - center;
+		const sinc = n === 0 ? 2 * normalizedCutoff : Math.sin(2 * Math.PI * normalizedCutoff * n) / (Math.PI * n);
+		const windowPhase = 2 * Math.PI * i / (taps - 1);
+		const coeff = sinc * (BLACKMAN_A0 - BLACKMAN_A1 * Math.cos(windowPhase) + BLACKMAN_A2 * Math.cos(2 * windowPhase));
+		kernel[i] = coeff;
+		sum += coeff;
+	}
+	if (Math.abs(sum) > MIN_KERNEL_SUM) for (let i = 0; i < taps; i += 1) kernel[i] = (kernel[i] ?? 0) / sum;
+	return kernel;
+}
+/**
+* Decimates a high-sample-rate audio buffer (e.g. 48,000 Hz) down to a target sub-kilohertz/low-kilohertz rate (e.g. 2,000 Hz) after applying an anti-aliasing FIR low-pass filter.
+* @param input - Input mono audio samples.
+* @param inputRateHz - Original sample rate in Hz (e.g. 48000).
+* @param targetRateHz - Decimated sample rate in Hz (default `ANALYSIS_SAMPLE_RATE_HZ`).
+* @returns Decimated mono audio samples and actual output sample rate.
+*/
+function decimateAudioStream(input, inputRateHz, targetRateHz = ANALYSIS_SAMPLE_RATE_HZ) {
+	if (!(inputRateHz > 0) || !(targetRateHz > 0)) throw new Error(`Sample rates must be positive, got input ${String(inputRateHz)} Hz and target ${String(targetRateHz)} Hz`);
+	if (inputRateHz <= targetRateHz) return {
+		samples: new Float32Array(input),
+		sampleRateHz: inputRateHz
+	};
+	const ratio = Math.max(1, Math.round(inputRateHz / targetRateHz));
+	const actualRateHz = inputRateHz / ratio;
+	const cutoffHz = PASSBAND_FRACTION * actualRateHz;
+	const transitionHz = actualRateHz - 2 * cutoffHz;
+	const kernel = designLowPassFirKernel(cutoffHz, inputRateHz, Math.ceil(BLACKMAN_TRANSITION_FACTOR * inputRateHz / transitionHz));
+	const halfKernel = kernel.length - 1 >> 1;
+	const outLength = Math.floor(input.length / ratio);
+	const output = new Float32Array(outLength);
+	for (let outIdx = 0; outIdx < outLength; outIdx += 1) {
+		const centerInIdx = outIdx * ratio;
+		let acc = 0;
+		for (let k = 0; k < kernel.length; k += 1) {
+			const sampleIdx = centerInIdx + k - halfKernel;
+			if (sampleIdx >= 0 && sampleIdx < input.length) acc += (input[sampleIdx] ?? 0) * (kernel[k] ?? 0);
+		}
+		output[outIdx] = acc;
+	}
+	return {
+		samples: output,
+		sampleRateHz: actualRateHz
+	};
+}
+// src/physics/algebra.ts
+/** Default one-sigma frequency measurement uncertainty of an asymptote in Hz; a design default that callers with a known spectrogram resolution override. */
+const DEFAULT_FREQ_MEASUREMENT_STD_HZ = .15;
+/** Default one-sigma relative uncertainty of the measured inflection slope (dimensionless, 5 per cent). */
+const DEFAULT_SLOPE_REL_STD = .05;
+/** Floor on the inferred groundspeed in m/s used as the divisor of the relative speed uncertainty, so a near-zero speed cannot divide by zero. */
+const MIN_INFERRED_SPEED_MPS = .001;
+/**
+* Separates aircraft groundspeed `v`, unshifted engine fundamental `f0`, and 3D Closest Point of Approach (CPA) slant distance `d_slant` in O(1) closed-form algebra directly from a Doppler curve's asymptotes and inflection slope.
+*
+* Because `f+ / f- = (1 + v/c) / (1 - v/c)`, the unknown engine base pitch `f0` cancels out identically:
+* - `v = c * (f+ - f-) / (f+ + f-)`
+* - `f0 = 2 * f+ * f- / (f+ + f-)` (the harmonic mean)
+* - `d_slant = - (f0 * v^2) / (c * df/dt|_CPA)`
+* @param measurement - Measured approaching/receding frequencies and inflection slope.
+* @returns Closed-form kinematic parameters and propagated standard deviations.
+*/
+function extractAsymptoticKinematics(measurement) {
+	const { asymptoticHighHz, asymptoticLowHz, inflectionSlopeHzPerSec } = measurement;
+	const soundSpeedMps = measurement.soundSpeedMps ?? 343;
+	const freqStd = measurement.freqMeasurementStdHz ?? DEFAULT_FREQ_MEASUREMENT_STD_HZ;
+	const slopeRelStd = measurement.slopeMeasurementRelStd ?? DEFAULT_SLOPE_REL_STD;
+	if (asymptoticHighHz <= asymptoticLowHz || asymptoticLowHz <= 0) throw new Error(`Approaching frequency (${String(asymptoticHighHz)} Hz) must exceed positive receding frequency (${String(asymptoticLowHz)} Hz)`);
+	if (inflectionSlopeHzPerSec >= 0) throw new Error(`Doppler inflection slope at CPA must be negative, got ${String(inflectionSlopeHzPerSec)} Hz/s`);
+	const sumFreq = asymptoticHighHz + asymptoticLowHz;
+	const inferredSpeedMps = soundSpeedMps * ((asymptoticHighHz - asymptoticLowHz) / sumFreq);
+	const baseFreqHz = 2 * asymptoticHighHz * asymptoticLowHz / sumFreq;
+	const inferredSlantMeters = -(baseFreqHz * inferredSpeedMps * inferredSpeedMps) / (soundSpeedMps * inflectionSlopeHzPerSec);
+	const dvDfHigh = 2 * soundSpeedMps * asymptoticLowHz / (sumFreq * sumFreq);
+	const dvDfLow = -(2 * soundSpeedMps * asymptoticHighHz) / (sumFreq * sumFreq);
+	const speedStdMps = Math.hypot(dvDfHigh * freqStd, dvDfLow * freqStd);
+	const relSpeedStd = speedStdMps / Math.max(MIN_INFERRED_SPEED_MPS, inferredSpeedMps);
+	return {
+		asymptoticHighHz,
+		asymptoticLowHz,
+		baseFreqHz,
+		inflectionSlopeHzPerSec,
+		inferredSpeedMps,
+		inferredSlantMeters,
+		speedStdMps,
+		slantStdMeters: inferredSlantMeters * Math.hypot(2 * relSpeedStd, slopeRelStd)
+	};
+}
+// src/dsp/ridge-tracker.ts
+/**
+* Default minimum per-frame peak signal-to-noise ratio in dB for a frame to join a ridge.
+*/
+const DEFAULT_MIN_SNR_DB = 6;
+/**
+* Default minimum time in seconds between the first and last point of a ridge for it to count as a flyover.
+*/
+const DEFAULT_MIN_DURATION_SEC = 6;
+/**
+* Default minimum drop in Hz from the approaching to the receding asymptote for a ridge to count as a Doppler S-curve rather than a steady tone.
+*/
+const DEFAULT_MIN_FREQ_DROP_HZ = 3.5;
+/**
+* Extra signal-to-noise ratio in dB demanded of a frame flagged as noise-polluted, so that only strong peaks survive elevated noise.
+*/
+const NOISE_POLLUTED_SNR_PENALTY_DB = 4;
+/**
+* Fewest candidate points, and fewest points in a ridge, from which a Doppler S-curve can be fitted.
+*/
+const MIN_RIDGE_POINTS = 5;
+/**
+* Fewest consecutive frequency-continuous points that form a ridge worth keeping.
+*/
+const MIN_CLUSTER_POINTS = 8;
+/**
+* Longest gap in seconds between consecutive points of one ridge.
+*/
+const MAX_TRACK_GAP_SEC = 1.5;
+/**
+* Smallest frequency jump in Hz allowed between consecutive ridge points however short the gap between them.
+*/
+const MIN_TRACK_FREQ_JUMP_HZ = 10;
+/**
+* Greatest frequency slew rate in Hz per second allowed between consecutive ridge points.
+*/
+const MAX_TRACK_SLEW_HZ_PER_SEC = 15;
+/**
+* Fraction of a ridge's points at each end whose median frequency estimates the approaching and receding asymptotes.
+*/
+const EDGE_FRACTION = .22;
+/**
+* Fewest points at each end of a ridge that are used to estimate an asymptote.
+*/
+const MIN_EDGE_POINTS = 2;
+/**
+* Number of ridge points that earn one point of half-span on each side of the closest point of approach when measuring the inflection slope.
+*/
+const RIDGE_POINTS_PER_SLOPE_SPAN_POINT = 6;
+/**
+* Greatest half-span in points on each side of the closest point of approach when measuring the inflection slope.
+*/
+const MAX_SLOPE_SPAN_POINTS = 3;
+/**
+* Shortest time in seconds across which the inflection slope is measured, so that a ridge sampled very densely does not divide by a near-zero interval.
+*/
+const MIN_SLOPE_WINDOW_SEC = .25;
+/**
+* Shortest time-scale in seconds of the closest-approach geometry that is assumed when extrapolating the asymptotes.
+*/
+const MIN_TAU_SEC = 1.5;
+/**
+* Smallest value of `cosThetaMax`, the cosine of the angle between the aircraft's course and its line of sight at the ridge ends, that the asymptotic extrapolation divides by; it bounds the correction a short ridge can apply.
+*/
+const MIN_COS_THETA_MAX = .5;
+/**
+* Lowest frequency in Hz that the extrapolated receding asymptote may take.
+*/
+const MIN_ASYMPTOTIC_LOW_HZ = 10;
+/**
+* Extracts Doppler S-curve observations from a spectrogram, down-weighting noise-polluted frames and computing closed-form kinematics for each detected flyover.
+* @param spectrogram - Computed spectrogram with noise-pollution flags.
+* @param options - Tracker thresholds and episode context.
+* @returns Array of detected aircraft Doppler observations.
+*/
+function extractDopplerObservations(spectrogram, options) {
+	const minSnrDb = options.minSnrDb ?? DEFAULT_MIN_SNR_DB;
+	const minDurationSec = options.minDurationSec ?? DEFAULT_MIN_DURATION_SEC;
+	const minFreqDropHz = options.minFreqDropHz ?? DEFAULT_MIN_FREQ_DROP_HZ;
+	const soundSpeedMps = options.soundSpeedMps ?? 343;
+	const candidatePoints = [];
+	for (const frame of spectrogram.frames) {
+		const effectiveThreshold = frame.noisePolluted ? minSnrDb + NOISE_POLLUTED_SNR_PENALTY_DB : minSnrDb;
+		if (frame.peakSnrDb >= effectiveThreshold) candidatePoints.push({
+			timeSec: frame.timeSec,
+			freqHz: frame.peakFreqHz,
+			snrDb: frame.peakSnrDb
+		});
+	}
+	if (candidatePoints.length < MIN_RIDGE_POINTS) return [];
+	const clusters = [];
+	let currentCluster = [];
+	for (const pt of candidatePoints) {
+		if (currentCluster.length === 0) {
+			currentCluster.push(pt);
+			continue;
+		}
+		const prev = currentCluster[currentCluster.length - 1];
+		if (prev === void 0) continue;
+		const dt = pt.timeSec - prev.timeSec;
+		const df = Math.abs(pt.freqHz - prev.freqHz);
+		if (dt <= MAX_TRACK_GAP_SEC && df <= Math.max(MIN_TRACK_FREQ_JUMP_HZ, MAX_TRACK_SLEW_HZ_PER_SEC * dt)) currentCluster.push(pt);
+		else {
+			if (currentCluster.length >= MIN_CLUSTER_POINTS) clusters.push(currentCluster);
+			currentCluster = [pt];
+		}
+	}
+	if (currentCluster.length >= MIN_CLUSTER_POINTS) clusters.push(currentCluster);
+	const observations = [];
+	for (let idx = 0; idx < clusters.length; idx += 1) {
+		const cluster = clusters[idx];
+		if (cluster === void 0 || cluster.length < MIN_RIDGE_POINTS) continue;
+		const firstPt = cluster[0];
+		const lastPt = cluster[cluster.length - 1];
+		if (firstPt === void 0 || lastPt === void 0) continue;
+		const durationSec = lastPt.timeSec - firstPt.timeSec;
+		if (durationSec < minDurationSec) continue;
+		const edgeCount = Math.max(MIN_EDGE_POINTS, Math.floor(cluster.length * EDGE_FRACTION));
+		const headFreqs = cluster.slice(0, edgeCount).map((p) => p.freqHz).sort((a, b) => a - b);
+		const tailFreqs = cluster.slice(cluster.length - edgeCount).map((p) => p.freqHz).sort((a, b) => a - b);
+		const fHigh = headFreqs[headFreqs.length >> 1] ?? firstPt.freqHz;
+		const fLow = tailFreqs[tailFreqs.length >> 1] ?? lastPt.freqHz;
+		if (fHigh - fLow < minFreqDropHz) continue;
+		const targetBaseFreq = 2 * fHigh * fLow / (fHigh + fLow);
+		let cpaIdx = cluster.length >> 1;
+		let minFreqDiff = Infinity;
+		for (let i = 1; i < cluster.length - 1; i += 1) {
+			const pt = cluster[i];
+			if (pt !== void 0) {
+				const diff = Math.abs(pt.freqHz - targetBaseFreq);
+				if (diff < minFreqDiff) {
+					minFreqDiff = diff;
+					cpaIdx = i;
+				}
+			}
+		}
+		const cpaPoint = cluster[cpaIdx] ?? firstPt;
+		const span = Math.max(1, Math.min(MAX_SLOPE_SPAN_POINTS, Math.floor(cluster.length / RIDGE_POINTS_PER_SLOPE_SPAN_POINT)));
+		const leftPt = cluster[Math.max(0, cpaIdx - span)] ?? firstPt;
+		const rightPt = cluster[Math.min(cluster.length - 1, cpaIdx + span)] ?? lastPt;
+		const dtSlope = Math.max(MIN_SLOPE_WINDOW_SEC, rightPt.timeSec - leftPt.timeSec);
+		const rawSlope = (rightPt.freqHz - leftPt.freqHz) / dtSlope;
+		const inflectionSlopeHzPerSec = rawSlope < -.02 ? rawSlope : -(fHigh - fLow) / durationSec;
+		const halfDur = Math.max(1, durationSec / 2);
+		const tauEst = Math.max(MIN_TAU_SEC, -(targetBaseFreq * ((fHigh - fLow) / (fHigh + fLow))) / inflectionSlopeHzPerSec);
+		const cosThetaMax = halfDur / Math.hypot(halfDur, tauEst);
+		const halfSpread = (fHigh - fLow) / 2 / Math.max(MIN_COS_THETA_MAX, cosThetaMax);
+		const midFreq = (fHigh + fLow) / 2;
+		const kinematics = extractAsymptoticKinematics({
+			asymptoticHighHz: midFreq + halfSpread,
+			asymptoticLowHz: Math.max(MIN_ASYMPTOTIC_LOW_HZ, midFreq - halfSpread),
+			inflectionSlopeHzPerSec,
+			soundSpeedMps
+		});
+		const snrValues = cluster.map((p) => p.snrDb).sort((a, b) => a - b);
+		const medianSnrDb = snrValues[snrValues.length >> 1] ?? minSnrDb;
+		observations.push({
+			id: `${options.episodeId}_obs${String(idx)}`,
+			episodeId: options.episodeId,
+			cpaTimeSec: cpaPoint.timeSec,
+			kinematics,
+			snrDb: medianSnrDb,
+			harmonicCount: 1,
+			ridgePoints: cluster
+		});
+	}
+	return observations;
+}
+// src/dsp/spectrogram.ts
+/**
+* Default margin in dB by which a frame's median noise floor may exceed the reference floor before the frame is flagged as noise-polluted.
+*/
+const NOISE_POLLUTION_MARGIN_DB = 12;
+/**
+* Default reference noise floor in dB against which a single isolated frame is judged for noise pollution when the caller supplies no baseline.
+*/
+const DEFAULT_BASELINE_NOISE_DB = -80;
+/**
+* Overall median noise floor in dB reported for a spectrogram that holds no frames.
+*/
+const EMPTY_SPECTROGRAM_NOISE_DB = -90;
+/**
+* Smallest absolute second difference in dB across a peak for which parabolic interpolation is attempted; a flatter peak keeps its integer bin.
+*/
+const MIN_PARABOLA_CURVATURE_DB = 1e-9;
+/**
+* Largest sub-bin offset in bins that parabolic interpolation may apply to a peak: a true maximum lies within half a bin of the sampled one.
+*/
+const MAX_SUB_BIN_OFFSET = .5;
+/**
+* Computes the median value of a numeric slice without mutating the source buffer.
+*/
+function medianOfSlice(values, start, end) {
+	const slice = [];
+	for (let i = start; i <= end; i += 1) {
+		const val = values[i];
+		if (val !== void 0) slice.push(val);
+	}
+	if (slice.length === 0) return MISSING_BIN_POWER_DB;
+	slice.sort((a, b) => a - b);
+	return slice[slice.length >> 1] ?? -120;
+}
+/**
+* Computes an isolated single STFT spectrogram frame over a single time window.
+* @param windowSlice - Time-domain audio slice (length must match fftSize).
+* @param options - Single frame computation options.
+* @returns Computed STFT frame, peak tracking values, and frequency bin parameters.
+*/
+function computeSingleSpectrogramFrame(windowSlice, options) {
+	const sampleRateHz = options.sampleRateHz;
+	const fftSize = options.fftSize ?? 2048;
+	const minFreqHz = options.minFreqHz ?? 65;
+	const maxFreqHz = options.maxFreqHz ?? 500;
+	const timeSec = options.timeSec ?? 0;
+	const pollutionMarginDb = options.noisePollutionThresholdDb ?? NOISE_POLLUTION_MARGIN_DB;
+	const baselineNoiseDb = options.baselineNoiseDb ?? DEFAULT_BASELINE_NOISE_DB;
+	const binStepHz = sampleRateHz / fftSize;
+	const minBin = Math.max(1, Math.floor(minFreqHz / binStepHz));
+	const maxBin = Math.min((fftSize >> 1) - 1, Math.ceil(maxFreqHz / binStepHz));
+	const fullSpectrumDb = computeHannPowerSpectrumDb(windowSlice, fftSize);
+	const medianNoiseFloorDb = medianOfSlice(fullSpectrumDb, minBin, maxBin);
+	let bestBin = minBin;
+	let bestPowerDb = -Infinity;
+	for (let b = minBin; b <= maxBin; b += 1) {
+		const p = fullSpectrumDb[b] ?? -Infinity;
+		if (p > bestPowerDb) {
+			bestPowerDb = p;
+			bestBin = b;
+		}
+	}
+	const leftDb = fullSpectrumDb[bestBin - 1] ?? bestPowerDb;
+	const rightDb = fullSpectrumDb[bestBin + 1] ?? bestPowerDb;
+	const denom = leftDb - 2 * bestPowerDb + rightDb;
+	const deltaBin = Math.abs(denom) > MIN_PARABOLA_CURVATURE_DB ? Math.max(-.5, Math.min(MAX_SUB_BIN_OFFSET, (leftDb - rightDb) / 2 / denom)) : 0;
+	const peakFreqHz = (bestBin + deltaBin) * binStepHz;
+	const peakSnrDb = bestPowerDb - medianNoiseFloorDb;
+	return {
+		timeSec,
+		powerDb: fullSpectrumDb.slice(minBin, maxBin + 1),
+		medianNoiseFloorDb,
+		peakFreqHz,
+		peakPowerDb: bestPowerDb,
+		peakSnrDb,
+		noisePolluted: medianNoiseFloorDb > baselineNoiseDb + pollutionMarginDb,
+		minBin,
+		maxBin,
+		binStepHz
+	};
+}
+/**
+* Computes a high-resolution spectrogram focused on the aircraft acoustic Doppler band (65 to 500 Hz by default), with parabolic sub-bin peak interpolation and continuous noise-pollution gating.
+* @param samples - Decimated mono audio samples (typically at 2,000 Hz).
+* @param options - Spectrogram configuration parameters.
+* @returns Spectrogram frames, sub-bin peak tracks, and quiet intervals where silence filtering is valid.
+*/
+function computeDopplerSpectrogram(samples, options) {
+	const sampleRateHz = options.sampleRateHz;
+	const startTimeSec = options.startTimeSec ?? 0;
+	const fftSize = options.fftSize ?? 2048;
+	const hopSamples = options.hopSamples ?? 500;
+	const minFreqHz = options.minFreqHz ?? 65;
+	const maxFreqHz = options.maxFreqHz ?? 500;
+	const pollutionMarginDb = options.noisePollutionThresholdDb ?? NOISE_POLLUTION_MARGIN_DB;
+	if (!(sampleRateHz > 0)) throw new Error(`Sample rate must be positive, got ${String(sampleRateHz)} Hz`);
+	if (!Number.isInteger(hopSamples) || hopSamples < 1) throw new Error(`hopSamples must be a positive integer, got ${String(hopSamples)}`);
+	const binStepHz = sampleRateHz / fftSize;
+	const minBin = Math.max(1, Math.floor(minFreqHz / binStepHz));
+	const maxBin = Math.min((fftSize >> 1) - 1, Math.ceil(maxFreqHz / binStepHz));
+	const rawFrames = [];
+	for (let offset = 0; offset + fftSize <= samples.length; offset += hopSamples) {
+		const frame = computeSingleSpectrogramFrame(samples.subarray(offset, offset + fftSize), {
+			sampleRateHz,
+			fftSize,
+			minFreqHz,
+			maxFreqHz,
+			timeSec: startTimeSec + (offset + fftSize / 2) / sampleRateHz
+		});
+		rawFrames.push(frame);
+	}
+	const floorList = rawFrames.map((f) => f.medianNoiseFloorDb).sort((a, b) => a - b);
+	const overallMedianNoiseDb = floorList.length > 0 ? floorList[floorList.length >> 1] ?? EMPTY_SPECTROGRAM_NOISE_DB : EMPTY_SPECTROGRAM_NOISE_DB;
+	const frameDurationSec = hopSamples / sampleRateHz;
+	const frames = rawFrames.map((f) => ({
+		timeSec: f.timeSec,
+		powerDb: f.powerDb,
+		medianNoiseFloorDb: f.medianNoiseFloorDb,
+		peakFreqHz: f.peakFreqHz,
+		peakPowerDb: f.peakPowerDb,
+		peakSnrDb: f.peakSnrDb,
+		noisePolluted: f.medianNoiseFloorDb > overallMedianNoiseDb + pollutionMarginDb
+	}));
+	const quietIntervals = [];
+	let currentStart = null;
+	let noiseAccum = [];
+	for (const frame of frames) if (!frame.noisePolluted) {
+		currentStart ??= frame.timeSec - frameDurationSec / 2;
+		noiseAccum.push(frame.medianNoiseFloorDb);
+	} else if (currentStart !== null) {
+		const sortedNoise = [...noiseAccum].sort((a, b) => a - b);
+		quietIntervals.push({
+			startSec: currentStart,
+			endSec: frame.timeSec - frameDurationSec / 2,
+			medianNoiseFloorDb: sortedNoise[sortedNoise.length >> 1] ?? overallMedianNoiseDb
+		});
+		currentStart = null;
+		noiseAccum = [];
+	}
+	if (currentStart !== null && frames.length > 0) {
+		const lastFrame = frames[frames.length - 1];
+		const sortedNoise = [...noiseAccum].sort((a, b) => a - b);
+		if (lastFrame !== void 0) quietIntervals.push({
+			startSec: currentStart,
+			endSec: lastFrame.timeSec + frameDurationSec / 2,
+			medianNoiseFloorDb: sortedNoise[sortedNoise.length >> 1] ?? overallMedianNoiseDb
+		});
+	}
+	return {
+		sampleRateHz,
+		fftSize,
+		minFreqHz,
+		maxFreqHz,
+		minBin,
+		maxBin,
+		binStepHz,
+		frames,
+		quietIntervals,
+		overallMedianNoiseDb
+	};
+}
+// src/define.ts
+/**
+* Reports whether a schema carries a callable `is` property, which narrows it to its guarded type without a type assertion.
+* @param candidate - The schema to inspect.
+* @returns True when `candidate` has an own `is` function.
+*/
+function isGuarded(candidate) {
+	return Object.hasOwn(candidate, "is") && "is" in candidate && typeof candidate.is === "function";
+}
+/**
+* Attaches a type guard to a Zod schema (the schema-attached guard pattern: validation, inference and narrowing share one definition, so the three cannot drift). The guard is defined on the schema object itself, because a Zod 4 schema keeps its methods on its prototype and its parse state on `_zod`: a spread copy loses the methods, so it could no longer be parsed or nested in another schema.
+* @param schema - The schema to augment.
+* @returns The same schema object, now also carrying `is`.
+* @throws When the schema is non-extensible, so the guard cannot be attached, or when the property was not installed.
+*/
+function define(schema) {
+	const augmented = Object.defineProperty(schema, "is", {
+		enumerable: true,
+		value: (value) => schema.safeParse(value).success
+	});
+	if (!isGuarded(augmented)) throw new TypeError("define: the type guard was not installed on the schema");
+	return augmented;
+}
+// src/schemas.ts
+/**
+* Northern limit of geodetic latitude in degrees: the North Pole.
+*/
+const MAX_LATITUDE_DEGREES = 90;
+/**
+* Southern limit of geodetic latitude in degrees: the South Pole, symmetric with the northern limit.
+*/
+const MIN_LATITUDE_DEGREES = -90;
+/**
+* Eastern limit of geodetic longitude in degrees: the antimeridian, half a full turn of 360 degrees from the prime meridian.
+*/
+const MAX_LONGITUDE_DEGREES = 180;
+/**
+* Western limit of geodetic longitude in degrees, symmetric with the eastern limit.
+*/
+const MIN_LONGITUDE_DEGREES = -180;
+/**
+* Lowest accepted altitude above the WGS84 ellipsoid in metres: a design margin below the deepest exposed land depression (the Dead Sea shore, about 430 m below sea level) so that real terrain-level observers are never rejected.
+*/
+const MIN_ALTITUDE_METERS = -500;
+/**
+* Highest accepted altitude above the WGS84 ellipsoid in metres: a design ceiling of 60 km, well above any aircraft service ceiling and so a safe bound that still rejects corrupt altitude values.
+*/
+const MAX_ALTITUDE_METERS = 6e4;
+/**
+* Hours in a UTC day: the upper bound of a time-of-day hour value, where 24 denotes the end of the day.
+*/
+const HOURS_PER_DAY = 24;
+/**
+* Geodetic 3D coordinate on or above the WGS84 reference ellipsoid.
+*/
+const GeoPoint3DSchema = define(z.object({
+	lat: z.number().min(MIN_LATITUDE_DEGREES).max(MAX_LATITUDE_DEGREES),
+	lon: z.number().min(MIN_LONGITUDE_DEGREES).max(MAX_LONGITUDE_DEGREES),
+	altMeters: z.number().min(MIN_ALTITUDE_METERS).max(MAX_ALTITUDE_METERS)
+}));
+define(z.object({
+	x: z.number(),
+	y: z.number(),
+	z: z.number()
+}));
+/**
+* Aircraft propulsion category used to filter acoustic candidates.
+*/
+const AircraftCategorySchema = define(z.enum([
+	"piston",
+	"turboprop",
+	"helicopter",
+	"jet",
+	"unknown"
+]));
+define(z.object({
+	epochSec: z.number(),
+	lat: z.number().min(MIN_LATITUDE_DEGREES).max(MAX_LATITUDE_DEGREES),
+	lon: z.number().min(MIN_LONGITUDE_DEGREES).max(MAX_LONGITUDE_DEGREES),
+	altMeters: z.number()
+}));
+/**
+* Piecewise-linear 4D aircraft trajectory segment produced by Ramer-Douglas-Peucker compression.
+*/
+const LinearFlightSegmentSchema = define(z.object({
+	id: z.string().min(1),
+	flightId: z.string().min(1),
+	icao24: z.string().min(1),
+	typeCode: z.string(),
+	category: AircraftCategorySchema,
+	dateIso: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+	startEpochSec: z.number(),
+	endEpochSec: z.number(),
+	startGeo: GeoPoint3DSchema,
+	endGeo: GeoPoint3DSchema,
+	groundspeedMps: z.number().nonnegative(),
+	h3Cell: z.string().min(1)
+}));
+/**
+* Single time-frequency point along an extracted spectrogram Doppler ridge.
+*/
+const DopplerRidgePointSchema = define(z.object({
+	timeSec: z.number(),
+	freqHz: z.number().positive(),
+	snrDb: z.number()
+}));
+/**
+* Closed-form kinematic parameters extracted algebraically from a single Doppler S-curve.
+*/
+const AsymptoticKinematicsSchema = define(z.object({
+	asymptoticHighHz: z.number().positive(),
+	asymptoticLowHz: z.number().positive(),
+	baseFreqHz: z.number().positive(),
+	inflectionSlopeHzPerSec: z.number().negative(),
+	inferredSpeedMps: z.number().positive(),
+	inferredSlantMeters: z.number().positive(),
+	speedStdMps: z.number().nonnegative(),
+	slantStdMeters: z.number().nonnegative()
+}));
+/**
+* Complete acoustic observation of an aircraft flyover extracted from an audio stream or file.
+*/
+const DopplerObservationSchema = define(z.object({
+	id: z.string().min(1),
+	episodeId: z.string().min(1),
+	cpaTimeSec: z.number(),
+	kinematics: AsymptoticKinematicsSchema,
+	snrDb: z.number(),
+	harmonicCount: z.number().int().min(1),
+	ridgePoints: z.array(DopplerRidgePointSchema).readonly()
+}));
+/**
+* Quantized Shazam-style constellation hash entry linking two flyovers at a shared H3 cell.
+*/
+const ConstellationEntrySchema = define(z.object({
+	hashKey: z.string().min(1),
+	dateIso: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+	h3Cell: z.string().min(1),
+	centerLat: z.number().min(MIN_LATITUDE_DEGREES).max(MAX_LATITUDE_DEGREES),
+	centerLon: z.number().min(MIN_LONGITUDE_DEGREES).max(MAX_LONGITUDE_DEGREES),
+	segmentIdA: z.string().min(1),
+	segmentIdB: z.string().min(1),
+	speedAMps: z.number().positive(),
+	speedBMps: z.number().positive(),
+	cpaDelayedEpochSecA: z.number(),
+	cpaDelayedEpochSecB: z.number(),
+	deltaSec: z.number().positive()
+}));
+/**
+* Time interval within a listening episode where ambient noise was below the silence-gating threshold.
+*/
+const QuietIntervalSchema = define(z.object({
+	startSec: z.number(),
+	endSec: z.number(),
+	medianNoiseFloorDb: z.number()
+}));
+/**
+* Continuous listening window within a multi-episode pause/resume geolocation session.
+*/
+const ListeningEpisodeSchema = define(z.object({
+	id: z.string().min(1),
+	startedAtSec: z.number(),
+	endedAtSec: z.number(),
+	status: z.enum([
+		"active",
+		"paused",
+		"completed"
+	]),
+	currentNoiseFloorDb: z.number(),
+	noisePolluted: z.boolean(),
+	quietIntervals: z.array(QuietIntervalSchema).readonly()
+}));
+/**
+* Passive Electrical Network Frequency (ENF) side-channel signature (50 Hz vs 60 Hz power grid).
+*/
+const EnfSignatureSchema = define(z.object({
+	detected: z.boolean(),
+	nominalHz: z.enum([
+		"50",
+		"60",
+		"unknown"
+	]),
+	measuredFreqHz: z.number().nonnegative(),
+	snrDb: z.number(),
+	regionHint: z.string()
+}));
+/**
+* Optional user or side-channel constraints over Space, Date, Time of Day, and Power Grid.
+*/
+const SearchConstraintsSchema = define(z.object({
+	minLat: z.number().min(MIN_LATITUDE_DEGREES).max(MAX_LATITUDE_DEGREES).optional(),
+	maxLat: z.number().min(MIN_LATITUDE_DEGREES).max(MAX_LATITUDE_DEGREES).optional(),
+	minLon: z.number().min(MIN_LONGITUDE_DEGREES).max(MAX_LONGITUDE_DEGREES).optional(),
+	maxLon: z.number().min(MIN_LONGITUDE_DEGREES).max(MAX_LONGITUDE_DEGREES).optional(),
+	dateFromIso: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+	dateToIso: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+	utcHourStart: z.number().min(0).max(HOURS_PER_DAY).optional(),
+	utcHourEnd: z.number().min(0).max(HOURS_PER_DAY).optional(),
+	enfNominalHz: z.enum(["50", "60"]).optional()
+}));
+/**
+* A flyover observation attributed to a flight segment under a location hypothesis. Matches are keyed by observation id, never by position, because an observation that fits no segment is absent from a hypothesis and would shift every later index.
+*/
+const HypothesisMatchSchema = define(z.object({
+	observationId: z.string().min(1),
+	segmentId: z.string().min(1)
+}));
+/**
+* Candidate observer location hypothesis with cumulative Bayesian log-posterior and 95% confidence ellipse.
+*/
+const LocationHypothesisSchema = define(z.object({
+	id: z.string().min(1),
+	h3Cell: z.string().min(1),
+	dateIso: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+	lat: z.number().min(MIN_LATITUDE_DEGREES).max(MAX_LATITUDE_DEGREES),
+	lon: z.number().min(MIN_LONGITUDE_DEGREES).max(MAX_LONGITUDE_DEGREES),
+	altMeters: z.number(),
+	estimatedStartEpochSec: z.number(),
+	logPosterior: z.number(),
+	probability: z.number().min(0).max(1),
+	rmsFreqResidualHz: z.number().nonnegative(),
+	fisherInfo: z.tuple([
+		z.number(),
+		z.number(),
+		z.number(),
+		z.number()
+	]).readonly(),
+	ellipseSemiMajorMeters: z.number().positive(),
+	ellipseSemiMinorMeters: z.number().positive(),
+	ellipseBearingDeg: z.number(),
+	matches: z.array(HypothesisMatchSchema).readonly()
+}));
+/**
+* Persistent, serializable geolocation session supporting continuous and episodic pause/resume refinement.
+*/
+const LocationSessionSchema = define(z.object({
+	id: z.string().min(1),
+	createdAtEpochSec: z.number(),
+	updatedAtEpochSec: z.number(),
+	ambientTempCelsius: z.number(),
+	constraints: SearchConstraintsSchema,
+	enfSignature: EnfSignatureSchema,
+	episodes: z.array(ListeningEpisodeSchema).readonly(),
+	observations: z.array(DopplerObservationSchema).readonly(),
+	hypotheses: z.array(LocationHypothesisSchema).readonly()
+}));
+/**
+* Portable dataset bundle containing 4D-RDP trajectory segments, constellation hash index, and elevation tiles.
+*/
+const DopplerDatasetSchema = define(z.object({
+	version: z.string().min(1),
+	generatedAtIso: z.string().min(1),
+	segments: z.array(LinearFlightSegmentSchema).readonly(),
+	constellations: z.array(ConstellationEntrySchema).readonly(),
+	elevationGrid: z.array(GeoPoint3DSchema).readonly()
+}));
+// src/physics/rdp.ts
+/** Shortest time span in seconds over which a range's end points define a constant-speed segment; a shorter span is treated as a single instant, so the interpolation fraction is zero instead of a division by a near-zero span. */
+const MIN_INTERPOLATION_SPAN_SEC = 1e-6;
+/** Shortest simplified segment in seconds; pings arrive at 1 Hz, so a shorter span between kept pings only arises from duplicate or near-duplicate timestamps, whose groundspeed would divide by a near-zero span and is dropped. */
+const MIN_SEGMENT_DURATION_SEC = .1;
+/**
+* Selects the indices of key vertices using 4D Ramer-Douglas-Peucker simplification over `(X, Y, Z, t)`: the end points are kept, and a range is split at its worst-fitting ping while that ping lies further than `toleranceMeters` from the straight, constant-speed segment joining the range's ends.
+* The ranges are processed from an explicit stack rather than by recursion, because a trace of tens of thousands of pings can split unevenly enough to exhaust the call stack, and each ping's ECEF position is computed once.
+* @param pings - Chronologically ordered pings.
+* @param toleranceMeters - Largest allowed 3D deviation of a dropped ping.
+* @returns Ascending indices of the kept pings, always including the first and last.
+*/
+function rdpIndices(pings, toleranceMeters) {
+	const count = pings.length;
+	const ecef = pings.map((ping) => geoToEcef(ping));
+	const keep = new Uint8Array(count);
+	keep[0] = 1;
+	keep[count - 1] = 1;
+	const ranges = [[0, count - 1]];
+	for (let range = ranges.pop(); range !== void 0; range = ranges.pop()) {
+		const [startIdx, endIdx] = range;
+		const first = pings[startIdx];
+		const last = pings[endIdx];
+		const firstEcef = ecef[startIdx];
+		const lastEcef = ecef[endIdx];
+		if (endIdx <= startIdx + 1 || first === void 0 || last === void 0 || firstEcef === void 0 || lastEcef === void 0) continue;
+		const totalDt = last.epochSec - first.epochSec;
+		let maxError = -1;
+		let splitIdx = startIdx;
+		for (let i = startIdx + 1; i < endIdx; i += 1) {
+			const ping = pings[i];
+			const position = ecef[i];
+			if (ping === void 0 || position === void 0) continue;
+			const fraction = totalDt > MIN_INTERPOLATION_SPAN_SEC ? Math.max(0, Math.min(1, (ping.epochSec - first.epochSec) / totalDt)) : 0;
+			const error = Math.hypot(position.x - (firstEcef.x + (lastEcef.x - firstEcef.x) * fraction), position.y - (firstEcef.y + (lastEcef.y - firstEcef.y) * fraction), position.z - (firstEcef.z + (lastEcef.z - firstEcef.z) * fraction));
+			if (error > maxError) {
+				maxError = error;
+				splitIdx = i;
+			}
+		}
+		if (maxError > toleranceMeters && splitIdx > startIdx && splitIdx < endIdx) {
+			keep[splitIdx] = 1;
+			ranges.push([startIdx, splitIdx], [splitIdx, endIdx]);
+		}
+	}
+	return Array.from(keep.entries(), ([index, kept]) => kept === 1 ? index : -1).filter((index) => index !== -1);
+}
+/**
+* Compresses a sequence of raw 1 Hz ADS-B pings into piecewise-linear 4D segments (`LinearFlightSegment`) with bounded spatiotemporal error.
+* @param pings - Chronologically ordered raw ADS-B pings.
+* @param meta - Flight and aircraft metadata.
+* @param toleranceMeters - Maximum allowed 3D interpolation error in meters (default 5 m).
+* @returns Array of compressed linear trajectory segments.
+*/
+function simplifyTrajectory4D(pings, meta, toleranceMeters = 5) {
+	if (pings.length < 2) return [];
+	const sorted = [...pings].sort((a, b) => a.epochSec - b.epochSec);
+	const keyIndices = rdpIndices(sorted, toleranceMeters);
+	const segments = [];
+	for (let k = 0; k < keyIndices.length - 1; k += 1) {
+		const idxA = keyIndices[k];
+		const idxB = keyIndices[k + 1];
+		if (idxA === void 0 || idxB === void 0) continue;
+		const startPing = sorted[idxA];
+		const endPing = sorted[idxB];
+		if (startPing === void 0 || endPing === void 0) continue;
+		const dt = endPing.epochSec - startPing.epochSec;
+		if (dt <= MIN_SEGMENT_DURATION_SEC) continue;
+		const groundspeedMps = slantDistanceMeters(startPing, endPing) / dt;
+		const midLat = (startPing.lat + endPing.lat) / 2;
+		const midLon = (startPing.lon + endPing.lon) / 2;
+		segments.push({
+			id: `${meta.flightId}_${String(Math.floor(startPing.epochSec))}`,
+			flightId: meta.flightId,
+			icao24: meta.icao24,
+			typeCode: meta.typeCode,
+			category: meta.category,
+			dateIso: meta.dateIso,
+			startEpochSec: startPing.epochSec,
+			endEpochSec: endPing.epochSec,
+			startGeo: {
+				lat: startPing.lat,
+				lon: startPing.lon,
+				altMeters: startPing.altMeters
+			},
+			endGeo: {
+				lat: endPing.lat,
+				lon: endPing.lon,
+				altMeters: endPing.altMeters
+			},
+			groundspeedMps,
+			h3Cell: encodeSpatialCell(midLat, midLon, 6)
+		});
+	}
+	return segments;
+}
+// src/solver/gauss-newton.ts
+/**
+* Residual size, in standard deviations, at which the score stops growing: a measurement further out than this is an outlier whatever its distance, so one gross mismatch cannot outweigh the rest of the evidence. Five sigma keeps a gross mismatch (ten sigma) costlier than a modest one (three sigma), which a three-sigma cap would score alike.
+*/
+const OUTLIER_SIGMAS = 5;
+/**
+* Standard deviation, in m/s, of the along-track wind. The Doppler fit measures speed through the air and ADS-B reports speed over the ground, so the two differ by the wind component along the track; a 5 m/s (about 10 knot) spread covers ordinary conditions.
+*/
+const WIND_SIGMA_MPS = 5;
+/**
+* Standard deviation, in seconds, of the modelled-minus-observed difference between the closest-approach times of two flyovers in one episode. A design choice: it sets how strongly timing weighs against slant, speed and frequency evidence.
+*/
+const CPA_OFFSET_SIGMA_SEC = .8;
+/**
+* Standard deviation, in Hz, of a ridge-point frequency residual. A design choice: it sets how strongly the ridge shape weighs against slant, speed and timing evidence.
+*/
+const RIDGE_FREQ_SIGMA_HZ = .35;
+/**
+* Largest per-flyover fundamental-frequency trim, in Hz, that the residual evaluation absorbs before scoring the ridge. It allows a small engine speed (RPM) trim per aircraft, and its bound stops a wrong trajectory from being fitted by shifting its whole ridge.
+*/
+const MAX_F0_TRIM_HZ = 2.5;
+/**
+* Standard deviation, in metres, of the weak isotropic prior added to the Fisher information so that a single-flyover ribbon, which constrains one direction only, stays invertible.
+*/
+const PRIOR_SIGMA_METERS = 2500;
+/**
+* Smallest Fisher eigenvalue, in 1/m^2, the confidence ellipse accepts, so that a degenerate matrix cannot divide by zero.
+*/
+const MIN_FISHER_EIGENVALUE = 1e-9;
+/**
+* Chi-square quantile with two degrees of freedom at probability 0.95 (`-2 * ln(0.05)`, rounded to five decimals): the squared radius of the 95% confidence ellipse in standard deviations.
+*/
+const CHI_SQUARE_2DOF_95 = 5.99146;
+/**
+* Largest semi-axis in metres that a confidence ellipse reports; a larger uncertainty is reported as this bound.
+*/
+const MAX_ELLIPSE_SEMI_AXIS_METERS = 15e3;
+/**
+* Smallest semi-major axis in metres that a confidence ellipse reports, so a very sharp fit is not reported as an exact position.
+*/
+const MIN_ELLIPSE_SEMI_MAJOR_METERS = 2;
+/**
+* Smallest semi-minor axis in metres that a confidence ellipse reports, so a very sharp fit is not reported as an exact position.
+*/
+const MIN_ELLIPSE_SEMI_MINOR_METERS = 1.5;
+/**
+* Angle in degrees between the East axis (where the mathematical angle starts) and North (where the compass bearing starts), so that `bearing = NORTH_FROM_EAST_DEG - angle`.
+*/
+const NORTH_FROM_EAST_DEG = 90;
+/**
+* Number of Levenberg-Marquardt iterations. Each iteration costs three residual evaluations over every pair, so it bounds the work spent on one candidate; a design choice that trades convergence for work.
+*/
+const MAX_REFINEMENT_ITERATIONS = 8;
+/**
+* Initial Levenberg-Marquardt damping, as a fraction of the diagonal of the normal equations. A small value starts close to a pure Gauss-Newton step.
+*/
+const INITIAL_DAMPING = .01;
+/**
+* Factor by which damping shrinks after an accepted step, moving towards a pure Gauss-Newton step.
+*/
+const DAMPING_DECREASE_FACTOR = .3;
+/**
+* Factor by which damping grows after a rejected step, moving towards a short gradient-descent step.
+*/
+const DAMPING_INCREASE_FACTOR = 4;
+/**
+* Finite-difference step in metres used for the numerical Jacobian: a design choice that trades truncation error (too large a step) against floating-point noise in the residual differences (too small).
+*/
+const FINITE_DIFFERENCE_STEP_METERS = 2;
+/**
+* Floor on a diagonal entry of the normal equations, in the units of the Jacobian squared, so that an unconstrained direction still receives damping.
+*/
+const MIN_NORMAL_DIAGONAL = 1e-4;
+/**
+* Determinant magnitude below which the damped normal equations are treated as singular and the refinement stops.
+*/
+const SINGULAR_DETERMINANT = 1e-12;
+/**
+* Longest single refinement step in metres, which keeps a poorly conditioned step from leaving the neighbourhood where the linearisation holds.
+*/
+const MAX_STEP_METERS = 1500;
+/**
+* Accepted step length in metres below which the refinement has converged.
+*/
+const CONVERGED_STEP_METERS = .25;
+/**
+* Log-likelihood cost of leaving an observation unmatched. An observation that no segment explains contributes every residual term it would have had (one slant residual, one speed residual and one frequency residual per ridge point) at the outlier gate, so a hypothesis cannot outscore a rival by ignoring evidence: a poor fit costs at most this much, and an omission costs exactly this much.
+* @param observation - The observation a hypothesis does not explain.
+* @returns A non-negative amount to subtract from the hypothesis's log-posterior.
+*/
+function unmatchedObservationLogPenalty(observation) {
+	return (2 + observation.ridgePoints.length) * OUTLIER_SIGMAS ** 2 / 2;
+}
+/**
+* Evaluates the frequency + CPA timing residual vector and log-likelihood at a local East-North offset `(eastMeters, northMeters)` from `referenceOrigin`.
+*/
+function evaluateResidualsAtEnuOffset(referenceOrigin, offsetEnu, pairs, context) {
+	const { eastMeters, northMeters } = offsetEnu;
+	const { demGrid, soundSpeedMps } = context;
+	const shiftedGeo = localEnuToGeo(referenceOrigin, {
+		x: eastMeters,
+		y: northMeters,
+		z: 0
+	});
+	const groundAlt = interpolateTerrainElevationMeters(shiftedGeo.lat, shiftedGeo.lon, demGrid);
+	const point = {
+		lat: shiftedGeo.lat,
+		lon: shiftedGeo.lon,
+		altMeters: groundAlt
+	};
+	const firstPair = pairs[0];
+	if (firstPair === void 0) return {
+		point,
+		estimatedStartEpochSec: 0,
+		residuals: [],
+		rmsFreqResidualHz: 0
+	};
+	const episodeReference = /* @__PURE__ */ new Map();
+	for (const pair of pairs) if (!episodeReference.has(pair.observation.episodeId)) episodeReference.set(pair.observation.episodeId, pair);
+	const sameClockPairs = pairs.filter((pair) => pair.observation.episodeId === firstPair.observation.episodeId);
+	let sumStartEpoch = 0;
+	for (const pair of sameClockPairs) {
+		const cpa = computeSegmentCpa(point, pair.segment, soundSpeedMps);
+		sumStartEpoch += cpa.cpaDelayedEpochSec - pair.observation.cpaTimeSec;
+	}
+	const estimatedStartEpochSec = sumStartEpoch / sameClockPairs.length;
+	const residuals = [];
+	let freqSqSum = 0;
+	let freqCount = 0;
+	for (const pair of pairs) {
+		const { observation, segment } = pair;
+		const cpa = computeSegmentCpa(point, segment, soundSpeedMps);
+		const slantDiff = cpa.cpaSlantMeters - observation.kinematics.inferredSlantMeters;
+		const slantSigma = Math.max(40, observation.kinematics.slantStdMeters);
+		residuals.push(slantDiff / slantSigma);
+		const speedSigma = Math.hypot(WIND_SIGMA_MPS, observation.kinematics.speedStdMps);
+		residuals.push((segment.groundspeedMps - observation.kinematics.inferredSpeedMps) / speedSigma);
+		const reference = episodeReference.get(observation.episodeId);
+		if (reference !== void 0 && reference !== pair) {
+			const firstCpa = computeSegmentCpa(point, reference.segment, soundSpeedMps);
+			const timeDiff = cpa.cpaDelayedEpochSec - firstCpa.cpaDelayedEpochSec - (observation.cpaTimeSec - reference.observation.cpaTimeSec);
+			residuals.push(timeDiff / CPA_OFFSET_SIGMA_SEC);
+		}
+		const sampleEpochs = observation.ridgePoints.map((pt) => cpa.cpaDelayedEpochSec + (pt.timeSec - observation.cpaTimeSec));
+		const modeledCurve = synthesizeRetardedDopplerCurve(point, segment, {
+			baseFreqHz: observation.kinematics.baseFreqHz,
+			obsEpochTimesSec: sampleEpochs,
+			soundSpeedMps
+		});
+		let meanFreqOffset = 0;
+		const nPts = Math.min(observation.ridgePoints.length, modeledCurve.length);
+		for (let k = 0; k < nPts; k += 1) {
+			const obsPt = observation.ridgePoints[k];
+			const modPt = modeledCurve[k];
+			if (obsPt !== void 0 && modPt !== void 0) meanFreqOffset += obsPt.freqHz - modPt.observedFreqHz;
+		}
+		meanFreqOffset = nPts > 0 ? meanFreqOffset / nPts : 0;
+		const clampedF0Trim = Math.max(-2.5, Math.min(MAX_F0_TRIM_HZ, meanFreqOffset));
+		for (let k = 0; k < nPts; k += 1) {
+			const obsPt = observation.ridgePoints[k];
+			const modPt = modeledCurve[k];
+			if (obsPt !== void 0 && modPt !== void 0) {
+				const freqErr = obsPt.freqHz - (modPt.observedFreqHz + clampedF0Trim);
+				freqSqSum += freqErr * freqErr;
+				freqCount += 1;
+				residuals.push(freqErr / RIDGE_FREQ_SIGMA_HZ);
+			}
+		}
+	}
+	return {
+		point,
+		estimatedStartEpochSec,
+		residuals,
+		rmsFreqResidualHz: freqCount > 0 ? Math.sqrt(freqSqSum / freqCount) : 0
+	};
+}
+/**
+* Converts a 2x2 Fisher Information matrix `[I_xx, I_xy, I_yx, I_yy]` in inverse-square meters into a 95% confidence ellipse (`chi2_2(0.95) = 5.991`).
+* @param fisher - 2x2 symmetric Fisher Information matrix entries `[I_xx, I_xy, I_yx, I_yy]`.
+* @returns Semi-major axis (m), semi-minor axis (m), and compass bearing of semi-major axis (degrees).
+*/
+function fisherToConfidenceEllipse95(fisher) {
+	const priorReg = 1 / (PRIOR_SIGMA_METERS * PRIOR_SIGMA_METERS);
+	const ixx = fisher[0] + priorReg;
+	const ixy = (fisher[1] + fisher[2]) / 2;
+	const iyy = fisher[3] + priorReg;
+	const trace = ixx + iyy;
+	const diff = ixx - iyy;
+	const disc = Math.hypot(diff, 2 * ixy);
+	const lambdaMax = Math.max(MIN_FISHER_EIGENVALUE, (trace + disc) / 2);
+	const lambdaMin = Math.max(MIN_FISHER_EIGENVALUE, (trace - disc) / 2);
+	const chi2Scale = Math.sqrt(CHI_SQUARE_2DOF_95);
+	const ellipseSemiMajorMeters = Math.min(MAX_ELLIPSE_SEMI_AXIS_METERS, Math.max(MIN_ELLIPSE_SEMI_MAJOR_METERS, chi2Scale / Math.sqrt(lambdaMin)));
+	const ellipseSemiMinorMeters = Math.min(MAX_ELLIPSE_SEMI_AXIS_METERS, Math.max(MIN_ELLIPSE_SEMI_MINOR_METERS, chi2Scale / Math.sqrt(lambdaMax)));
+	const angleRad = Math.atan2(2 * ixy, ixx - iyy) / 2 + Math.PI / 2;
+	return {
+		ellipseSemiMajorMeters,
+		ellipseSemiMinorMeters,
+		ellipseBearingDeg: ((NORTH_FROM_EAST_DEG - angleRad * 180 / Math.PI) % 360 + 360) % 360
+	};
+}
+/**
+* Refines a candidate observer coordinate `(lat, lon)` without spatial grids using damped Levenberg-Marquardt nonlinear least squares and computes the 2x2 Fisher Information matrix and 95% confidence ellipse.
+* @param seedGeo - Coarse initial coordinate (e.g. H3 cell center or cylinder intersection).
+* @param pairs - Matched observation-to-segment pairs (1 or more flyovers).
+* @param options - Terrain elevation grid and sound speed.
+* @returns Optimized coordinate, log-likelihood, Fisher Information matrix, and 95% error ellipse.
+*/
+function refineObserverCoordinateGaussNewton(seedGeo, pairs, options = {}) {
+	const { demGrid = [], soundSpeedMps = 343 } = options;
+	const context = {
+		demGrid,
+		soundSpeedMps
+	};
+	let eastMeters = 0;
+	let northMeters = 0;
+	let damping = INITIAL_DAMPING;
+	let currentEval = evaluateResidualsAtEnuOffset(seedGeo, {
+		eastMeters,
+		northMeters
+	}, pairs, context);
+	let currentCost = currentEval.residuals.reduce((acc, r) => acc + r * r, 0);
+	let jtj00 = 0;
+	let jtj01 = 0;
+	let jtj11 = 0;
+	for (let iter = 0; iter < MAX_REFINEMENT_ITERATIONS; iter += 1) {
+		const evalPlusE = evaluateResidualsAtEnuOffset(seedGeo, {
+			eastMeters: eastMeters + FINITE_DIFFERENCE_STEP_METERS,
+			northMeters
+		}, pairs, context);
+		const evalPlusN = evaluateResidualsAtEnuOffset(seedGeo, {
+			eastMeters,
+			northMeters: northMeters + FINITE_DIFFERENCE_STEP_METERS
+		}, pairs, context);
+		jtj00 = 0;
+		jtj01 = 0;
+		jtj11 = 0;
+		let jtr0 = 0;
+		let jtr1 = 0;
+		const nRes = currentEval.residuals.length;
+		for (let k = 0; k < nRes; k += 1) {
+			const r0 = currentEval.residuals[k] ?? 0;
+			const rE = evalPlusE.residuals[k] ?? r0;
+			const rN = evalPlusN.residuals[k] ?? r0;
+			const jE = (rE - r0) / FINITE_DIFFERENCE_STEP_METERS;
+			const jN = (rN - r0) / FINITE_DIFFERENCE_STEP_METERS;
+			jtj00 += jE * jE;
+			jtj01 += jE * jN;
+			jtj11 += jN * jN;
+			jtr0 += jE * r0;
+			jtr1 += jN * r0;
+		}
+		const a00 = jtj00 + damping * Math.max(MIN_NORMAL_DIAGONAL, jtj00);
+		const a11 = jtj11 + damping * Math.max(MIN_NORMAL_DIAGONAL, jtj11);
+		const det = a00 * a11 - jtj01 * jtj01;
+		if (Math.abs(det) < SINGULAR_DETERMINANT) break;
+		const rawStepE = -(a11 * jtr0 - jtj01 * jtr1) / det;
+		const rawStepN = -(-jtj01 * jtr0 + a00 * jtr1) / det;
+		const stepNorm = Math.hypot(rawStepE, rawStepN);
+		const scale = stepNorm > MAX_STEP_METERS ? MAX_STEP_METERS / stepNorm : 1;
+		const stepE = rawStepE * scale;
+		const stepN = rawStepN * scale;
+		const candidateEval = evaluateResidualsAtEnuOffset(seedGeo, {
+			eastMeters: eastMeters + stepE,
+			northMeters: northMeters + stepN
+		}, pairs, context);
+		const candidateCost = candidateEval.residuals.reduce((acc, r) => acc + r * r, 0);
+		if (candidateCost < currentCost) {
+			eastMeters += stepE;
+			northMeters += stepN;
+			currentEval = candidateEval;
+			currentCost = candidateCost;
+			damping *= DAMPING_DECREASE_FACTOR;
+			if (Math.hypot(stepE, stepN) < CONVERGED_STEP_METERS) break;
+		} else damping *= DAMPING_INCREASE_FACTOR;
+	}
+	const fisherInfo = [
+		jtj00,
+		jtj01,
+		jtj01,
+		jtj11
+	];
+	const ellipse = fisherToConfidenceEllipse95(fisherInfo);
+	const logLikelihood = -(currentEval.residuals.reduce((acc, r) => acc + Math.min(r * r, OUTLIER_SIGMAS ** 2), 0) / 2);
+	return {
+		lat: currentEval.point.lat,
+		lon: currentEval.point.lon,
+		altMeters: currentEval.point.altMeters,
+		estimatedStartEpochSec: currentEval.estimatedStartEpochSec,
+		rmsFreqResidualHz: currentEval.rmsFreqResidualHz,
+		logLikelihood,
+		fisherInfo,
+		ellipseSemiMajorMeters: ellipse.ellipseSemiMajorMeters,
+		ellipseSemiMinorMeters: ellipse.ellipseSemiMinorMeters,
+		ellipseBearingDeg: ellipse.ellipseBearingDeg
+	};
+}
+// src/solver/session.ts
+/** Hypotheses kept after ranking, which bounds the work each further flyover costs. */
+const MAX_HYPOTHESES = 15;
+/** Milliseconds in a second, the divisor from `Date.now()` to epoch seconds. */
+const MS_PER_SEC = 1e3;
+/** Radix of the random part of a session id: digits and lowercase letters. */
+const SESSION_ID_RADIX = 36;
+/** Characters `Math.random().toString(36)` places before the fraction digits (the leading `0.`), skipped when taking the random part. */
+const SESSION_ID_PREFIX_LENGTH = 2;
+/** Air temperature in degrees Celsius assumed for the speed of sound when the caller gives none; a design default for a mild day. */
+const DEFAULT_AMBIENT_TEMP_CELSIUS = 20;
+/** Noise floor in decibels reported for an episode before its first noise update, below any floor measured in practice so that it never reads as pollution. */
+const INITIAL_NOISE_FLOOR_DB = -80;
+/** Number of standard deviations of the measured speed uncertainty allowed between a measured Doppler speed and a segment's ground speed, when that exceeds the along-track wind allowance. */
+const SPEED_TOLERANCE_SIGMAS = 2.5;
+/** Largest difference in metres between a segment's closest-approach slant distance at a cell centre and the measured slant distance for the cell to seed a hypothesis. It trades missed seeds against refinement work, since each admitted seed costs a Gauss-Newton run. */
+const SEED_SLANT_GATE_METERS = 3500;
+/** Largest difference in seconds between the arrival-time gap a candidate segment implies and the measured gap on one clock for the segment to explain a further flyover. */
+const TIMING_GAP_GATE_SEC = 30;
+/** Largest difference in metres between a candidate segment's closest-approach slant distance at a hypothesis and the measured slant distance for the segment to explain a further flyover. */
+const MATCH_SLANT_GATE_METERS = 4e3;
+/**
+* Reads the system clock as whole seconds since the Unix epoch.
+* @returns Epoch seconds, rounded down.
+*/
+function nowEpochSec() {
+	return Math.floor(Date.now() / MS_PER_SEC);
+}
+/**
+* Continuous & Episodic Bayesian Refinement Engine.
+*
+* Supports leaving the microphone running continuously, or pausing and resuming across hours, days,
+* or device reboots. Ingests observations sequentially and computes an accumulating log-posterior
+* surface and Fisher Information covariance matrix across surviving candidate hypotheses.
+*/
+var DopplerSessionEngine = class DopplerSessionEngine {
+	session;
+	dataset;
+	segmentsById;
+	constructor(options) {
+		this.dataset = options.dataset;
+		const segMap = /* @__PURE__ */ new Map();
+		for (const seg of options.dataset.segments) segMap.set(seg.id, seg);
+		this.segmentsById = segMap;
+		if (options.initialSession !== void 0) this.session = { ...options.initialSession };
+		else {
+			const now = nowEpochSec();
+			this.session = {
+				id: `sess_${String(now)}_${Math.random().toString(SESSION_ID_RADIX).slice(SESSION_ID_PREFIX_LENGTH, 8)}`,
+				createdAtEpochSec: now,
+				updatedAtEpochSec: now,
+				ambientTempCelsius: options.ambientTempCelsius ?? DEFAULT_AMBIENT_TEMP_CELSIUS,
+				constraints: options.constraints ?? {},
+				enfSignature: {
+					detected: false,
+					nominalHz: "unknown",
+					measuredFreqHz: 0,
+					snrDb: 0,
+					regionHint: "No ENF analysis performed yet"
+				},
+				episodes: [],
+				observations: [],
+				hypotheses: []
+			};
+		}
+	}
+	/**
+	* Returns an immutable snapshot of the current session state.
+	*/
+	getSession() {
+		return this.session;
+	}
+	/**
+	* Updates multi-axis user constraints (bounding box, date range, hour window, ENF grid) and prunes incompatible hypotheses.
+	*/
+	updateConstraints(constraints) {
+		const updatedHypotheses = this.session.hypotheses.filter((h) => matchesSearchConstraints({
+			lat: h.lat,
+			lon: h.lon,
+			dateIso: h.dateIso,
+			epochSec: h.estimatedStartEpochSec
+		}, constraints));
+		this.session = {
+			...this.session,
+			updatedAtEpochSec: nowEpochSec(),
+			constraints: {
+				...this.session.constraints,
+				...constraints
+			},
+			hypotheses: updatedHypotheses
+		};
+		return this.session;
+	}
+	/**
+	* Starts a new listening episode (e.g. user clicks "Start Listening" or device boots up).
+	*/
+	startEpisode(startedAtEpochSec) {
+		const newEpisode = {
+			id: `ep_${String(startedAtEpochSec)}_${String(this.session.episodes.length + 1)}`,
+			startedAtSec: startedAtEpochSec,
+			endedAtSec: startedAtEpochSec,
+			status: "active",
+			currentNoiseFloorDb: INITIAL_NOISE_FLOOR_DB,
+			noisePolluted: false,
+			quietIntervals: []
+		};
+		this.session = {
+			...this.session,
+			updatedAtEpochSec: nowEpochSec(),
+			episodes: [...this.session.episodes, newEpisode]
+		};
+		return newEpisode;
+	}
+	/**
+	* Updates episode telemetry with real-time in-band noise floor and pollution gating.
+	*/
+	updateEpisodeNoise(episodeId, currentNoiseFloorDb, noisePolluted, currentEpochSec) {
+		const episodes = this.session.episodes.map((ep) => {
+			if (ep.id !== episodeId || ep.status !== "active") return ep;
+			return {
+				...ep,
+				endedAtSec: currentEpochSec,
+				currentNoiseFloorDb,
+				noisePolluted
+			};
+		});
+		this.session = {
+			...this.session,
+			updatedAtEpochSec: nowEpochSec(),
+			episodes
+		};
+	}
+	/**
+	* Pauses an active listening episode (e.g. user pauses, device enters sleep, or ambient noise exceeds threshold).
+	*/
+	pauseEpisode(episodeId, pausedAtEpochSec) {
+		const episodes = this.session.episodes.map((ep) => {
+			if (ep.id !== episodeId) return ep;
+			return {
+				...ep,
+				endedAtSec: pausedAtEpochSec,
+				status: "paused"
+			};
+		});
+		this.session = {
+			...this.session,
+			updatedAtEpochSec: nowEpochSec(),
+			episodes
+		};
+	}
+	/**
+	* Resumes a paused episode or starts a follow-up active episode within the session.
+	*/
+	resumeEpisode(episodeId, resumedAtEpochSec) {
+		const existing = this.session.episodes.find((ep) => ep.id === episodeId);
+		if (existing?.status === "paused") {
+			const episodes = this.session.episodes.map((ep) => {
+				if (ep.id !== episodeId) return ep;
+				return {
+					...ep,
+					status: "active",
+					endedAtSec: resumedAtEpochSec
+				};
+			});
+			this.session = {
+				...this.session,
+				updatedAtEpochSec: nowEpochSec(),
+				episodes
+			};
+			return {
+				...existing,
+				status: "active",
+				endedAtSec: resumedAtEpochSec
+			};
+		}
+		return this.startEpisode(resumedAtEpochSec);
+	}
+	/**
+	* Ingests an extracted DopplerObservation and performs sequential Bayesian refinement.
+	*
+	* - First flyover: creates candidate hypotheses along matching flight track cylinders.
+	* - Second flyover: queries constellation hash index or pairs with existing observation to collapse candidates to curve intersections.
+	* - Third+ flyovers: refits each surviving hypothesis on every flyover it explains, so the Fisher Information matrix is that of the joint fit (shrinking O(1/sqrt(N))) and no flyover is counted twice.
+	*
+	* An observation whose id was ingested before replaces it, and the hypotheses are rebuilt from the whole list: a live listener re-reports a growing flyover under one id, and the latest report must not stack on the earlier ones.
+	*/
+	ingestObservation(obs) {
+		const index = this.session.observations.findIndex((existing) => existing.id === obs.id);
+		if (index === -1) return this.applyObservation(obs);
+		const observations = this.session.observations.map((existing, position) => position === index ? obs : existing);
+		this.session = {
+			...this.session,
+			observations: [],
+			hypotheses: []
+		};
+		for (const observation of observations) this.applyObservation(observation);
+		return this.session;
+	}
+	applyObservation(obs) {
+		const soundSpeedMps = speedOfSoundAtTempMps(this.session.ambientTempCelsius);
+		const existingObs = this.session.observations;
+		const allObs = [...existingObs, obs];
+		let newHypotheses = [];
+		if (existingObs.length === 0) newHypotheses = this.spawnInitialHypotheses(obs, soundSpeedMps, allObs);
+		else if (this.session.hypotheses.length === 0) {
+			const prevObs = existingObs.findLast((candidate) => candidate.episodeId === obs.episodeId);
+			newHypotheses = prevObs === void 0 ? [] : this.matchConstellations({
+				obsA: prevObs,
+				obsB: obs,
+				allObs
+			}, soundSpeedMps);
+			if (newHypotheses.length === 0) newHypotheses = this.spawnInitialHypotheses(obs, soundSpeedMps, allObs);
+		} else newHypotheses = this.refineExistingHypotheses(obs, soundSpeedMps);
+		newHypotheses = newHypotheses.filter((h) => matchesSearchConstraints({
+			lat: h.lat,
+			lon: h.lon,
+			dateIso: h.dateIso,
+			epochSec: h.estimatedStartEpochSec
+		}, this.session.constraints));
+		if (newHypotheses.length > 0) {
+			const maxLog = Math.max(...newHypotheses.map((h) => h.logPosterior));
+			const expSum = newHypotheses.reduce((acc, h) => acc + Math.exp(h.logPosterior - maxLog), 0);
+			newHypotheses = newHypotheses.map((h) => ({
+				...h,
+				probability: expSum > 0 ? Math.exp(h.logPosterior - maxLog) / expSum : 1 / newHypotheses.length
+			}));
+			newHypotheses.sort((a, b) => b.logPosterior - a.logPosterior);
+		}
+		this.session = {
+			...this.session,
+			updatedAtEpochSec: nowEpochSec(),
+			observations: allObs,
+			hypotheses: newHypotheses
+		};
+		return this.session;
+	}
+	/**
+	* Log-posterior of a hypothesis: the joint fit of the flyovers it explains, less the cost of every flyover it leaves unexplained.
+	*/
+	static scoreHypothesis(fitLogLikelihood, allObs, matches) {
+		return fitLogLikelihood - allObs.filter((obs) => !matches.some((match) => match.observationId === obs.id)).reduce((total, obs) => total + unmatchedObservationLogPenalty(obs), 0);
+	}
+	/**
+	* Allowed speed difference between a measured Doppler speed and a segment's ground speed, which differ by the along-track wind.
+	*/
+	static speedTolerance(kinematics) {
+		return Math.max(15, kinematics.speedStdMps * SPEED_TOLERANCE_SIGMAS);
+	}
+	/**
+	* Generates initial candidate hypotheses along flight tracks matching a single flyover.
+	*/
+	spawnInitialHypotheses(obs, soundSpeedMps, allObs) {
+		const candidates = [];
+		const targetSpeed = obs.kinematics.inferredSpeedMps;
+		const speedTolerance = DopplerSessionEngine.speedTolerance(obs.kinematics);
+		for (const seg of this.dataset.segments) {
+			if (seg.category === "jet") continue;
+			if (Math.abs(seg.groundspeedMps - targetSpeed) > speedTolerance) continue;
+			const center = decodeSpatialCellCenter(seg.h3Cell);
+			const groundAlt = interpolateTerrainElevationMeters(center.lat, center.lon, this.dataset.elevationGrid);
+			const seed = {
+				lat: center.lat,
+				lon: center.lon,
+				altMeters: groundAlt
+			};
+			const cpa = computeSegmentCpa(seed, seg, soundSpeedMps);
+			if (Math.abs(cpa.cpaSlantMeters - obs.kinematics.inferredSlantMeters) > SEED_SLANT_GATE_METERS) continue;
+			const refined = refineObserverCoordinateGaussNewton(seed, [{
+				observation: obs,
+				segment: seg
+			}], {
+				demGrid: this.dataset.elevationGrid,
+				soundSpeedMps
+			});
+			const matches = [{
+				observationId: obs.id,
+				segmentId: seg.id
+			}];
+			candidates.push({
+				id: `hyp_${seg.id}_${String(candidates.length + 1)}`,
+				h3Cell: seg.h3Cell,
+				dateIso: seg.dateIso,
+				lat: refined.lat,
+				lon: refined.lon,
+				altMeters: refined.altMeters,
+				estimatedStartEpochSec: refined.estimatedStartEpochSec,
+				logPosterior: DopplerSessionEngine.scoreHypothesis(refined.logLikelihood, allObs, matches),
+				probability: 0,
+				rmsFreqResidualHz: refined.rmsFreqResidualHz,
+				fisherInfo: refined.fisherInfo,
+				ellipseSemiMajorMeters: refined.ellipseSemiMajorMeters,
+				ellipseSemiMinorMeters: refined.ellipseSemiMinorMeters,
+				ellipseBearingDeg: refined.ellipseBearingDeg,
+				matches
+			});
+		}
+		return DopplerSessionEngine.keepBest(candidates);
+	}
+	/**
+	* Keeps the best-scoring hypotheses. Ranking comes before the cut: dataset order says nothing about fit, so cutting first can discard the true track.
+	*/
+	static keepBest(candidates) {
+		return [...candidates].sort((a, b) => b.logPosterior - a.logPosterior).slice(0, MAX_HYPOTHESES);
+	}
+	/**
+	* Matches candidate constellations from the Shazam-style hash table.
+	*/
+	matchConstellations(flyovers, soundSpeedMps) {
+		const { obsA, obsB, allObs } = flyovers;
+		const keys = expandConstellationQueryKeys(obsA.kinematics.inferredSpeedMps, obsB.kinematics.inferredSpeedMps, obsB.cpaTimeSec - obsA.cpaTimeSec);
+		const matchedEntries = this.dataset.constellations.filter((c) => keys.has(c.hashKey));
+		const candidates = [];
+		for (const entry of matchedEntries) {
+			const segA = this.segmentsById.get(entry.segmentIdA);
+			const segB = this.segmentsById.get(entry.segmentIdB);
+			if (segA === void 0 || segB === void 0) continue;
+			const groundAlt = interpolateTerrainElevationMeters(entry.centerLat, entry.centerLon, this.dataset.elevationGrid);
+			const refined = refineObserverCoordinateGaussNewton({
+				lat: entry.centerLat,
+				lon: entry.centerLon,
+				altMeters: groundAlt
+			}, [{
+				observation: obsA,
+				segment: segA
+			}, {
+				observation: obsB,
+				segment: segB
+			}], {
+				demGrid: this.dataset.elevationGrid,
+				soundSpeedMps
+			});
+			const matches = [{
+				observationId: obsA.id,
+				segmentId: segA.id
+			}, {
+				observationId: obsB.id,
+				segmentId: segB.id
+			}];
+			candidates.push({
+				id: `hyp_${entry.segmentIdA}_${entry.segmentIdB}`,
+				h3Cell: entry.h3Cell,
+				dateIso: entry.dateIso,
+				lat: refined.lat,
+				lon: refined.lon,
+				altMeters: refined.altMeters,
+				estimatedStartEpochSec: refined.estimatedStartEpochSec,
+				logPosterior: DopplerSessionEngine.scoreHypothesis(refined.logLikelihood, allObs, matches),
+				probability: 0,
+				rmsFreqResidualHz: refined.rmsFreqResidualHz,
+				fisherInfo: refined.fisherInfo,
+				ellipseSemiMajorMeters: refined.ellipseSemiMajorMeters,
+				ellipseSemiMinorMeters: refined.ellipseSemiMinorMeters,
+				ellipseBearingDeg: refined.ellipseBearingDeg,
+				matches
+			});
+		}
+		return DopplerSessionEngine.keepBest(candidates);
+	}
+	/**
+	* Sequentially refines existing candidate hypotheses by refitting each on every flyover it explains, the new one included.
+	*/
+	refineExistingHypotheses(newObs, soundSpeedMps) {
+		const refinedList = [];
+		const allObs = [...this.session.observations, newObs];
+		const observationsById = new Map(allObs.map((obs) => [obs.id, obs]));
+		for (const hyp of this.session.hypotheses) {
+			const hypCoord = {
+				lat: hyp.lat,
+				lon: hyp.lon,
+				altMeters: hyp.altMeters
+			};
+			let bestSeg = null;
+			let minSlantDiff = Infinity;
+			const firstMatch = hyp.matches[0];
+			const firstSeg = firstMatch === void 0 ? void 0 : this.segmentsById.get(firstMatch.segmentId);
+			const firstObs = firstMatch === void 0 ? void 0 : observationsById.get(firstMatch.observationId);
+			const firstCpa = firstSeg === void 0 ? null : computeSegmentCpa(hypCoord, firstSeg, soundSpeedMps);
+			const timingReference = firstCpa !== null && firstObs?.episodeId === newObs.episodeId ? {
+				firstCpa,
+				firstObs
+			} : null;
+			const speedTolerance = DopplerSessionEngine.speedTolerance(newObs.kinematics);
+			for (const seg of this.dataset.segments) {
+				if (seg.dateIso !== hyp.dateIso || seg.category === "jet") continue;
+				if (hyp.matches.some((match) => match.segmentId === seg.id)) continue;
+				if (Math.abs(seg.groundspeedMps - newObs.kinematics.inferredSpeedMps) > speedTolerance) continue;
+				const cpa = computeSegmentCpa(hypCoord, seg, soundSpeedMps);
+				if (timingReference !== null) {
+					const expectedDeltaSec = newObs.cpaTimeSec - timingReference.firstObs.cpaTimeSec;
+					const actualDeltaSec = cpa.cpaDelayedEpochSec - timingReference.firstCpa.cpaDelayedEpochSec;
+					if (Math.abs(actualDeltaSec - expectedDeltaSec) > TIMING_GAP_GATE_SEC) continue;
+				}
+				const slantDiff = Math.abs(cpa.cpaSlantMeters - newObs.kinematics.inferredSlantMeters);
+				if (slantDiff < minSlantDiff && slantDiff < MATCH_SLANT_GATE_METERS) {
+					minSlantDiff = slantDiff;
+					bestSeg = seg;
+				}
+			}
+			if (bestSeg === null) {
+				refinedList.push({
+					...hyp,
+					logPosterior: hyp.logPosterior - unmatchedObservationLogPenalty(newObs)
+				});
+				continue;
+			}
+			const matches = [...hyp.matches, {
+				observationId: newObs.id,
+				segmentId: bestSeg.id
+			}];
+			const refined = refineObserverCoordinateGaussNewton(hypCoord, matches.flatMap((match) => {
+				const observation = observationsById.get(match.observationId);
+				const segment = this.segmentsById.get(match.segmentId);
+				return observation !== void 0 && segment !== void 0 ? [{
+					observation,
+					segment
+				}] : [];
+			}), {
+				demGrid: this.dataset.elevationGrid,
+				soundSpeedMps
+			});
+			refinedList.push({
+				...hyp,
+				lat: refined.lat,
+				lon: refined.lon,
+				altMeters: refined.altMeters,
+				estimatedStartEpochSec: refined.estimatedStartEpochSec,
+				logPosterior: DopplerSessionEngine.scoreHypothesis(refined.logLikelihood, allObs, matches),
+				rmsFreqResidualHz: refined.rmsFreqResidualHz,
+				fisherInfo: refined.fisherInfo,
+				ellipseSemiMajorMeters: refined.ellipseSemiMajorMeters,
+				ellipseSemiMinorMeters: refined.ellipseSemiMinorMeters,
+				ellipseBearingDeg: refined.ellipseBearingDeg,
+				matches
+			});
+		}
+		return refinedList;
+	}
+};
+// src/time.ts
+/** Milliseconds in a second, for converting between epoch seconds (the unit of every timestamp in the schemas) and the millisecond clocks of `Date` and `performance`. */
+const MS_PER_SECOND = 1e3;
+// src/node/stream-adsb.ts
+/**
+* One trace sample as `adsb.lol` and `tar1090` write it: seconds since the trace's `timestamp`, latitude, longitude and barometric altitude in feet, which is the string `ground` on the ground and null when unreported. Later fields (ground speed, track, flags) are ignored.
+*/
+const RawTracePoint = z.tuple([
+	z.number(),
+	z.number(),
+	z.number(),
+	z.union([
+		z.number(),
+		z.literal("ground"),
+		z.null()
+	])
+]).rest(z.unknown());
+/**
+* Raw trace format from `adsb.lol` or `tar1090` JSON exports.
+*/
+const RawAdsbTraceFileSchema = define(z.object({
+	icao: z.string().min(1),
+	r: z.string().optional(),
+	t: z.string().optional(),
+	desc: z.string().optional(),
+	/** Epoch seconds that each point's offset is counted from. */
+	timestamp: z.number().optional(),
+	trace: z.array(RawTracePoint)
+}));
+/** Altitude above which a ping is cruise traffic that the microphone is not expected to hear: 20,000 ft. */
+const MAX_AUDIBLE_ALTITUDE_METERS = 6096;
+/**
+* Ground speed, in m/s (about 195 knots), above which a segment of an aircraft whose type is not classified is dropped. Light propeller aircraft and helicopters seldom exceed it (about 2 percent of their segments in a sample of real traces), whereas most unclassified types are airliners that fly faster than this below 20,000 ft (about 56 percent of theirs) and have no narrowband propeller tone to match.
+*/
+const MAX_UNCLASSIFIED_SPEED_MPS = 100;
+/** Characters of the ISO 8601 calendar date (`YYYY-MM-DD`) at the start of a `Date.toISOString()` string. */
+const ISO_DATE_LENGTH = 10;
+/** Metres in a foot. */
+const METERS_PER_FOOT = .3048;
+/**
+* Longest gap between pings that is still bridged by a straight line. Across a longer gap the aircraft can have turned, landed or left coverage, and at light-aircraft speeds (about 70 m/s) a two-minute gap is already about 8 km, comparable to the acoustic range, so the run is split instead.
+*/
+const MAX_PING_GAP_SEC = 120;
+function inBox(lat, lon, box) {
+	return lat >= box.minLat && lat <= box.maxLat && lon >= box.minLon && lon <= box.maxLon;
+}
+/**
+* Classifies an ICAO aircraft type code into a propulsion category.
+* @param typeCode - 4-character ICAO aircraft type designator (e.g. `C172`, `B738`, `DA42`, `EC35`).
+* @returns Propulsion category.
+*/
+function classifyAircraftCategory(typeCode) {
+	if (typeCode === void 0 || typeCode === "") return "unknown";
+	const code = typeCode.toUpperCase().trim();
+	if ([
+		"R22",
+		"R44",
+		"R66",
+		"EC20",
+		"EC30",
+		"EC35",
+		"EC45",
+		"B06",
+		"B206",
+		"B407",
+		"AS50",
+		"A109",
+		"S76",
+		"H125",
+		"H135",
+		"H145",
+		"G2CA"
+	].includes(code)) return "helicopter";
+	if ([
+		"C150",
+		"C152",
+		"C172",
+		"C182",
+		"C206",
+		"C210",
+		"PA28",
+		"PA32",
+		"PA34",
+		"PA44",
+		"SR20",
+		"SR22",
+		"DA20",
+		"DA40",
+		"DA42",
+		"P28A",
+		"AA5",
+		"BE36",
+		"BE58",
+		"M20T",
+		"RV7",
+		"RV8",
+		"RV10"
+	].includes(code)) return "piston";
+	if ([
+		"B350",
+		"BE20",
+		"PC12",
+		"TBM7",
+		"TBM8",
+		"TBM9",
+		"DH8D",
+		"AT72",
+		"AT76",
+		"AT45",
+		"C208",
+		"SW4",
+		"D228"
+	].includes(code)) return "turboprop";
+	if ([
+		"A319",
+		"A320",
+		"A321",
+		"A332",
+		"A333",
+		"A359",
+		"B737",
+		"B738",
+		"B739",
+		"B772",
+		"B77W",
+		"B788",
+		"B789",
+		"E190",
+		"E195",
+		"CRJ7",
+		"CRJ9",
+		"C56X",
+		"C680",
+		"GL5T",
+		"GLEX",
+		"FA7X",
+		"CL30"
+	].includes(code)) return "jet";
+	return "unknown";
+}
+/**
+* Converts a raw `adsb.lol` / `tar1090` trace object into compressed 4D piecewise-linear segments.
+* Jet categories are discarded. A ping on the ground, with no altitude, or above 20,000 ft ends the current run, and so does a gap of more than two minutes, so a segment never spans a landing, a climb to cruise or a loss of coverage.
+* @param trace - Raw ADS-B trace record.
+* @param dateIso - ISO calendar date (`YYYY-MM-DD`).
+* @param baseEpochSec - Epoch seconds that the trace's point offsets are counted from.
+* @param options - Region filter and compression tolerance.
+* @returns Array of linear flight segments.
+*/
+function processRawAdsbTrace(trace, dateIso, baseEpochSec, options = {}) {
+	const typeCode = trace.t ?? "unknown";
+	const category = classifyAircraftCategory(typeCode);
+	if (category === "jet") return [];
+	const runs = [];
+	let run = [];
+	const endRun = () => {
+		if (run.length > 0) {
+			runs.push(run);
+			run = [];
+		}
+	};
+	for (const [offsetSec, lat, lon, altFeet] of trace.trace) {
+		const altMeters = typeof altFeet === "number" ? altFeet * METERS_PER_FOOT : void 0;
+		const { bbox } = options;
+		if (altMeters === void 0 || altMeters > MAX_AUDIBLE_ALTITUDE_METERS || bbox !== void 0 && !inBox(lat, lon, bbox)) {
+			endRun();
+			continue;
+		}
+		const epochSec = baseEpochSec + offsetSec;
+		const previous = run[run.length - 1];
+		if (previous !== void 0 && epochSec - previous.epochSec > MAX_PING_GAP_SEC) endRun();
+		run.push({
+			epochSec,
+			lat,
+			lon,
+			altMeters
+		});
+	}
+	endRun();
+	return runs.flatMap((pings) => simplifyTrajectory4D(pings, {
+		flightId: trace.r ?? trace.icao,
+		icao24: trace.icao,
+		typeCode,
+		category,
+		dateIso
+	}, options.toleranceMeters ?? 20)).filter((segment) => category !== "unknown" || segment.groundspeedMps <= MAX_UNCLASSIFIED_SPEED_MPS);
+}
+/**
+* Converts parsed ADS-B JSON into segments: ready-made segments (an array, or an object with `segments`), a raw trace, or an array of raw traces.
+* @param parsed - The parsed JSON value.
+* @param options - Date for raw traces without a `timestamp`.
+* @returns The segments it holds.
+* @throws When the value matches none of the accepted shapes, or a raw trace has neither a `timestamp` nor a date option.
+*/
+function segmentsFromAdsbJson(parsed, options) {
+	if (Array.isArray(parsed)) return parsed.flatMap((element) => segmentsFromAdsbJson(element, options));
+	if (typeof parsed === "object" && parsed !== null && "segments" in parsed) return z.array(LinearFlightSegmentSchema).parse(parsed.segments);
+	if (LinearFlightSegmentSchema.is(parsed)) return [parsed];
+	const trace = RawAdsbTraceFileSchema.parse(parsed);
+	if (trace.timestamp !== void 0) return processRawAdsbTrace(trace, (/* @__PURE__ */ new Date(trace.timestamp * MS_PER_SECOND)).toISOString().slice(0, ISO_DATE_LENGTH), trace.timestamp, options);
+	if (options.dateIso === void 0) throw new Error(`trace ${trace.icao} has no timestamp, so its date is unknown; pass the date`);
+	return processRawAdsbTrace(trace, options.dateIso, Date.parse(`${options.dateIso}T00:00:00Z`) / MS_PER_SECOND, options);
+}
+/**
+* Reads flight segments from ADS-B JSON on disk: a file or every `.json` file of a directory (not recursive). Each file may hold ready-made segments (an array, or an object with `segments`), a raw `adsb.lol` / `tar1090` trace, or an array of raw traces.
+* @param inputPath - A JSON file or a directory of them.
+* @param options - Date for raw traces without a `timestamp`.
+* @returns Segments from every file, in file-name order.
+* @throws When a file is not valid JSON or matches none of the accepted shapes, naming the file.
+*/
+function readAdsbSegments(inputPath, options = {}) {
+	return (statSync(inputPath).isDirectory() ? readdirSync(inputPath).filter((name) => name.endsWith(".json")).sort().map((name) => join(inputPath, name)) : [inputPath]).flatMap((file) => {
+		try {
+			return segmentsFromAdsbJson(JSON.parse(readFileSync(file, "utf8")), options);
+		} catch (error) {
+			throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+	});
+}
+/**
+* Loads and parses a DopplerDataset JSON file from disk.
+* @param filePath - Path to `.json` dataset file.
+* @returns Parsed `DopplerDataset`.
+*/
+function loadDatasetFile(filePath) {
+	const raw = readFileSync(filePath, "utf8");
+	const parsed = JSON.parse(raw);
+	return DopplerDatasetSchema.parse(parsed);
+}
+/** Items serialised per write, so no single string approaches the engine's string length limit however large the dataset. */
+const WRITE_BATCH_ITEMS = 5e3;
+function writeJsonArray(fd, items) {
+	writeSync(fd, "[");
+	for (let start = 0; start < items.length; start += WRITE_BATCH_ITEMS) {
+		const batch = items.slice(start, start + WRITE_BATCH_ITEMS).map((item) => JSON.stringify(item)).join(",");
+		writeSync(fd, start === 0 ? batch : `,${batch}`);
+	}
+	writeSync(fd, "]");
+}
+/**
+* Serializes and saves a DopplerDataset to disk with built constellation index. The file is compact JSON written in batches, because a day of real traffic is hundreds of thousands of segments and one `JSON.stringify` of that overflows the string length limit.
+* @param filePath - Output path.
+* @param segments - Array of linear flight segments.
+* @param demGrid - Optional DEM elevation grid points.
+* @returns The saved `DopplerDataset`.
+*/
+function saveDatasetBundle(filePath, segments, demGrid = []) {
+	const constellations = buildConstellationIndex(segments, { demGrid });
+	const dataset = {
+		version: "1.0.0",
+		generatedAtIso: (/* @__PURE__ */ new Date()).toISOString(),
+		segments,
+		constellations,
+		elevationGrid: demGrid
+	};
+	const fd = openSync(filePath, "w");
+	try {
+		writeSync(fd, `{"version":${JSON.stringify(dataset.version)},"generatedAtIso":${JSON.stringify(dataset.generatedAtIso)},"segments":`);
+		writeJsonArray(fd, segments);
+		writeSync(fd, ",\"constellations\":");
+		writeJsonArray(fd, constellations);
+		writeSync(fd, ",\"elevationGrid\":");
+		writeJsonArray(fd, demGrid);
+		writeSync(fd, "}");
+	} finally {
+		closeSync(fd);
+	}
+	return dataset;
+}
+// src/node/tar-stream.ts
+/** Bytes in a tar block: headers and the padding of entry data are multiples of it. */
+const TAR_BLOCK_BYTES = 512;
+/** Offsets and lengths of the header fields this reader needs (POSIX ustar and GNU tar agree on them). */
+const NAME_FIELD = {
+	offset: 0,
+	length: 100
+};
+const SIZE_FIELD = {
+	offset: 124,
+	length: 12
+};
+const TYPE_FIELD_OFFSET = 156;
+const PREFIX_FIELD = {
+	offset: 345,
+	length: 155
+};
+/** Tar writes sizes as octal text. */
+const OCTAL_RADIX = 8;
+/** Words for the parser state in a truncation error. */
+const STATE_LABELS = {
+	header: "header",
+	longName: "long name",
+	data: "entry",
+	skip: "entry"
+};
+/**
+* A push-driven tar parser: it is fed chunks as they arrive and holds only the bytes of the current header or entry plus the unconsumed remainder of the current chunk.
+* It is a synchronous state machine, so the only suspension point of a reader is the `for await` over the source.
+*/
+var TarParser = class {
+	wanted;
+	state = { kind: "header" };
+	/** Bytes still needed to finish the current state. */
+	need = TAR_BLOCK_BYTES;
+	/** Bytes the current state asked for in total, for the truncation error. */
+	total = TAR_BLOCK_BYTES;
+	/** Collected bytes of the current header, long name or file; skipped bytes are not kept. */
+	collected = [];
+	longName;
+	ended = false;
+	constructor(wanted) {
+		this.wanted = wanted;
+	}
+	/** True once an end-of-archive block has been read: later bytes are ignored. */
+	get isEnded() {
+		return this.ended;
+	}
+	begin(state, length) {
+		this.state = state;
+		this.need = length;
+		this.total = length;
+		this.collected = [];
+	}
+	/**
+	* Feeds one chunk of the stream.
+	* @param chunk - The next bytes of the tar stream.
+	* @returns The files completed by these bytes.
+	* @throws When a header has a size that is not an octal number.
+	*/
+	*push(chunk) {
+		let rest = chunk;
+		while (!this.ended) {
+			if (this.need === 0) {
+				yield* this.complete();
+				continue;
+			}
+			if (rest.length === 0) return;
+			const taken = rest.subarray(0, this.need);
+			if (this.state.kind !== "skip") this.collected.push(taken);
+			this.need -= taken.length;
+			rest = rest.subarray(taken.length);
+		}
+	}
+	/**
+	* Checks that the stream ended on an entry boundary.
+	* @throws When the stream ended inside a header, a long name or an entry.
+	*/
+	finish() {
+		const onBoundary = this.state.kind === "header" && this.need === this.total;
+		if (!this.ended && !onBoundary) throw new Error(`Tar stream ended ${String(this.need)} bytes short of a ${String(this.total)}-byte ${STATE_LABELS[this.state.kind]}`);
+	}
+	*complete() {
+		const state = this.state;
+		const bytes = Buffer.concat(this.collected);
+		switch (state.kind) {
+			case "header":
+				this.readHeader(bytes);
+				break;
+			case "longName":
+				this.longName = field(bytes, {
+					offset: 0,
+					length: bytes.length
+				});
+				this.begin({ kind: "skip" }, state.padding);
+				break;
+			case "data":
+				this.begin({
+					kind: "skip",
+					file: {
+						name: state.name,
+						data: bytes
+					}
+				}, state.padding);
+				break;
+			case "skip":
+				this.begin({ kind: "header" }, TAR_BLOCK_BYTES);
+				if (state.file !== void 0) yield state.file;
+		}
+	}
+	readHeader(header) {
+		if (header.every((byte) => byte === 0)) {
+			this.ended = true;
+			return;
+		}
+		const size = Number.parseInt(field(header, SIZE_FIELD).trim() || "0", OCTAL_RADIX);
+		if (!Number.isFinite(size)) throw new Error("Tar header has a size that is not an octal number");
+		const padding = (TAR_BLOCK_BYTES - size % TAR_BLOCK_BYTES) % TAR_BLOCK_BYTES;
+		const type = String.fromCharCode(header[TYPE_FIELD_OFFSET] ?? 0);
+		if (type === "L") {
+			this.begin({
+				kind: "longName",
+				padding
+			}, size);
+			return;
+		}
+		const prefix = field(header, PREFIX_FIELD);
+		const name = this.longName ?? (prefix === "" ? field(header, NAME_FIELD) : `${prefix}/${field(header, NAME_FIELD)}`);
+		this.longName = void 0;
+		if ((type === "0" || type === "\0") && this.wanted(name)) this.begin({
+			kind: "data",
+			name,
+			padding
+		}, size);
+		else this.begin({ kind: "skip" }, size + padding);
+	}
+};
+function field(header, spec) {
+	const raw = header.subarray(spec.offset, spec.offset + spec.length);
+	const end = raw.indexOf(0);
+	return raw.subarray(0, end === -1 ? raw.length : end).toString("utf8");
+}
+/**
+* Reads the regular files of a tar stream one at a time. Entries for which `wanted` is false are skipped without being buffered, which matters for archives that mix small files with very large ones.
+* Entry data is held in memory, so one entry must fit in memory. GNU long names (`L`) are honoured; other extension headers (`K`, pax `x` and `g`) are skipped, and directories, links and devices are ignored.
+* @param source - The tar bytes, for example a file or standard input stream.
+* @param wanted - Chooses by name which entries are read.
+* @returns A generator of each wanted regular file.
+* @throws When the stream ends inside a header or an entry.
+*/
+async function* readTarFiles(source, wanted) {
+	const parser = new TarParser(wanted);
+	for await (const chunk of source) {
+		yield* parser.push(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+		if (parser.isEnded) return;
+	}
+	parser.finish();
+}
+// src/node/adsb-archive.ts
+/** First two bytes of a gzip stream. `readsb` history files carry a `.json` name but are usually gzip-compressed. */
+const GZIP_MAGIC = [31, 139];
+/** Matches the per-aircraft trace files of an `adsb.lol` `globe_history` archive, for example `./traces/3a/trace_full_3a1b2c.json`. */
+const TRACE_FILE = /(^|\/)trace_full_[0-9a-f~]+\.json$/;
+/**
+* Reads flight segments from a tar stream of `adsb.lol` `globe_history` traces, one aircraft at a time so memory holds a single trace and the segments kept.
+* A day is published as `.tar.aa` and `.tar.ab` parts that concatenate to one tar, so the two parts can be piped in one after the other.
+* @param source - The tar bytes.
+* @param options - Region filter and compression tolerance.
+* @returns Segments from every trace file in the archive.
+* @throws When a trace file is not valid JSON of the trace shape, naming the file.
+*/
+async function readAdsbArchiveSegments(source, options = {}) {
+	const segments = [];
+	for await (const file of readTarFiles(source, (name) => TRACE_FILE.test(name))) {
+		const text = (GZIP_MAGIC.every((byte, index) => file.data[index] === byte) ? gunzipSync(file.data) : file.data).toString("utf8");
+		let found;
+		try {
+			found = segmentsFromAdsbJson(JSON.parse(text), options);
+		} catch (error) {
+			throw new Error(`${file.name}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+		segments.push(...found);
+	}
+	return segments;
+}
+// src/node/wav-file.ts
+/**
+* Reads and decodes a WAV audio file from disk into mono `Float32Array` samples and sample rate.
+* @param filePath - Path to `.wav` file.
+* @returns Decoded mono audio samples and sample rate in Hz.
+*/
+function readWavFile(filePath) {
+	return decodeWavBytes(new Uint8Array(readFileSync(filePath)));
+}
+// cli/doppler.ts
+const PackageManifest = z.object({ version: z.string() });
+/** The package version, read from the package.json that sits one directory above both `cli/` and `dist-cli/`. */
+function getCliVersion() {
+	return PackageManifest.parse(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))).version;
+}
+/**
+* Parses `minLat,minLon,maxLat,maxLon`.
+* @param text - The option value.
+* @returns The box.
+* @throws When the value is not four numbers with the minimums below the maximums.
+*/
+function parseBoundingBox(text) {
+	const parts = (text ?? "").split(",").map(Number);
+	const [minLat, minLon, maxLat, maxLon] = parts;
+	if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part)) || minLat === void 0 || minLon === void 0 || maxLat === void 0 || maxLon === void 0 || minLat >= maxLat || minLon >= maxLon) throw new Error(`--bbox needs minLat,minLon,maxLat,maxLon with each minimum below its maximum, got ${text ?? "nothing"}`);
+	return {
+		minLat,
+		minLon,
+		maxLat,
+		maxLon
+	};
+}
+function formatCpaTime(cpaTimeSec) {
+	if (cpaTimeSec > 1e9) return (/* @__PURE__ */ new Date(cpaTimeSec * 1e3)).toLocaleTimeString();
+	const mins = Math.floor(cpaTimeSec / 60);
+	const secs = (cpaTimeSec % 60).toFixed(1);
+	return mins > 0 ? `${String(mins)}m ${secs}s` : `${secs}s`;
+}
+function printHelp() {
+	console.log(`
+doppler - Offline and real-time aircraft Doppler audio geolocation
+
+Usage:
+  doppler locate <audio.wav> [options]
+  doppler session <session.json> --add-audio <audio.wav>
+  doppler ingest --input <adsb.json|directory|-> --out <dataset.json> [--date <YYYY-MM-DD>] [--bbox <minLat,minLon,maxLat,maxLon>]
+
+Options:
+  --dataset <path>    Path to a custom DopplerDataset .json file (defaults to bundled dataset)
+  --date <YYYY-MM-DD> For ingest: date of raw traces that carry no timestamp
+  --bbox <a,b,c,d>    For ingest: keep segments touching minLat,minLon,maxLat,maxLon
+                      (--input - reads an adsb.lol globe_history tar from stdin)
+  --temp <celsius>    Ambient air temperature in Celsius (default 20.0)
+  --json              Output raw JSON results
+  --version, -v       Show version
+  --help, -h          Show help
+`);
+}
+async function run() {
+	const args = process.argv.slice(2);
+	if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+		printHelp();
+		return;
+	}
+	if (args.includes("-v") || args.includes("--version")) {
+		console.log(`doppler v${getCliVersion()}`);
+		return;
+	}
+	const command = args[0];
+	if (command === "locate") {
+		const audioPath = args[1];
+		if (audioPath === void 0 || audioPath.startsWith("--")) {
+			console.error("Error: specify an audio file path: doppler locate <file.wav>");
+			process.exit(1);
+		}
+		const datasetIdx = args.indexOf("--dataset");
+		const datasetPath = datasetIdx !== -1 ? args[datasetIdx + 1] : void 0;
+		const tempIdx = args.indexOf("--temp");
+		const ambientTemp = tempIdx !== -1 ? Number(args[tempIdx + 1]) : 20;
+		if (!Number.isFinite(ambientTemp)) {
+			console.error(`Error: --temp needs a number of degrees Celsius, got ${args[tempIdx + 1] ?? "nothing"}`);
+			process.exit(1);
+		}
+		const isJson = args.includes("--json");
+		const dataset = datasetPath !== void 0 ? loadDatasetFile(datasetPath) : BUNDLED_DATASET;
+		const { samples, sampleRateHz } = readWavFile(audioPath);
+		const decimated = decimateAudioStream(samples, sampleRateHz, 2e3);
+		const enf = detectEnfSignature(decimated.samples, decimated.sampleRateHz);
+		const observations = extractDopplerObservations(computeDopplerSpectrogram(decimated.samples, {
+			sampleRateHz: decimated.sampleRateHz,
+			startTimeSec: 0,
+			fftSize: 2048,
+			hopSamples: 500
+		}), {
+			episodeId: "cli_file",
+			minSnrDb: 5
+		});
+		const engine = new DopplerSessionEngine({
+			dataset,
+			ambientTempCelsius: ambientTemp,
+			constraints: enf.detected ? { enfNominalHz: enf.nominalHz === "50" ? "50" : "60" } : {}
+		});
+		engine.startEpisode(0);
+		for (const obs of observations) engine.ingestObservation(obs);
+		const session = engine.getSession();
+		const topHyp = session.hypotheses[0];
+		if (isJson) {
+			console.log(JSON.stringify(session, null, 2));
+			return;
+		}
+		console.log("\n--- Doppler Geolocation Results ---");
+		console.log(`Audio File:      ${audioPath} (${(samples.length / sampleRateHz).toFixed(1)}s @ ${String(sampleRateHz)}Hz)`);
+		console.log(`ENF Power Grid:  ${enf.detected ? `${enf.nominalHz} Hz (${enf.regionHint})` : "Not detected"}`);
+		console.log(`Flyovers Found:  ${String(observations.length)}`);
+		for (let i = 0; i < observations.length; i += 1) {
+			const o = observations[i];
+			if (o !== void 0) {
+				const timeLabel = formatCpaTime(o.cpaTimeSec);
+				console.log(`  [#${String(i + 1)}] CPA: ${timeLabel}, Base: ${o.kinematics.baseFreqHz.toFixed(1)}Hz, Speed: ${o.kinematics.inferredSpeedMps.toFixed(1)}m/s, Slant: ${o.kinematics.inferredSlantMeters.toFixed(0)}m, SNR: ${o.snrDb.toFixed(1)}dB`);
+			}
+		}
+		if (topHyp !== void 0) {
+			console.log("\nTop Hypothesis:");
+			console.log(`  Coordinates:   ${topHyp.lat.toFixed(5)}° N, ${topHyp.lon.toFixed(5)}° E (alt: ${topHyp.altMeters.toFixed(0)}m)`);
+			console.log(`  H3 Cell:       ${topHyp.h3Cell}`);
+			console.log(`  Date / Time:   ${topHyp.dateIso} ~${(/* @__PURE__ */ new Date(topHyp.estimatedStartEpochSec * 1e3)).toISOString()}`);
+			console.log(`  Probability:   ${(topHyp.probability * 100).toFixed(1)}% (Log-Posterior: ${topHyp.logPosterior.toFixed(2)})`);
+			console.log(`  95% Ellipse:   ${topHyp.ellipseSemiMajorMeters.toFixed(0)}m × ${topHyp.ellipseSemiMinorMeters.toFixed(0)}m (bearing ${topHyp.ellipseBearingDeg.toFixed(0)}°)`);
+			console.log(`  Matched Segs:  ${topHyp.matches.map((match) => match.segmentId).join(", ")}`);
+		} else console.log("\nNo matching flight trajectory found in dataset.");
+		return;
+	}
+	if (command === "session") {
+		const sessionPath = args[1];
+		const addIdx = args.indexOf("--add-audio");
+		const audioPath = addIdx !== -1 ? args[addIdx + 1] : void 0;
+		if (sessionPath === void 0 || audioPath === void 0) {
+			console.error("Usage: doppler session <session.json> --add-audio <file.wav>");
+			process.exit(1);
+		}
+		const sessionRaw = readFileSync(sessionPath, "utf8");
+		const initialSession = LocationSessionSchema.parse(JSON.parse(sessionRaw));
+		const { samples, sampleRateHz } = readWavFile(audioPath);
+		const decimated = decimateAudioStream(samples, sampleRateHz, 2e3);
+		const observations = extractDopplerObservations(computeDopplerSpectrogram(decimated.samples, {
+			sampleRateHz: decimated.sampleRateHz,
+			startTimeSec: 0,
+			fftSize: 2048,
+			hopSamples: 500
+		}), {
+			episodeId: `episode_${String(initialSession.episodes.length + 1)}`,
+			minSnrDb: 5
+		});
+		const engine = new DopplerSessionEngine({
+			initialSession,
+			dataset: BUNDLED_DATASET
+		});
+		const episode = engine.startEpisode(Math.floor(Date.now() / 1e3));
+		for (const obs of observations) engine.ingestObservation(obs);
+		engine.pauseEpisode(episode.id, Math.floor(Date.now() / 1e3));
+		const updated = engine.getSession();
+		writeFileSync(sessionPath, JSON.stringify(updated, null, 2), "utf8");
+		const top = updated.hypotheses[0];
+		console.log(`\nUpdated session ${sessionPath}:`);
+		console.log(`  Total Observations: ${String(updated.observations.length)}`);
+		if (top !== void 0) {
+			console.log(`  Current Estimate:   ${top.lat.toFixed(5)}° N, ${top.lon.toFixed(5)}° E`);
+			console.log(`  95% Confidence:     ${top.ellipseSemiMajorMeters.toFixed(0)}m × ${top.ellipseSemiMinorMeters.toFixed(0)}m`);
+		}
+		return;
+	}
+	if (command === "ingest") {
+		const inIdx = args.indexOf("--input");
+		const outIdx = args.indexOf("--out");
+		const inputPath = inIdx !== -1 ? args[inIdx + 1] : void 0;
+		const outputPath = outIdx !== -1 ? args[outIdx + 1] : void 0;
+		if (inputPath === void 0 || outputPath === void 0) {
+			console.error("Usage: doppler ingest --input <adsb.json|directory|-> --out <dataset.json> [--date <YYYY-MM-DD>] [--bbox <minLat,minLon,maxLat,maxLon>]");
+			process.exit(1);
+		}
+		const dateIdx = args.indexOf("--date");
+		const dateIso = dateIdx !== -1 ? args[dateIdx + 1] : void 0;
+		const bboxIdx = args.indexOf("--bbox");
+		const bbox = bboxIdx !== -1 ? parseBoundingBox(args[bboxIdx + 1]) : void 0;
+		const options = {
+			...bbox === void 0 ? {} : { bbox },
+			...dateIso === void 0 ? {} : { dateIso }
+		};
+		const segments = inputPath === "-" ? await readAdsbArchiveSegments(process.stdin, options) : readAdsbSegments(inputPath, options);
+		saveDatasetBundle(outputPath, segments);
+		console.log(`Saved dataset bundle with ${String(segments.length)} segments to ${outputPath}`);
+		return;
+	}
+	console.error(`Unknown command: ${command ?? "none"}`);
+	printHelp();
+	process.exit(1);
+}
+await run();
+export {};