gps-plus-slam-app-framework 1.0.0 → 1.0.7

package/dist/state/tracking-quality.js

@@ -0,0 +1,723 @@
+import { selectLastSensorOrientation, selectLastValidPose, selectTrackingPhase } from "./tracking-slice.js";
+import { selectAlignmentMatrix, selectGpsPositions, selectOdometryPositions, selectZeroReference } from "./app-selectors.js";
+import { calcGpsCoords, distanceInMeters } from "gps-plus-slam-js";
+import { createListenerMiddleware, createSlice } from "@reduxjs/toolkit";
+import { mat4, quat, vec3 } from "gl-matrix";
+//#region ../src/state/tracking-quality.ts
+const DEFAULT_TRACKING_QUALITY_OPTIONS = {
+	matrixHistorySize: 5,
+	residualWindowSize: 16,
+	degradedThreshold: .5,
+	gpsAccuracyWindowSize: 30,
+	coverageWalkedDistanceM: 15,
+	coverageDirectionSpreadDeg: 90,
+	convergenceRotationWarnDeg: 6,
+	convergenceTranslationWarnM: 2,
+	compassWarnDeg: 15,
+	compassFailDeg: 35,
+	warmupMinObservations: 10,
+	warmupMinCoverage: .5,
+	residualConfidenceTargetM: 3,
+	gpsAccuracyFloorM: 1,
+	firstAgreementMinStreak: 3,
+	degradedHoldoff: 3,
+	convergenceEmaAlpha: .3
+};
+const initialState = {
+	recentAlignments: [],
+	firstAgreementObservationIndex: null,
+	report: null,
+	degradedConsecutiveCount: 0,
+	smoothedConvergence: null
+};
+function clamp01(x) {
+	if (!Number.isFinite(x)) return 0;
+	if (x < 0) return 0;
+	if (x > 1) return 1;
+	return x;
+}
+/**
+* §4.8b (Finding 4) — exponential moving-average blend. When `prev` is
+* `null` the filter has no history yet and we seed it to `raw`.
+* `alpha = 1` disables smoothing (returns `raw`); `alpha = 0` freezes
+* the filter at `prev`. Non-finite `alpha` is treated as 1 (no
+* smoothing) to fail safe — never silently swallow a valid raw signal.
+*/
+function emaBlend(prev, raw, alpha) {
+	if (prev === null) return raw;
+	return prev + (Number.isFinite(alpha) ? alpha : 1) * (raw - prev);
+}
+function wrapToHalfCircle(deg) {
+	let d = (deg + 180) % 360 - 180;
+	if (d < -180) d += 360;
+	return d;
+}
+function bearingDeg(north, east) {
+	let deg = Math.atan2(east, north) * 180 / Math.PI;
+	if (deg < 0) deg += 360;
+	return deg;
+}
+function median(values) {
+	if (values.length === 0) return 0;
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/**
+* Linear ramp: `value ≤ low` → 1, `value ≥ high` → 0, linear between.
+* Used by sub-scores whose underlying physical quantity grows as
+* quality drops (e.g. residuals, heading delta).
+*/
+function rampDown(value, low, high) {
+	if (!Number.isFinite(value)) return 0;
+	if (high <= low) return value <= low ? 1 : 0;
+	if (value <= low) return 1;
+	if (value >= high) return 0;
+	return 1 - (value - low) / (high - low);
+}
+/**
+* Linear ramp: `value ≤ low` → 0, `value ≥ high` → 1, linear between.
+* Used by sub-scores whose underlying quantity grows as quality
+* improves (e.g. walked distance, direction spread).
+*/
+function rampUp(value, low, high) {
+	if (!Number.isFinite(value)) return 0;
+	if (high <= low) return value >= high ? 1 : 0;
+	if (value <= low) return 0;
+	if (value >= high) return 1;
+	return (value - low) / (high - low);
+}
+/**
+* §4.1 matrix-history convergence over the buffered snapshots.
+*
+* Reuses the same kernel idea as `computeStabilityDelta` from the
+* Investigation helpers (rotation + translation delta between two 4×4
+* matrices). With 0 or 1 snapshot we return score 0 — convergence is
+* undefined until at least one consecutive pair exists.
+*
+* Finding 6 (2026-05-23 field test): the per-pair `max` aggregation was
+* replaced with a **sum** across the window. `max` is a burst detector
+* — dominated by one bad pair, blind to slow drift; `sum` answers
+* "how much alignment motion accumulated over the window?" and exposes
+* slow creeping drift in user-readable units (°, m). The HUD now shows
+* the raw sums (`ΣΔrot:`, `ΣΔpos:`) alongside the EMA-smoothed `Conv:`
+* sub-score (Finding 4) so the user can debug an unstable reading.
+*/
+function computeConvergence(snapshots, options = {}) {
+	const rotWarn = options.rotationWarnDeg ?? DEFAULT_TRACKING_QUALITY_OPTIONS.convergenceRotationWarnDeg;
+	const transWarn = options.translationWarnM ?? DEFAULT_TRACKING_QUALITY_OPTIONS.convergenceTranslationWarnM;
+	const rotFail = rotWarn * 4;
+	const transFail = transWarn * 4;
+	if (snapshots.length < 2) return {
+		score: 0,
+		recentSumRotationDeltaDeg: 0,
+		recentSumTranslationDeltaM: 0,
+		pairCount: 0
+	};
+	let sumRotDeg = 0;
+	let sumTransM = 0;
+	let pairCount = 0;
+	for (let i = 1; i < snapshots.length; i++) {
+		const { rotationDeltaDeg, translationDeltaM } = matrixDelta(snapshots[i - 1].matrix, snapshots[i].matrix);
+		sumRotDeg += Math.abs(rotationDeltaDeg);
+		sumTransM += Math.abs(translationDeltaM);
+		pairCount += 1;
+	}
+	const rotScore = rampDown(sumRotDeg, rotWarn, rotFail);
+	const transScore = rampDown(sumTransM, transWarn, transFail);
+	return {
+		score: Math.min(rotScore, transScore),
+		recentSumRotationDeltaDeg: sumRotDeg,
+		recentSumTranslationDeltaM: sumTransM,
+		pairCount
+	};
+}
+/**
+* Rotation and translation delta between two 4×4 alignment matrices in
+* the column-major layout that gl-matrix and the framework use.
+*
+* Rotation: extract the orientation quaternion with `mat4.getRotation`
+* and compute the relative angle via `quat.getAngle` (degrees).
+* Translation: extract the origin column with `mat4.getTranslation` and
+* compute the Euclidean distance.
+*
+* This is the **single shared kernel** for the AppFramework reporter and
+* the Investigation harness (see §11 (a) of the tracking-quality plan).
+* `GpsPlusSlamJs_Investigation/src/investigation-helpers.ts` re-exports
+* `computeStabilityDelta` as a thin wrapper around this function so the
+* §6.1 corpus sweep and the runtime convergence score share one numeric
+* definition.
+*/
+function matrixDelta(prev, curr) {
+	if (prev.length !== 16 || curr.length !== 16) return {
+		rotationDeltaDeg: 0,
+		translationDeltaM: 0
+	};
+	const prevMat = prev;
+	const currMat = curr;
+	const prevQuat = quat.create();
+	const currQuat = quat.create();
+	mat4.getRotation(prevQuat, prevMat);
+	mat4.getRotation(currQuat, currMat);
+	quat.normalize(prevQuat, prevQuat);
+	quat.normalize(currQuat, currQuat);
+	const angleRad = quat.getAngle(prevQuat, currQuat);
+	const rotationDeltaDeg = Number.isNaN(angleRad) ? 0 : angleRad * 180 / Math.PI;
+	const prevT = vec3.create();
+	const currT = vec3.create();
+	mat4.getTranslation(prevT, prevMat);
+	mat4.getTranslation(currT, currMat);
+	return {
+		rotationDeltaDeg,
+		translationDeltaM: vec3.distance(prevT, currT)
+	};
+}
+/**
+* §4.2 — Median residual between the last `K` GPS observations and the
+* positions you would have predicted by transforming the matching
+* odometry positions through the current alignment matrix.
+*
+* Returns `score = 0`, `medianResidualM = 0` when we have fewer than
+* 2 paired observations or when the alignment matrix / zero ref is
+* not yet set.
+*/
+function computeResidualConsensus(alignmentMatrix, gpsPositions, odometryPositions, zeroRef, options = {
+	residualWindowSize: DEFAULT_TRACKING_QUALITY_OPTIONS.residualWindowSize,
+	residualConfidenceTargetM: DEFAULT_TRACKING_QUALITY_OPTIONS.residualConfidenceTargetM,
+	gpsAccuracyFloorM: DEFAULT_TRACKING_QUALITY_OPTIONS.gpsAccuracyFloorM
+}) {
+	if (!alignmentMatrix || !zeroRef) return {
+		score: 0,
+		medianResidualM: 0,
+		count: 0
+	};
+	const n = Math.min(gpsPositions.length, odometryPositions.length);
+	if (n < 2) return {
+		score: 0,
+		medianResidualM: 0,
+		count: 0
+	};
+	const start = Math.max(0, n - options.residualWindowSize);
+	const glMat = alignmentMatrix;
+	const tmp = vec3.create();
+	const normalised = [];
+	let rawResidualSum = 0;
+	let rawResidualCount = 0;
+	for (let i = start; i < n; i++) {
+		const odom = odometryPositions[i];
+		const gps = gpsPositions[i];
+		vec3.set(tmp, odom[0], odom[1], odom[2]);
+		vec3.transformMat4(tmp, tmp, glMat);
+		const meters = distanceInMeters(calcGpsCoords(zeroRef, tmp), {
+			lat: gps.latitude,
+			lon: gps.longitude
+		});
+		if (!Number.isFinite(meters)) continue;
+		rawResidualSum += meters;
+		rawResidualCount += 1;
+		const acc = Math.max(options.gpsAccuracyFloorM, gps.latLongAccuracy ?? options.gpsAccuracyFloorM);
+		normalised.push(meters / acc);
+	}
+	if (normalised.length < 2) return {
+		score: 0,
+		medianResidualM: rawResidualCount > 0 ? rawResidualSum / rawResidualCount : 0,
+		count: normalised.length
+	};
+	const medianNorm = median(normalised);
+	const medianResidualM = rawResidualSum / rawResidualCount;
+	return {
+		score: clamp01(1 / (1 + medianNorm / options.residualConfidenceTargetM)),
+		medianResidualM,
+		count: normalised.length
+	};
+}
+/**
+* §4.4 — Median `latLongAccuracy` of the last `K` GPS points, with
+* an "accurate-fix count" diagnostic. Cheap, always available.
+*
+* `score` ramps from 1.0 at median ≤ 3 m to 0.0 at median ≥ 25 m
+* (linear), matching the plan's "≤ 5 m is good" heuristic with a
+* generous fail tail.
+*/
+function computeGpsAccuracy(gpsPositions, options = {}) {
+	const windowSize = options.windowSize ?? DEFAULT_TRACKING_QUALITY_OPTIONS.gpsAccuracyWindowSize;
+	const goodMedianM = options.goodMedianM ?? 3;
+	const badMedianM = options.badMedianM ?? 25;
+	if (gpsPositions.length === 0) return {
+		score: 0,
+		medianM: 0,
+		countAccurate: 0,
+		countTotal: 0
+	};
+	const start = Math.max(0, gpsPositions.length - windowSize);
+	const accs = [];
+	let countAccurate = 0;
+	for (let i = start; i < gpsPositions.length; i++) {
+		const acc = gpsPositions[i].latLongAccuracy;
+		if (typeof acc === "number" && Number.isFinite(acc)) {
+			accs.push(acc);
+			if (acc <= 5) countAccurate += 1;
+		}
+	}
+	if (accs.length === 0) return {
+		score: 0,
+		medianM: 0,
+		countAccurate: 0,
+		countTotal: gpsPositions.length - start
+	};
+	const medianM = median(accs);
+	return {
+		score: rampDown(medianM, goodMedianM, badMedianM),
+		medianM,
+		countAccurate,
+		countTotal: accs.length
+	};
+}
+/**
+* §4.5 — Coverage = how far the user has walked AND how diverse the
+* walking direction has been. Both required: a long but unidirectional
+* walk leaves the rotation about the walking axis under-determined.
+*/
+function computeCoverage(odometryPositions, options = {}) {
+	const wThr = options.walkedDistanceM ?? DEFAULT_TRACKING_QUALITY_OPTIONS.coverageWalkedDistanceM;
+	const dThr = options.directionSpreadDeg ?? DEFAULT_TRACKING_QUALITY_OPTIONS.coverageDirectionSpreadDeg;
+	if (odometryPositions.length < 2) return {
+		score: 0,
+		walkedDistanceM: 0,
+		directionSpreadDeg: 0
+	};
+	let walked = 0;
+	const bearings = [];
+	for (let i = 1; i < odometryPositions.length; i++) {
+		const a = odometryPositions[i - 1];
+		const b = odometryPositions[i];
+		const dN = b[0] - a[0];
+		const dE = b[2] - a[2];
+		const segLen = Math.hypot(dN, dE);
+		if (!Number.isFinite(segLen) || segLen < 1e-4) continue;
+		walked += segLen;
+		bearings.push(bearingDeg(dN, dE));
+	}
+	let spread = 0;
+	if (bearings.length >= 2) {
+		const sorted = [...bearings].sort((a, b) => a - b);
+		let maxGap = 0;
+		for (let i = 1; i < sorted.length; i++) {
+			const gap = sorted[i] - sorted[i - 1];
+			if (gap > maxGap) maxGap = gap;
+		}
+		const wrapGap = 360 - sorted[sorted.length - 1] + sorted[0];
+		if (wrapGap > maxGap) maxGap = wrapGap;
+		spread = Math.max(0, 360 - maxGap);
+	}
+	const walkScore = rampUp(walked, wThr * .25, wThr);
+	const spreadScore = rampUp(spread, dThr * .25, dThr);
+	return {
+		score: Math.min(walkScore, spreadScore),
+		walkedDistanceM: walked,
+		directionSpreadDeg: spread
+	};
+}
+/**
+* §4.3 — Compare the alignment matrix's mapping of AR-forward to ENU
+* against the device compass heading. Returns `score = null` whenever
+* the sensor's `absolute !== true` so the aggregate excludes the
+* sub-score (per Q2 in the plan).
+*
+* AR-forward in our `ARPose` convention is `(0, 0, -1)` (right-handed,
+* Y-up). We rotate that by the alignment's 3×3 rotation, take its
+* North/East components, and compare against the compass alpha.
+*/
+function computeCompassAgreement(alignmentMatrix, sensorOrientation, arPose, options = {}) {
+	const warn = options.warnDeg ?? DEFAULT_TRACKING_QUALITY_OPTIONS.compassWarnDeg;
+	const fail = options.failDeg ?? DEFAULT_TRACKING_QUALITY_OPTIONS.compassFailDeg;
+	if (!alignmentMatrix || !sensorOrientation || !arPose) return {
+		score: null,
+		headingDeltaDeg: null
+	};
+	if (sensorOrientation.absolute !== true) return {
+		score: null,
+		headingDeltaDeg: null
+	};
+	const q = arPose.orientation;
+	const fx = 0;
+	const fy = 0;
+	const fz = -1;
+	const x = q.x, y = q.y, z = q.z, w = q.w;
+	const tx = 2 * (y * fz - z * fy);
+	const ty = 2 * (z * fx - x * fz);
+	const tz = 2 * (x * fy - y * fx);
+	const arForwardLocal = [
+		fx + w * tx + (y * tz - z * ty),
+		fy + w * ty + (z * tx - x * tz),
+		fz + w * tz + (x * ty - y * tx)
+	];
+	const m = alignmentMatrix;
+	const enuN = m[0] * arForwardLocal[0] + m[4] * arForwardLocal[1] + m[8] * arForwardLocal[2];
+	m[1] * arForwardLocal[0] + m[5] * arForwardLocal[1] + m[9] * arForwardLocal[2];
+	const enuE = m[2] * arForwardLocal[0] + m[6] * arForwardLocal[1] + m[10] * arForwardLocal[2];
+	if (Math.hypot(enuN, enuE) < 1e-6) return {
+		score: null,
+		headingDeltaDeg: null
+	};
+	const alignmentHeadingDeg = bearingDeg(enuN, enuE);
+	const compassHeadingDeg = sensorOrientation.alpha;
+	const delta = Math.abs(wrapToHalfCircle(alignmentHeadingDeg - compassHeadingDeg));
+	return {
+		score: rampDown(delta, warn, fail),
+		headingDeltaDeg: delta
+	};
+}
+/**
+* §4.6 — Maximum lateral distance between raw GPS positions and the
+* positions you would predict by transforming the matching odometry
+* positions through the current alignment. Diagnostic only — never
+* feeds the aggregate confidence per the plan.
+*/
+function computeGpsVsFusedDivergence(alignmentMatrix, gpsPositions, odometryPositions, zeroRef, windowSize = 16) {
+	if (!alignmentMatrix || !zeroRef) return 0;
+	const n = Math.min(gpsPositions.length, odometryPositions.length);
+	if (n < 2) return 0;
+	const start = Math.max(0, n - windowSize);
+	const glMat = alignmentMatrix;
+	const tmp = vec3.create();
+	let maxDiv = 0;
+	for (let i = start; i < n; i++) {
+		const odom = odometryPositions[i];
+		vec3.set(tmp, odom[0], odom[1], odom[2]);
+		vec3.transformMat4(tmp, tmp, glMat);
+		const d = distanceInMeters(calcGpsCoords(zeroRef, tmp), {
+			lat: gpsPositions[i].latitude,
+			lon: gpsPositions[i].longitude
+		});
+		if (Number.isFinite(d) && d > maxDiv) maxDiv = d;
+	}
+	return maxDiv;
+}
+const trackingQualitySlice = createSlice({
+	name: "trackingQuality",
+	initialState,
+	reducers: {
+		/**
+		* Push a new alignment snapshot. Idempotent: callers must only
+		* dispatch when the matrix has actually changed (the listener
+		* middleware enforces this).
+		*/
+		snapshotPushed(state, action) {
+			state.recentAlignments.push(action.payload);
+		},
+		/**
+		* Drop oldest snapshots until `length ≤ size`. Separate action so
+		* the buffer cap can be applied after `snapshotPushed` without
+		* the reducer needing to know the option value.
+		*/
+		snapshotsTrimmed(state, action) {
+			const size = Math.max(1, action.payload.size | 0);
+			while (state.recentAlignments.length > size) state.recentAlignments.shift();
+		},
+		reportUpdated(state, action) {
+			state.report = action.payload;
+		},
+		firstAgreementReached(state, action) {
+			state.firstAgreementObservationIndex = action.payload;
+		},
+		/** §4.8 — update the hysteresis counter for ok → degraded holdoff. */
+		degradedCountUpdated(state, action) {
+			state.degradedConsecutiveCount = action.payload;
+		},
+		/**
+		* §4.8b (Finding 4) — persist the latest EMA-smoothed convergence so
+		* the next aggregator pass can blend against it. `null` resets the
+		* filter (next pass seeds from raw).
+		*/
+		smoothedConvergenceUpdated(state, action) {
+			state.smoothedConvergence = action.payload;
+		},
+		/** Full reset — used on new session start / tracking reset. */
+		resetTrackingQuality() {
+			return initialState;
+		}
+	}
+});
+const { snapshotPushed, snapshotsTrimmed, reportUpdated, firstAgreementReached, degradedCountUpdated, resetTrackingQuality } = trackingQualitySlice.actions;
+const { smoothedConvergenceUpdated } = trackingQualitySlice.actions;
+const trackingQualityReducer = trackingQualitySlice.reducer;
+function selectTrackingQuality(state) {
+	return state.trackingQuality?.report ?? null;
+}
+function selectRecentAlignments(state) {
+	return state.trackingQuality?.recentAlignments ?? EMPTY_SNAPSHOTS;
+}
+function selectFirstAgreementObservationIndex(state) {
+	return state.trackingQuality?.firstAgreementObservationIndex ?? null;
+}
+const EMPTY_SNAPSHOTS = Object.freeze([]);
+/**
+* Pure function — produces a {@link TrackingQualityReport} from a root
+* state and options. The Investigation harness imports this directly to
+* sweep `(N, K)` without going through the Redux listener middleware.
+*
+* The report's `state` enum follows §5 of the plan:
+*   - `ar-lost` whenever `tracking.phase !== 'tracking'`
+*   - `warming-up` until `coverage ≥ warmupMinCoverage` AND
+*     `observationsSeen ≥ warmupMinObservations`
+*   - then `ok` / `degraded` from `min(subScores)` vs.
+*     `degradedThreshold`.
+*/
+function computeTrackingQualityReport(rootState, options = {}) {
+	const opts = {
+		...DEFAULT_TRACKING_QUALITY_OPTIONS,
+		...options
+	};
+	const alignmentMatrix = selectAlignmentMatrix(rootState);
+	const gpsPositions = selectGpsPositions(rootState);
+	const odometryPositions = selectOdometryPositions(rootState);
+	const zeroRef = selectZeroReference(rootState);
+	const trackingPhase = selectTrackingPhase(rootState);
+	const sensorOrientation = selectLastSensorOrientation(rootState);
+	const lastPose = selectLastValidPose(rootState);
+	const snapshots = selectRecentAlignments(rootState);
+	const firstAgreementIdx = selectFirstAgreementObservationIndex(rootState);
+	const coverage = computeCoverage(odometryPositions, {
+		walkedDistanceM: opts.coverageWalkedDistanceM,
+		directionSpreadDeg: opts.coverageDirectionSpreadDeg
+	});
+	const gpsAccuracy = computeGpsAccuracy(gpsPositions, { windowSize: opts.gpsAccuracyWindowSize });
+	const residual = computeResidualConsensus(alignmentMatrix, gpsPositions, odometryPositions, zeroRef, {
+		residualWindowSize: opts.residualWindowSize,
+		residualConfidenceTargetM: opts.residualConfidenceTargetM,
+		gpsAccuracyFloorM: opts.gpsAccuracyFloorM
+	});
+	const convergence = computeConvergence(snapshots, {
+		rotationWarnDeg: opts.convergenceRotationWarnDeg,
+		translationWarnM: opts.convergenceTranslationWarnM
+	});
+	const compass = computeCompassAgreement(alignmentMatrix, sensorOrientation, lastPose, {
+		warnDeg: opts.compassWarnDeg,
+		failDeg: opts.compassFailDeg
+	});
+	const gpsVsFusedMaxDivergenceM = computeGpsVsFusedDivergence(alignmentMatrix, gpsPositions, odometryPositions, zeroRef);
+	const subScores = {
+		convergence: clamp01(emaBlend(rootState.trackingQuality?.smoothedConvergence ?? null, convergence.score, opts.convergenceEmaAlpha)),
+		residualConsensus: clamp01(residual.score),
+		compassAgreement: compass.score === null ? null : clamp01(compass.score),
+		gpsAccuracy: clamp01(gpsAccuracy.score),
+		coverage: clamp01(coverage.score)
+	};
+	const aggregateInputs = [
+		subScores.convergence,
+		subScores.residualConsensus,
+		subScores.gpsAccuracy,
+		subScores.coverage
+	];
+	if (subScores.compassAgreement !== null) aggregateInputs.push(subScores.compassAgreement);
+	const confidence = clamp01(Math.min(...aggregateInputs));
+	const observationsSeen = gpsPositions.length;
+	let state;
+	if (trackingPhase !== "tracking") state = "ar-lost";
+	else if (subScores.coverage < opts.warmupMinCoverage || observationsSeen < opts.warmupMinObservations) state = "warming-up";
+	else if (confidence < opts.degradedThreshold) state = "degraded";
+	else state = "ok";
+	return {
+		state,
+		confidence: state === "ar-lost" ? 0 : confidence,
+		subScores,
+		diagnostics: {
+			recentSumRotationDeltaDeg: convergence.recentSumRotationDeltaDeg,
+			recentSumTranslationDeltaM: convergence.recentSumTranslationDeltaM,
+			medianResidualM: residual.medianResidualM,
+			medianRecentGpsAccuracyM: gpsAccuracy.medianM,
+			walkedDistanceM: coverage.walkedDistanceM,
+			directionSpreadDeg: coverage.directionSpreadDeg,
+			headingDeltaDeg: compass.headingDeltaDeg,
+			compassDriftDetected: firstAgreementIdx !== null && compass.headingDeltaDeg !== null && compass.headingDeltaDeg > opts.compassWarnDeg,
+			observationsSeen,
+			gpsVsFusedMaxDivergenceM
+		}
+	};
+}
+/**
+* Per-field tolerances for the {@link reportsEqual} dispatch gate.
+*
+* Why this exists: `tracking/poseReceived` fires on *every* XR frame
+* (30–60 fps). The §4.3 compass cross-check consumes the live AR pose
+* and sensor heading, so `subScores.compassAgreement` and
+* `diagnostics.headingDeltaDeg` (and, when compass is the minimum,
+* `confidence`) jitter by imperceptible floating-point amounts on a
+* held-still device. With a strict `!==` comparison every such frame
+* produced a fresh `reportUpdated` dispatch → high Redux churn and a
+* HUD re-render at frame rate. The tolerances below quantise those
+* sub-perceptual changes so the gate only fires when the user-visible
+* quality actually moved.
+*
+* The gate compares the freshly computed report against the *last
+* dispatched* report (the stored `prev`), not against the previous
+* frame, so slow real drift cannot accumulate indefinitely: once it
+* crosses a tolerance a dispatch fires and re-baselines. Tolerances are
+* chosen below the smallest user-meaningful step in the HUD:
+*  - scores/confidence live in 0..1 → 1e-3 (0.1 %).
+*  - angle diagnostics are shown in whole/tenths of a degree → 0.01°.
+*  - metre diagnostics are shown in centimetres at best → 1 mm.
+*/
+const REPORT_SCORE_EPSILON = .001;
+const REPORT_ANGLE_EPSILON_DEG = .01;
+const REPORT_METRE_EPSILON_M = .001;
+/**
+* Tolerant scalar comparison that treats `null` as a distinct value
+* (both `null` ⇒ equal; exactly one `null` ⇒ different) and otherwise
+* compares with an absolute epsilon. Non-finite values are compared with
+* {@link Object.is}, so a genuine finite↔NaN/Infinity transition still
+* fires a dispatch, but a *persistently* NaN diagnostic (the only
+* unguarded path is a NaN compass `alpha` leaking into
+* `diagnostics.headingDeltaDeg`) does NOT churn the gate every frame —
+* `Object.is(NaN, NaN)` is `true` whereas `NaN === NaN` is `false`.
+*/
+function nearlyEqual(a, b, eps) {
+	if (a === null || b === null) return a === b;
+	if (!Number.isFinite(a) || !Number.isFinite(b)) return Object.is(a, b);
+	return Math.abs(a - b) <= eps;
+}
+/**
+* Deep-equal that only inspects the public shape of a
+* {@link TrackingQualityReport}. Cheaper than a generic deep-equal
+* because it knows the schema; gates `reportUpdated` dispatches so
+* subscribers wake up exactly when the user-visible quality changes.
+*
+* Float fields use the per-field tolerances above
+* ({@link REPORT_SCORE_EPSILON} et al.) so imperceptible per-frame
+* compass jitter does not churn the store — see the constants' doc
+* comment for the rationale.
+*/
+function reportsEqual(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	if (a.state !== b.state) return false;
+	if (!nearlyEqual(a.confidence, b.confidence, REPORT_SCORE_EPSILON)) return false;
+	const sa = a.subScores;
+	const sb = b.subScores;
+	if (!nearlyEqual(sa.convergence, sb.convergence, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.residualConsensus, sb.residualConsensus, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.compassAgreement, sb.compassAgreement, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.gpsAccuracy, sb.gpsAccuracy, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.coverage, sb.coverage, REPORT_SCORE_EPSILON)) return false;
+	const da = a.diagnostics;
+	const db = b.diagnostics;
+	return da.compassDriftDetected === db.compassDriftDetected && da.observationsSeen === db.observationsSeen && nearlyEqual(da.recentSumRotationDeltaDeg, db.recentSumRotationDeltaDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.directionSpreadDeg, db.directionSpreadDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.headingDeltaDeg, db.headingDeltaDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.recentSumTranslationDeltaM, db.recentSumTranslationDeltaM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.medianResidualM, db.medianResidualM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.medianRecentGpsAccuracyM, db.medianRecentGpsAccuracyM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.walkedDistanceM, db.walkedDistanceM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.gpsVsFusedMaxDivergenceM, db.gpsVsFusedMaxDivergenceM, REPORT_METRE_EPSILON_M);
+}
+function matricesNearlyEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (Math.abs(a[i] - b[i]) > 1e-9) return false;
+	return true;
+}
+/**
+* Action types the listener reacts to. Module-private: consumed only by the
+* listener predicate and middleware below. The strings are the canonical
+* RTK auto-generated action types.
+*/
+const TRACKING_QUALITY_INPUT_ACTIONS = {
+	gpsRecorded: "gpsData/recordGpsEvent",
+	setZeroPos: "gpsData/setZeroPos",
+	poseReceived: "tracking/poseReceived",
+	poseLost: "tracking/poseLost",
+	resetTracking: "tracking/resetTracking",
+	startSession: "recording/startSession"
+};
+function inputActionPredicate(action) {
+	switch (action.type) {
+		case TRACKING_QUALITY_INPUT_ACTIONS.gpsRecorded:
+		case TRACKING_QUALITY_INPUT_ACTIONS.setZeroPos:
+		case TRACKING_QUALITY_INPUT_ACTIONS.poseReceived:
+		case TRACKING_QUALITY_INPUT_ACTIONS.poseLost:
+		case TRACKING_QUALITY_INPUT_ACTIONS.resetTracking:
+		case TRACKING_QUALITY_INPUT_ACTIONS.startSession: return true;
+		default: return false;
+	}
+}
+/**
+* Build the listener middleware that drives the `trackingQuality`
+* slice. Register the returned middleware in `createSlamAppStore`.
+*
+* Behaviour:
+*  - On `gpsData/recordGpsEvent` and `gpsData/setZeroPos`: if the
+*    alignment matrix changed, dispatch `snapshotPushed` +
+*    `snapshotsTrimmed`. Then recompute the report and dispatch
+*    `reportUpdated` if it changed.
+*  - On `recording/startSession` and `tracking/resetTracking`:
+*    dispatch `resetTrackingQuality` and recompute the report.
+*  - On `tracking/poseReceived` and `tracking/poseLost`: only
+*    recompute the report (no buffer change).
+*  - All dispatches are idempotency-gated so quiet motion does not
+*    churn the store.
+*/
+function createTrackingQualityListenerMiddleware(options = {}) {
+	const opts = {
+		...DEFAULT_TRACKING_QUALITY_OPTIONS,
+		...options
+	};
+	let compassStreak = 0;
+	const listenerMiddleware = createListenerMiddleware();
+	listenerMiddleware.startListening({
+		predicate: (action) => inputActionPredicate(action),
+		effect: (action, api) => {
+			const state = api.getState();
+			if (action.type === TRACKING_QUALITY_INPUT_ACTIONS.startSession || action.type === TRACKING_QUALITY_INPUT_ACTIONS.resetTracking) {
+				compassStreak = 0;
+				const tq = state.trackingQuality;
+				if (tq && (tq.recentAlignments.length > 0 || tq.firstAgreementObservationIndex !== null || tq.report !== null || tq.degradedConsecutiveCount > 0)) api.dispatch(resetTrackingQuality());
+				return;
+			}
+			if (action.type === TRACKING_QUALITY_INPUT_ACTIONS.gpsRecorded || action.type === TRACKING_QUALITY_INPUT_ACTIONS.setZeroPos) {
+				const alignment = selectAlignmentMatrix(state);
+				if (alignment) {
+					const buf = state.trackingQuality?.recentAlignments ?? [];
+					const newMatrix = alignment;
+					const obsIndex = selectGpsPositions(state).length;
+					const last = buf.length > 0 ? buf[buf.length - 1] : null;
+					if (!last || !matricesNearlyEqual(last.matrix, newMatrix)) {
+						api.dispatch(snapshotPushed({
+							observationIndex: obsIndex,
+							matrix: [...newMatrix]
+						}));
+						api.dispatch(snapshotsTrimmed({ size: opts.matrixHistorySize }));
+					}
+				}
+			}
+			const midState = api.getState();
+			const midTq = midState.trackingQuality;
+			if (midTq && midTq.firstAgreementObservationIndex === null) {
+				const snapshots = selectRecentAlignments(midState);
+				if (snapshots.length >= 2) {
+					const conv = computeConvergence(snapshots, {
+						rotationWarnDeg: opts.convergenceRotationWarnDeg,
+						translationWarnM: opts.convergenceTranslationWarnM
+					});
+					const sensorOr = selectLastSensorOrientation(midState);
+					const pose = selectLastValidPose(midState);
+					const compass = computeCompassAgreement(selectAlignmentMatrix(midState), sensorOr, pose, {
+						warnDeg: opts.compassWarnDeg,
+						failDeg: opts.compassFailDeg
+					});
+					if (conv.score >= .7 && compass.headingDeltaDeg !== null && compass.headingDeltaDeg <= opts.compassWarnDeg) {
+						compassStreak += 1;
+						if (compassStreak >= opts.firstAgreementMinStreak) {
+							const obsCount = selectGpsPositions(midState).length;
+							api.dispatch(firstAgreementReached(obsCount));
+						}
+					} else compassStreak = 0;
+				}
+			}
+			const next = api.getState();
+			const report = computeTrackingQualityReport(next, opts);
+			const prev = next.trackingQuality?.report ?? null;
+			const tqNext = next.trackingQuality;
+			let dcc = tqNext?.degradedConsecutiveCount ?? 0;
+			if (report.state === "degraded") {
+				dcc += 1;
+				if (prev?.state === "ok" && dcc < opts.degradedHoldoff) report.state = "ok";
+			} else dcc = 0;
+			if (dcc !== (tqNext?.degradedConsecutiveCount ?? 0)) api.dispatch(degradedCountUpdated(dcc));
+			const newSmoothed = report.subScores.convergence;
+			if (newSmoothed !== (tqNext?.smoothedConvergence ?? null)) api.dispatch(smoothedConvergenceUpdated(newSmoothed));
+			if (!reportsEqual(prev, report)) api.dispatch(reportUpdated(report));
+		}
+	});
+	return listenerMiddleware.middleware;
+}
+//#endregion
+export { DEFAULT_TRACKING_QUALITY_OPTIONS, computeCompassAgreement, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeResidualConsensus, computeTrackingQualityReport, createTrackingQualityListenerMiddleware, degradedCountUpdated, firstAgreementReached, matrixDelta, reportUpdated, resetTrackingQuality, selectFirstAgreementObservationIndex, selectRecentAlignments, selectTrackingQuality, snapshotPushed, snapshotsTrimmed, trackingQualityReducer };