[AZ-918] [AZ-919] [AZ-920] [AZ-921] [AZ-922] VIO/ESKF baseline fixes

Derkachi e2e Tier-2 divergence had three stacked root causes; this
commit ships fixes for all three plus the IMU prerequisite they
depend on, plus a baseline cheirality gate for cv2.recoverPose.

AZ-918  MAVLink IMU adapters now convert raw mG/mrad-s + FRD body to
        SI m/s^2 + rad/s + FLU body via helpers.imu_units. Without
        this the ESKF receives values ~1000x too small with wrong-
        sign Y/Z and cannot function at all.

AZ-919  Composition root wires EskfNominalAltitudeProvider into the
        KLT/RANSAC strategy via the AZ-331 factory introspect path;
        OKVIS2 and VINS-Mono are unaffected.

AZ-920  KLT/RANSAC recovers metric translation via Ground Sampling
        Distance when AGL is available; otherwise falls through with
        scale_quality=direction_only/unknown (no fake scale invented).

AZ-921  VioOutput.scale_quality signal; ESKF add_vio adapts R_meas
        position block based on the flag (1e6 inflation when scale is
        direction_only/unknown to keep the filter consistent).

AZ-922  KLT/RANSAC cheirality gate rejects single-frame rotations
        beyond a config threshold (default 30 deg), catching
        cv2.recoverPose twisted-pair flips that cause immediate ESKF
        divergence on low-parallax aerial scenes.

Verification:
- Tier-1 (macOS) unit suite: 2346 passed, 0 failed.
- Tier-2 (Jetson) Derkachi e2e: divergence moves from frame 5
  (mahalanobis^2 3757) to frame 233 (mahalanobis^2 212). Remaining
  drift is open-loop attitude accumulation, not cheirality.

Follow-up tickets filed:
- AZ-923 closed as misdiagnosed: EskfNominalAltitudeProvider was
  already correct (nominal_pos.z IS the AGL when takeoff origin sits
  at ground level); the early-frame AGL near zero reflects the drone
  being stationary on the ground, not a provider bug.
- AZ-942 filed: cross-check VIO rotation against IMU preintegrator
  (consistency gate) - more physically grounded than the coarse
  AZ-922 threshold and likely required to absorb the frame-233 drift.

Co-authored-by: Cursor <cursoragent@cursor.com>

tests/unit/c1_vio/test_az919_klt_ransac_altitude_provider.py

@@ -0,0 +1,70 @@
+"""AZ-919 — `KltRansacStrategy` accepts the `altitude_provider` kwarg.
+
+AZ-919 is plumbing only: the strategy must accept and store the provider
+without yet consuming it. The math that consumes it lands in AZ-920;
+the degraded-mode behaviour lands in AZ-921. Until then, the strategy
+MUST behave identically to today when ``altitude_provider`` is ``None``
+(AC-3 bug-for-bug compatibility).
+"""
+
+from __future__ import annotations
+
+from gps_denied_onboard.components.c1_vio import C1VioConfig, KltRansacConfig
+from gps_denied_onboard.components.c1_vio.klt_ransac import KltRansacStrategy
+from gps_denied_onboard.config.schema import Config, RuntimeConfig
+from gps_denied_onboard.fdr_client.client import FdrClient
+from gps_denied_onboard.helpers.altitude_provider import (
+    AltitudeProvider,
+    EskfNominalAltitudeProvider,
+)
+
+
+def _config() -> Config:
+    c1 = C1VioConfig(
+        strategy="klt_ransac",
+        klt_ransac=KltRansacConfig(),
+        lost_frame_threshold=3,
+    )
+    return Config.with_blocks(c1_vio=c1, runtime=RuntimeConfig())
+
+
+def _fdr_client() -> FdrClient:
+    return FdrClient(producer_id="test.az919", capacity=8, _emit_diag_log=False)
+
+
+def test_default_altitude_provider_is_none() -> None:
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+
+    assert strategy._altitude_provider is None
+
+
+def test_explicit_altitude_provider_is_stored() -> None:
+    provider: AltitudeProvider = EskfNominalAltitudeProvider(
+        estimator_supplier=lambda: None,
+    )
+
+    strategy = KltRansacStrategy(
+        _config(),
+        fdr_client=_fdr_client(),
+        altitude_provider=provider,
+    )
+
+    assert strategy._altitude_provider is provider
+
+
+def test_altitude_provider_is_keyword_only() -> None:
+    # Arrange — positional pass of altitude_provider must fail because
+    # the kwarg is declared after ``*``. This pins the calling contract
+    # so future refactors cannot accidentally make it positional.
+    fdr_client = _fdr_client()
+    provider = EskfNominalAltitudeProvider(estimator_supplier=lambda: None)
+
+    # Act + Assert
+    try:
+        KltRansacStrategy(_config(), fdr_client, provider)  # type: ignore[misc]
+    except TypeError:
+        return
+    raise AssertionError(
+        "KltRansacStrategy accepted altitude_provider positionally; "
+        "AZ-919 AC-3 requires the kwarg to be keyword-only."
+    )

tests/unit/c1_vio/test_az920_gsd_scale.py

@@ -0,0 +1,254 @@
+"""AZ-920 — `recover_scale` pure-function tests.
+
+Pins the GSD scale-recovery contract that the KLT/RANSAC integration
+in ``KltRansacStrategy.process_frame`` relies on. The integration
+test is in ``test_az920_klt_ransac_scale_integration.py``; this file
+covers the math in isolation.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import pytest
+
+from gps_denied_onboard.components.c1_vio._gsd_scale import (
+    INFINITE_SCALE_UNCERTAINTY_M,
+    RELATIVE_DISPLACEMENT_NOISE,
+    ScaleRecoveryResult,
+    recover_scale,
+)
+
+# ----------------------------------------------------------------------
+# Helpers
+
+
+def _intrinsics(fx: float = 1680.4469) -> np.ndarray:
+    """Derkachi-grade nadir intrinsics by default (fx=fy, cx/cy at centre)."""
+    return np.array(
+        [
+            [fx, 0.0, 960.0],
+            [0.0, fx, 540.0],
+            [0.0, 0.0, 1.0],
+        ],
+        dtype=np.float64,
+    )
+
+
+def _uniform_flow(n: int, dx_px: float, dy_px: float = 0.0) -> tuple[np.ndarray, np.ndarray]:
+    """Build Nx2 prev / curr point clouds with a uniform pixel-flow shift."""
+    rng = np.random.default_rng(seed=2026)
+    base = rng.uniform(100.0, 1800.0, size=(n, 2))
+    prev = base.copy()
+    curr = base + np.array([dx_px, dy_px], dtype=np.float64)
+    return prev, curr
+
+
+# ----------------------------------------------------------------------
+# Happy path
+
+
+def test_nadir_identity_rotation_with_known_gsd_yields_expected_scale() -> None:
+    # Arrange — at AGL=100 m, fx=1680 px → GSD ≈ 0.0595 m/px. A 20 px
+    # mean flow corresponds to ≈1.19 m of horizontal motion. t_unit
+    # along +X means t_horizontal = 1; scale_factor must equal 1.19.
+    t_unit = np.array([1.0, 0.0, 0.0], dtype=np.float64)
+    pts_prev, pts_curr = _uniform_flow(n=64, dx_px=20.0)
+
+    # Act
+    result = recover_scale(
+        t_unit=t_unit,
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=100.0,
+    )
+
+    # Assert
+    assert isinstance(result, ScaleRecoveryResult)
+    expected_disp_m = 20.0 * 100.0 / 1680.4469
+    assert result.scale_factor == pytest.approx(expected_disp_m, rel=1e-9)
+    assert result.scale_uncertainty_m == pytest.approx(
+        expected_disp_m * RELATIVE_DISPLACEMENT_NOISE, rel=1e-9
+    )
+    assert result.is_recoverable()
+    # AZ-921 — happy-path categorisation is "metric".
+    assert result.quality == "metric"
+
+
+def test_diagonal_flow_uses_l2_norm_for_mean_magnitude() -> None:
+    # Arrange — (dx=3, dy=4) flow has L2 magnitude 5 px per feature.
+    t_unit = np.array([1.0, 0.0, 0.0], dtype=np.float64)
+    pts_prev, pts_curr = _uniform_flow(n=50, dx_px=3.0, dy_px=4.0)
+
+    # Act
+    result = recover_scale(
+        t_unit=t_unit,
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=100.0,
+    )
+
+    # Assert
+    expected_disp_m = 5.0 * 100.0 / 1680.4469
+    assert result.scale_factor == pytest.approx(expected_disp_m, rel=1e-9)
+
+
+def test_off_axis_t_unit_uses_horizontal_component_magnitude() -> None:
+    # Arrange — t_unit splits 0.6/0.8 between camera-X and camera-Y;
+    # the horizontal magnitude is sqrt(0.36 + 0.64) = 1.0. The scale
+    # therefore stays the displacement / 1.0.
+    t_unit = np.array([0.6, 0.8, 0.0], dtype=np.float64)
+    pts_prev, pts_curr = _uniform_flow(n=40, dx_px=10.0)
+
+    # Act
+    result = recover_scale(
+        t_unit=t_unit,
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=120.0,
+    )
+
+    # Assert
+    expected_disp_m = 10.0 * 120.0 / 1680.4469
+    assert result.scale_factor == pytest.approx(expected_disp_m, rel=1e-9)
+
+
+# ----------------------------------------------------------------------
+# Degenerate / fallback paths — each must produce inf uncertainty.
+
+
+def test_agl_none_returns_infinite_uncertainty() -> None:
+    pts_prev, pts_curr = _uniform_flow(n=32, dx_px=20.0)
+
+    result = recover_scale(
+        t_unit=np.array([1.0, 0.0, 0.0]),
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=None,
+    )
+
+    assert result.scale_factor == 0.0
+    assert result.scale_uncertainty_m == INFINITE_SCALE_UNCERTAINTY_M
+    assert not result.is_recoverable()
+    # AZ-921 — AGL-unknown is "unknown", not "direction_only".
+    assert result.quality == "unknown"
+
+
+def test_zero_or_negative_agl_returns_infinite_uncertainty() -> None:
+    pts_prev, pts_curr = _uniform_flow(n=32, dx_px=20.0)
+
+    for bad_agl in (0.0, -1.0):
+        result = recover_scale(
+            t_unit=np.array([1.0, 0.0, 0.0]),
+            pts_prev=pts_prev,
+            pts_curr=pts_curr,
+            intrinsics_3x3=_intrinsics(),
+            agl_m=bad_agl,
+        )
+
+        assert math.isinf(result.scale_uncertainty_m), f"agl={bad_agl}"
+
+
+def test_near_pure_vertical_t_unit_returns_infinite_uncertainty() -> None:
+    # Arrange — t along the optical axis (camera-Z) only; the GSD
+    # method cannot tie horizontal pixel flow to vertical motion.
+    pts_prev, pts_curr = _uniform_flow(n=40, dx_px=5.0)
+
+    result = recover_scale(
+        t_unit=np.array([0.01, 0.01, 0.9998]),
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=100.0,
+    )
+
+    assert not result.is_recoverable()
+    # AZ-921 — near-vertical motion routes to direction_only: the
+    # direction of t_unit is still meaningful, only the magnitude is
+    # not derivable from horizontal pixel flow.
+    assert result.quality == "direction_only"
+
+
+def test_zero_inlier_flow_returns_infinite_uncertainty() -> None:
+    # Arrange — stationary inliers (dx=dy=0). Cannot disambiguate the
+    # scale of a zero motion.
+    pts_prev, pts_curr = _uniform_flow(n=40, dx_px=0.0, dy_px=0.0)
+
+    result = recover_scale(
+        t_unit=np.array([1.0, 0.0, 0.0]),
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=100.0,
+    )
+
+    assert not result.is_recoverable()
+    # AZ-921 — stale features routes to "unknown", since neither the
+    # magnitude nor the direction of motion is trustworthy.
+    assert result.quality == "unknown"
+
+
+def test_empty_inlier_set_returns_infinite_uncertainty() -> None:
+    empty = np.zeros((0, 2), dtype=np.float64)
+
+    result = recover_scale(
+        t_unit=np.array([1.0, 0.0, 0.0]),
+        pts_prev=empty,
+        pts_curr=empty,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=100.0,
+    )
+
+    assert not result.is_recoverable()
+
+
+def test_zero_focal_length_returns_infinite_uncertainty() -> None:
+    pts_prev, pts_curr = _uniform_flow(n=32, dx_px=20.0)
+
+    result = recover_scale(
+        t_unit=np.array([1.0, 0.0, 0.0]),
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(fx=0.0),
+        agl_m=100.0,
+    )
+
+    assert not result.is_recoverable()
+
+
+# ----------------------------------------------------------------------
+# Numerical stability with a Derkachi-grade inlier set
+
+
+def test_derkachi_grade_inlier_count_yields_stable_scale() -> None:
+    # Arrange — 120 inliers (representative of the Derkachi cruise
+    # observation) with a small per-feature noise around a uniform
+    # 30 px optical flow at 150 m AGL.
+    rng = np.random.default_rng(seed=271828)
+    base = rng.uniform(100.0, 1800.0, size=(120, 2))
+    flow_mean_px = 30.0
+    noise = rng.normal(0.0, 0.5, size=(120, 2))
+    pts_prev = base
+    pts_curr = base + np.array([flow_mean_px, 0.0]) + noise
+    t_unit = np.array([1.0, 0.0, 0.0])
+    agl_m = 150.0
+
+    # Act
+    result = recover_scale(
+        t_unit=t_unit,
+        pts_prev=pts_prev,
+        pts_curr=pts_curr,
+        intrinsics_3x3=_intrinsics(),
+        agl_m=agl_m,
+    )
+
+    # Assert — observed scale must be within 5 % of the analytic value
+    # at this noise level (sigma = 0.5 px over 120 inliers).
+    expected = flow_mean_px * agl_m / 1680.4469
+    assert result.scale_factor == pytest.approx(expected, rel=5e-2)
+    assert result.is_recoverable()

tests/unit/c1_vio/test_az920_klt_ransac_scale_integration.py

@@ -0,0 +1,319 @@
+"""AZ-920 — `KltRansacStrategy` x `AltitudeProvider` integration coverage.
+
+Pins the contract that ``process_frame`` consumes the
+:class:`AltitudeProvider` to recover metric scale on the
+otherwise-unit translation that ``cv2.recoverPose`` emits. Pure
+function math is covered in ``test_az920_gsd_scale.py``; this file
+covers the wiring at the strategy boundary.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import numpy as np
+import pytest
+
+from gps_denied_onboard._types.calibration import CameraCalibration
+from gps_denied_onboard._types.nav import (
+    ImuSample,
+    ImuWindow,
+    NavCameraFrame,
+)
+from gps_denied_onboard.components.c1_vio import C1VioConfig, KltRansacConfig
+from gps_denied_onboard.components.c1_vio import klt_ransac as klt_ransac_module
+from gps_denied_onboard.components.c1_vio._gsd_scale import RELATIVE_DISPLACEMENT_NOISE
+from gps_denied_onboard.components.c1_vio.klt_ransac import (
+    _MIN_POSITION_VARIANCE_M2,
+    KltRansacStrategy,
+)
+from gps_denied_onboard.config.schema import Config, RuntimeConfig
+from gps_denied_onboard.fdr_client.client import FdrClient
+from gps_denied_onboard.helpers.altitude_provider import AltitudeProvider
+from gps_denied_onboard.helpers.ransac_filter import RansacResult
+
+# ----------------------------------------------------------------------
+# Test scaffolding
+
+
+class _ConstantAgl(AltitudeProvider):
+    """Returns a fixed AGL on every call."""
+
+    def __init__(self, agl_m: float | None) -> None:
+        self._agl_m = agl_m
+
+    def agl_m(self, now_ns: int) -> float | None:
+        return self._agl_m
+
+
+def _calibration(focal_length: float = 1680.0) -> CameraCalibration:
+    return CameraCalibration(
+        camera_id="khp20s30-test",
+        intrinsics_3x3=np.array(
+            [
+                [focal_length, 0.0, 960.0],
+                [0.0, focal_length, 540.0],
+                [0.0, 0.0, 1.0],
+            ],
+            dtype=np.float64,
+        ),
+        distortion=np.zeros(5, dtype=np.float64),
+        body_to_camera_se3=np.eye(4, dtype=np.float64),
+        acquisition_method="test_az920",
+    )
+
+
+def _frame(idx: int) -> NavCameraFrame:
+    rng = np.random.default_rng(seed=idx)
+    image = (rng.integers(0, 255, size=(240, 240), dtype=np.int16)).astype(np.uint8)
+    return NavCameraFrame(
+        frame_id=idx,
+        timestamp=datetime.fromtimestamp(idx * 0.1, tz=timezone.utc),
+        image=image,
+        camera_calibration_id="khp20s30-test",
+    )
+
+
+def _imu_window(frame_idx: int) -> ImuWindow:
+    ts_start_ns = 1_000_000_000 + frame_idx * 100_000_000
+    samples = tuple(
+        ImuSample(
+            ts_ns=ts_start_ns + i * 5_000_000,
+            accel_xyz=(0.0, 0.0, 9.81),
+            gyro_xyz=(0.0, 0.0, 0.0),
+        )
+        for i in range(3)
+    )
+    return ImuWindow(
+        samples=samples,
+        ts_start_ns=samples[0].ts_ns,
+        ts_end_ns=samples[-1].ts_ns,
+    )
+
+
+def _config() -> Config:
+    return Config.with_blocks(
+        c1_vio=C1VioConfig(
+            strategy="klt_ransac",
+            klt_ransac=KltRansacConfig(),
+            lost_frame_threshold=3,
+        ),
+        runtime=RuntimeConfig(),
+    )
+
+
+def _patch_pose_recovery(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    flow_px: float,
+    inlier_count: int = 40,
+    t_unit: tuple[float, float, float] = (1.0, 0.0, 0.0),
+) -> None:
+    """Force the geometry stack to a controlled success path.
+
+    Builds an inlier set with a uniform ``flow_px`` pixel shift in the
+    +x direction; ``cv2.findEssentialMat`` returns identity rotation +
+    an all-inlier mask; ``cv2.recoverPose`` returns identity rotation +
+    a unit-length translation in ``t_unit``.
+    """
+    rng = np.random.default_rng(seed=314159)
+    base = rng.uniform(50.0, 1800.0, size=(inlier_count, 2))
+    inliers = np.column_stack([base, base + np.array([flow_px, 0.0])])
+    mask = np.ones((inlier_count, 1), dtype=np.uint8)
+
+    def _fake_filter(_corr: np.ndarray, _thresh: float, _min: int) -> RansacResult:
+        return RansacResult(
+            inlier_correspondences=inliers,
+            inlier_count=inlier_count,
+            outlier_count=0,
+            median_residual_px=0.5,
+        )
+
+    def _fake_find_essential(*_a: Any, **_k: Any) -> tuple[np.ndarray, np.ndarray]:
+        return np.eye(3, dtype=np.float64), mask
+
+    def _fake_recover_pose(*_a: Any, **_k: Any) -> tuple[int, np.ndarray, np.ndarray, np.ndarray]:
+        R = np.eye(3, dtype=np.float64)
+        t_col = np.asarray(t_unit, dtype=np.float64).reshape(3, 1)
+        return inlier_count, R, t_col, mask
+
+    monkeypatch.setattr(
+        klt_ransac_module.RansacFilter,
+        "filter_correspondences",
+        staticmethod(_fake_filter),
+    )
+    monkeypatch.setattr(klt_ransac_module.cv2, "findEssentialMat", _fake_find_essential)
+    monkeypatch.setattr(klt_ransac_module.cv2, "recoverPose", _fake_recover_pose)
+
+
+def _fdr_client() -> FdrClient:
+    return FdrClient(producer_id="test.az920", capacity=16, _emit_diag_log=False)
+
+
+# ----------------------------------------------------------------------
+# AC-4 — translation gets metric scale when the provider yields valid AGL
+
+
+def test_steady_state_frame_translation_is_metric_when_agl_known(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange — 20 px mean flow at 100 m AGL, fx=1680.
+    # Expected scale_factor = 20 * 100 / 1680 ≈ 1.190 m. The unit t is
+    # along +X, so the emitted translation is ≈ (1.19, 0, 0) m.
+    _patch_pose_recovery(monkeypatch, flow_px=20.0)
+    fdr_client = _fdr_client()
+    provider = _ConstantAgl(agl_m=100.0)
+    strategy = KltRansacStrategy(
+        _config(), fdr_client=fdr_client, altitude_provider=provider
+    )
+    calibration = _calibration(focal_length=1680.0)
+
+    # Act — first frame: INIT (identity pose). Second frame: scale recovery fires.
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    pose_matrix = np.asarray(second.relative_pose_T.matrix())
+    translation = pose_matrix[:3, 3]
+    expected_x = 20.0 * 100.0 / 1680.0
+    assert translation[0] == pytest.approx(expected_x, rel=1e-3)
+    # Y / Z components are zero because t_unit was pure +X.
+    assert translation[1] == pytest.approx(0.0, abs=1e-9)
+    assert translation[2] == pytest.approx(0.0, abs=1e-9)
+    # Translation magnitude is metric, not unit-length.
+    assert float(np.linalg.norm(translation)) > 0.5  # metres, not 1.0 px-scale
+    # AZ-921 — scale_quality must report "metric" on the happy path.
+    assert second.scale_quality == "metric"
+
+
+# ----------------------------------------------------------------------
+# AC-4 — position covariance is in m² when AGL is known
+
+
+def test_position_covariance_block_is_metric_when_agl_known(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    _patch_pose_recovery(monkeypatch, flow_px=20.0)
+    provider = _ConstantAgl(agl_m=100.0)
+    strategy = KltRansacStrategy(
+        _config(), fdr_client=_fdr_client(), altitude_provider=provider
+    )
+    calibration = _calibration(focal_length=1680.0)
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    cov = np.asarray(second.pose_covariance_6x6)
+    expected_disp_m = 20.0 * 100.0 / 1680.0
+    expected_pos_var = max(
+        (expected_disp_m * RELATIVE_DISPLACEMENT_NOISE) ** 2,
+        _MIN_POSITION_VARIANCE_M2,
+    )
+    pos_block = cov[0:3, 0:3]
+    assert np.allclose(pos_block, np.eye(3) * expected_pos_var, atol=1e-12)
+
+
+# ----------------------------------------------------------------------
+# AZ-921 AC-7 — when AGL is unknown the strategy emits scale_quality
+# = "unknown" and leaves the cov in geometry-natural units (the ESKF
+# inflates R_meas; see test_az921_eskf_add_vio_scale_quality.py).
+
+
+def test_scale_quality_unknown_when_agl_provider_returns_none(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    _patch_pose_recovery(monkeypatch, flow_px=20.0)
+    provider = _ConstantAgl(agl_m=None)
+    strategy = KltRansacStrategy(
+        _config(), fdr_client=_fdr_client(), altitude_provider=provider
+    )
+    calibration = _calibration(focal_length=1680.0)
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    assert second.scale_quality == "unknown"
+    # Translation stays unit-length when scale could not be recovered.
+    pose_matrix = np.asarray(second.relative_pose_T.matrix())
+    translation = pose_matrix[:3, 3]
+    assert float(np.linalg.norm(translation)) == pytest.approx(1.0, rel=1e-6)
+    # The position block of cov is NOT overridden by KLT/RANSAC any
+    # more (AZ-921 AC-7). The ESKF's R_meas adaptation provides the
+    # "do not trust" signal on the consumer side.
+    cov = np.asarray(second.pose_covariance_6x6)
+    pos_block = cov[0:3, 0:3]
+    assert float(pos_block[0, 0]) < 1.0  # NOT the AZ-920 1e6 sentinel
+
+
+# ----------------------------------------------------------------------
+# AZ-921 AC-6 — direction_only branch reachable on near-vertical motion
+
+
+def test_scale_quality_direction_only_on_near_pure_vertical_motion(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange — realistic horizontal flow (20 px) but cv2.recoverPose
+    # returns a t_unit pointing essentially along the optical axis
+    # (the climb/descent edge case). Horizontal magnitude is far below
+    # the _MIN_T_HORIZONTAL_MAGNITUDE = 0.05 threshold.
+    _patch_pose_recovery(
+        monkeypatch,
+        flow_px=20.0,
+        t_unit=(0.001, 0.001, 0.99999),
+    )
+    provider = _ConstantAgl(agl_m=100.0)
+    strategy = KltRansacStrategy(
+        _config(), fdr_client=_fdr_client(), altitude_provider=provider
+    )
+    calibration = _calibration(focal_length=1680.0)
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    assert second.scale_quality == "direction_only"
+    # Translation magnitude stays at the cv2.recoverPose output — i.e.
+    # the t_unit input — because scale was not recovered. The mocked
+    # t_unit is (0.001, 0.001, 0.99999), L2 norm ≈ 0.9999. The test
+    # asserts the strategy did NOT multiply by a real metric scale.
+    pose_matrix = np.asarray(second.relative_pose_T.matrix())
+    translation = pose_matrix[:3, 3]
+    assert float(np.linalg.norm(translation)) == pytest.approx(0.9999, abs=1e-3)
+
+
+# ----------------------------------------------------------------------
+# AZ-919 AC-3 regression — provider=None keeps pre-AZ-920 behaviour
+
+
+def test_translation_unchanged_and_cov_untouched_when_provider_is_none(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange — same mock as before, but the strategy is built WITHOUT
+    # an altitude_provider (the pre-AZ-919 / legacy unit-test path).
+    _patch_pose_recovery(monkeypatch, flow_px=20.0)
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration(focal_length=1680.0)
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert — translation stays at the unit-length t_unit (1, 0, 0).
+    pose_matrix = np.asarray(second.relative_pose_T.matrix())
+    translation = pose_matrix[:3, 3]
+    assert float(np.linalg.norm(translation)) == pytest.approx(1.0, rel=1e-6)
+    # The position block of cov is the same scalar * I as the rotation
+    # block — no AZ-920 override fired.
+    cov = np.asarray(second.pose_covariance_6x6)
+    assert np.allclose(cov[0:3, 0:3], cov[3:6, 3:6], atol=1e-12)
+    # AZ-921 — without an altitude provider, the strategy defaults
+    # scale_quality to "unknown" so consumers know to inflate R_meas.
+    assert second.scale_quality == "unknown"

tests/unit/c1_vio/test_az922_cheirality_gate.py

@@ -0,0 +1,354 @@
+"""AZ-922 — cheirality / rotation-plausibility gate in KLT/RANSAC.
+
+Covers AC-1 (axis-angle helper math), AC-2/AC-3 (gate threshold + routing
+through `_pose_recovery_failed`), and AC-4 (boundary + AC-7 lost-frame
+escalation). AC-5 (Jetson e2e Derkachi past frame 5) is gated separately
+via the Tier-2 harness — not in unit scope.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from typing import Any
+
+import numpy as np
+import pytest
+
+from gps_denied_onboard._types.calibration import CameraCalibration
+from gps_denied_onboard._types.nav import (
+    ImuSample,
+    ImuWindow,
+    NavCameraFrame,
+)
+from gps_denied_onboard.components.c1_vio import C1VioConfig, KltRansacConfig
+from gps_denied_onboard.components.c1_vio import klt_ransac as klt_ransac_module
+from gps_denied_onboard.components.c1_vio.errors import (
+    VioFatalError,
+    VioInitializingError,
+)
+from gps_denied_onboard.components.c1_vio.klt_ransac import (
+    KltRansacStrategy,
+    _rotation_angle_rad,
+)
+from gps_denied_onboard.config.schema import Config, RuntimeConfig
+from gps_denied_onboard.fdr_client.client import FdrClient
+from gps_denied_onboard.helpers.ransac_filter import RansacResult
+
+# ----------------------------------------------------------------------
+# AC-1 — pure helper math
+# ----------------------------------------------------------------------
+
+
+def test_rotation_angle_identity_is_zero() -> None:
+    # Assert
+    assert _rotation_angle_rad(np.eye(3, dtype=np.float64)) == pytest.approx(0.0, abs=1e-12)
+
+
+def test_rotation_angle_180_about_x_is_pi() -> None:
+    # Arrange — R rotates 180° about the body-X axis: trace = 1 + (-1) + (-1) = -1.
+    R = np.array(
+        [
+            [1.0, 0.0, 0.0],
+            [0.0, -1.0, 0.0],
+            [0.0, 0.0, -1.0],
+        ],
+        dtype=np.float64,
+    )
+
+    # Assert
+    assert _rotation_angle_rad(R) == pytest.approx(math.pi, abs=1e-9)
+
+
+def test_rotation_angle_general_diagonal_recovers_axis_angle_magnitude() -> None:
+    # Arrange — 30° rotation about body-Z: trace = cos(30)+cos(30)+1.
+    theta = math.radians(30.0)
+    R = np.array(
+        [
+            [math.cos(theta), -math.sin(theta), 0.0],
+            [math.sin(theta), math.cos(theta), 0.0],
+            [0.0, 0.0, 1.0],
+        ],
+        dtype=np.float64,
+    )
+
+    # Assert
+    assert _rotation_angle_rad(R) == pytest.approx(theta, abs=1e-9)
+
+
+def test_rotation_angle_arccos_argument_clipped_against_float_drift() -> None:
+    # Arrange — synthesise an R whose trace is *just* above 3.0 (impossible
+    # in exact arithmetic but achievable via float drift). Without the
+    # arccos clip this would yield NaN; with the clip it must return 0.
+    R = np.eye(3, dtype=np.float64) + np.full((3, 3), 1e-15, dtype=np.float64)
+
+    # Assert
+    assert _rotation_angle_rad(R) == pytest.approx(0.0, abs=1e-6)
+    assert math.isfinite(_rotation_angle_rad(R))
+
+
+def test_rotation_angle_uses_jetson_frame_5_diagonal_signature() -> None:
+    # Arrange — exact R diagonal observed at Derkachi frame 5 (the
+    # divergence point). Trace = -0.848 - 0.639 + 0.487 = -1.0.
+    R = np.diag([-0.848, -0.639, 0.487]).astype(np.float64)
+
+    # Assert — recover the 180° rotation the ESKF traceback implied.
+    assert _rotation_angle_rad(R) == pytest.approx(math.pi, abs=1e-9)
+
+
+# ----------------------------------------------------------------------
+# Strategy-level scaffolding (mirrors test_az920_klt_ransac_scale_integration.py)
+# ----------------------------------------------------------------------
+
+
+def _calibration() -> CameraCalibration:
+    return CameraCalibration(
+        camera_id="khp20s30-test",
+        intrinsics_3x3=np.array(
+            [
+                [1680.0, 0.0, 960.0],
+                [0.0, 1680.0, 540.0],
+                [0.0, 0.0, 1.0],
+            ],
+            dtype=np.float64,
+        ),
+        distortion=np.zeros(5, dtype=np.float64),
+        body_to_camera_se3=np.eye(4, dtype=np.float64),
+        acquisition_method="test_az922",
+    )
+
+
+def _frame(idx: int) -> NavCameraFrame:
+    rng = np.random.default_rng(seed=idx)
+    image = (rng.integers(0, 255, size=(240, 240), dtype=np.int16)).astype(np.uint8)
+    return NavCameraFrame(
+        frame_id=idx,
+        timestamp=datetime.fromtimestamp(idx * 0.1, tz=timezone.utc),
+        image=image,
+        camera_calibration_id="khp20s30-test",
+    )
+
+
+def _imu_window(frame_idx: int) -> ImuWindow:
+    ts_start_ns = 1_000_000_000 + frame_idx * 100_000_000
+    samples = tuple(
+        ImuSample(
+            ts_ns=ts_start_ns + i * 5_000_000,
+            accel_xyz=(0.0, 0.0, 9.81),
+            gyro_xyz=(0.0, 0.0, 0.0),
+        )
+        for i in range(3)
+    )
+    return ImuWindow(
+        samples=samples,
+        ts_start_ns=samples[0].ts_ns,
+        ts_end_ns=samples[-1].ts_ns,
+    )
+
+
+def _config(lost_frame_threshold: int = 3) -> Config:
+    return Config.with_blocks(
+        c1_vio=C1VioConfig(
+            strategy="klt_ransac",
+            klt_ransac=KltRansacConfig(),
+            lost_frame_threshold=lost_frame_threshold,
+        ),
+        runtime=RuntimeConfig(),
+    )
+
+
+def _patch_pose_recovery_with_rotation(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    R_3x3: np.ndarray,
+    inlier_count: int = 40,
+) -> None:
+    """Force the geometry stack to a controlled path with a chosen R.
+
+    Mirrors the AZ-920 test helper but takes the rotation matrix as a
+    parameter so AZ-922 can exercise the cheirality gate directly.
+    """
+    rng = np.random.default_rng(seed=271828)
+    base = rng.uniform(50.0, 1800.0, size=(inlier_count, 2))
+    inliers = np.column_stack([base, base + np.array([5.0, 0.0])])
+    mask = np.ones((inlier_count, 1), dtype=np.uint8)
+
+    def _fake_filter(_corr: np.ndarray, _thresh: float, _min: int) -> RansacResult:
+        return RansacResult(
+            inlier_correspondences=inliers,
+            inlier_count=inlier_count,
+            outlier_count=0,
+            median_residual_px=0.5,
+        )
+
+    def _fake_find_essential(*_a: Any, **_k: Any) -> tuple[np.ndarray, np.ndarray]:
+        return np.eye(3, dtype=np.float64), mask
+
+    def _fake_recover_pose(*_a: Any, **_k: Any) -> tuple[int, np.ndarray, np.ndarray, np.ndarray]:
+        t_col = np.array([[1.0], [0.0], [0.0]], dtype=np.float64)
+        return inlier_count, R_3x3.astype(np.float64), t_col, mask
+
+    monkeypatch.setattr(
+        klt_ransac_module.RansacFilter,
+        "filter_correspondences",
+        staticmethod(_fake_filter),
+    )
+    monkeypatch.setattr(klt_ransac_module.cv2, "findEssentialMat", _fake_find_essential)
+    monkeypatch.setattr(klt_ransac_module.cv2, "recoverPose", _fake_recover_pose)
+
+
+def _fdr_client() -> FdrClient:
+    return FdrClient(producer_id="test.az922", capacity=16, _emit_diag_log=False)
+
+
+def _r_about_z(theta_rad: float) -> np.ndarray:
+    return np.array(
+        [
+            [math.cos(theta_rad), -math.sin(theta_rad), 0.0],
+            [math.sin(theta_rad), math.cos(theta_rad), 0.0],
+            [0.0, 0.0, 1.0],
+        ],
+        dtype=np.float64,
+    )
+
+
+# ----------------------------------------------------------------------
+# AC-2/AC-3 — gate threshold + routing through _pose_recovery_failed
+# ----------------------------------------------------------------------
+
+
+def test_identity_rotation_passes_gate(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Arrange
+    _patch_pose_recovery_with_rotation(monkeypatch, R_3x3=np.eye(3))
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration()
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    assert second is not None
+    assert second.frame_id == "2"
+
+
+def test_five_degree_rotation_passes_gate(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Arrange — 5° rotation, well below the 30° default threshold.
+    _patch_pose_recovery_with_rotation(monkeypatch, R_3x3=_r_about_z(math.radians(5.0)))
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration()
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    assert second is not None
+
+
+def test_sixty_degree_rotation_rejected_by_gate(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Arrange — 60° rotation exceeds the 30° default threshold.
+    _patch_pose_recovery_with_rotation(monkeypatch, R_3x3=_r_about_z(math.radians(60.0)))
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration()
+
+    # Act + Assert
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    with pytest.raises(VioInitializingError, match="implausible_rotation_angle"):
+        strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+
+def test_180_degree_rotation_rejected_by_gate(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Arrange — synthesise the Jetson-observed frame-5 R signature.
+    R_180 = np.diag([-0.848, -0.639, 0.487]).astype(np.float64)
+    _patch_pose_recovery_with_rotation(monkeypatch, R_3x3=R_180)
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration()
+
+    # Act + Assert
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    with pytest.raises(VioInitializingError, match="implausible_rotation_angle"):
+        strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+
+def test_threshold_boundary_just_above_rejects(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Arrange — 30.1° vs 30° threshold.
+    _patch_pose_recovery_with_rotation(
+        monkeypatch, R_3x3=_r_about_z(math.radians(30.1))
+    )
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration()
+
+    # Act + Assert
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    with pytest.raises(VioInitializingError, match="implausible_rotation_angle"):
+        strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+
+def test_threshold_boundary_just_below_passes(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Arrange — 29.9° just below 30° threshold.
+    _patch_pose_recovery_with_rotation(
+        monkeypatch, R_3x3=_r_about_z(math.radians(29.9))
+    )
+    strategy = KltRansacStrategy(_config(), fdr_client=_fdr_client())
+    calibration = _calibration()
+
+    # Act
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    second = strategy.process_frame(_frame(idx=2), _imu_window(2), calibration)
+
+    # Assert
+    assert second is not None
+
+
+# ----------------------------------------------------------------------
+# AC-4 (AC-7 path) — consecutive rejections escalate to VioFatalError
+# ----------------------------------------------------------------------
+
+
+def test_consecutive_rejections_eventually_raise_vio_fatal(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange — every frame yields a 180° flip; lost_frame_threshold=3
+    # means the 4th frame in this stream (the 3rd consecutive failure)
+    # crosses the LOST gate.
+    R_180 = np.diag([-1.0, -1.0, 1.0]).astype(np.float64)  # 180° about Z
+    _patch_pose_recovery_with_rotation(monkeypatch, R_3x3=R_180)
+    strategy = KltRansacStrategy(
+        _config(lost_frame_threshold=3), fdr_client=_fdr_client()
+    )
+    calibration = _calibration()
+
+    # Act — frame 1 seeds INIT; frames 2-4 hit the gate and tick lost.
+    strategy.process_frame(_frame(idx=1), _imu_window(1), calibration)
+    for idx in range(2, 4):
+        with pytest.raises(VioInitializingError, match="implausible_rotation_angle"):
+            strategy.process_frame(_frame(idx=idx), _imu_window(idx), calibration)
+    # The 4th consecutive failed frame trips the LOST/VioFatalError gate.
+    with pytest.raises(VioFatalError, match="exhausted lost-frame budget"):
+        strategy.process_frame(_frame(idx=4), _imu_window(4), calibration)
+
+
+# ----------------------------------------------------------------------
+# Config validation — defends the (0, π] range
+# ----------------------------------------------------------------------
+
+
+def test_config_rejects_zero_or_negative_threshold() -> None:
+    # Act + Assert
+    with pytest.raises(Exception, match="max_frame_rotation_rad must be in"):
+        KltRansacConfig(max_frame_rotation_rad=0.0)
+
+
+def test_config_rejects_threshold_above_pi() -> None:
+    # Act + Assert
+    with pytest.raises(Exception, match="max_frame_rotation_rad must be in"):
+        KltRansacConfig(max_frame_rotation_rad=math.pi + 0.01)
+
+
+def test_config_accepts_pi_exactly() -> None:
+    # Act — the inclusive upper bound. No rotation can exceed π anyway.
+    cfg = KltRansacConfig(max_frame_rotation_rad=math.pi)
+
+    # Assert
+    assert cfg.max_frame_rotation_rad == pytest.approx(math.pi)

tests/unit/c1_vio/test_klt_ransac_strategy.py

@@ -53,7 +53,6 @@ from gps_denied_onboard.config.schema import Config, RuntimeConfig
 from gps_denied_onboard.fdr_client.client import FdrClient
 from gps_denied_onboard.fdr_client.records import FdrRecord
 
-
 # ----------------------------------------------------------------------
 # Helpers — keep boilerplate out of the AC test bodies.
 
@@ -528,6 +527,19 @@ def test_ac6_low_inlier_count_emits_degraded_with_monotonic_covariance(
         calibration,
     )
 
+    # AZ-922 — pin cv2.recoverPose to identity rotation for frame 2 too.
+    # Real cv2 on this synthetic input returns a near-180° rotation that
+    # the cheirality gate would reject; this test asserts FACADE state
+    # classification on inlier loss, not cv2's geometry on synthetic data.
+    def _identity_recover_pose(
+        *_a: Any, **_k: Any
+    ) -> tuple[int, np.ndarray, np.ndarray, np.ndarray]:
+        R = np.eye(3, dtype=np.float64)
+        t = np.array([[0.01], [0.0], [0.0]], dtype=np.float64)
+        return 1, R, t, np.ones((1, 1), dtype=np.uint8)
+
+    monkeypatch.setattr(klt_ransac_module.cv2, "recoverPose", _identity_recover_pose)
+
     # Frame 2 — first successful pose recovery (TRACKING).
     out_tracking = strategy.process_frame(
         _frame(idx=2, image=_synthetic_frame_image(seed=31, shift_x=3)),