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>
Freezes the c1_vio Public API per
_docs/02_document/contracts/c1_vio/vio_strategy_protocol.md v1.0.0:
- VioStrategy Protocol (4 methods: process_frame, reset_to_warm_start,
health_snapshot, current_strategy_label) in
components/c1_vio/interface.py.
- DTOs (VioOutput, VioHealth, FeatureQuality, WarmStartPose) + VioState
enum in _types/nav.py — L1 placement so C5 + C13 consume them without
crossing the components.* boundary (AZ-270 AC-6). The new VioOutput
shape (frame_id: str, relative_pose_T: gtsam.Pose3,
pose_covariance_6x6, imu_bias, feature_quality, emitted_at_ns)
replaces the AZ-263 scaffolding in _types/vio.py, which is now
deleted.
- VioError family (VioInitializingError / VioDegradedError /
VioFatalError) in components/c1_vio/errors.py. Documented
rationale: the degraded-operation path returns a VioOutput with
inflated covariance + VioHealth.state=DEGRADED rather than raising
VioDegradedError — the error type exists only for the rare
degraded->fatal transition.
- C1VioConfig per-component config block (strategy enum,
lost_frame_threshold default 9, warm_start_max_frames default 5)
with constructor-time validation rejecting unknown strategy labels.
- StrategyNotAvailableError added to runtime_root/errors.py;
composition-time error distinct from the VioError family.
- Composition-root factory build_vio_strategy in
runtime_root/vio_factory.py with three BUILD_* gates (BUILD_OKVIS2,
BUILD_VINS_MONO, BUILD_KLT_RANSAC). Concrete strategy modules are
imported lazily via __import__ AFTER the flag check — Tier-0
workstation builds with the flag OFF MUST NOT load the strategy
module (Risk-2 / I-5; verifiable via sys.modules).
- 36 conformance tests cover all 9 ACs + NFR-perf-factory
(p99 build under 200 ms x 1000 calls) + NFR-reliability-error-family.
AC-8 introspects the contract file's Shape table and asserts method
parity against the runtime Protocol; AC-9 asserts the frame_id
annotation is 'str' (PEP-563 stringified).
C5 migration (consumers of the new VioOutput shape):
- gtsam_isam2_estimator.py + eskf_baseline.py: replaced
vio.timestamp -> vio.emitted_at_ns (drops _datetime_to_ns on the
VIO path), vio.pose_se3 -> vio.relative_pose_T (gtsam.Pose3 direct;
drops _pose_se3_to_gtsam / _pose_se3_to_array), vio.covariance_6x6
-> vio.pose_covariance_6x6 (rename).
- key_for_frame signature widened to UUID | int | str to accept the
new str frame_id.
- 4 C5 test files migrated to the new VioOutput shape with helper
fixtures producing ImuBias + FeatureQuality + str frame_id.
- c5_state/interface.py TYPE_CHECKING import path updated.
Bootstrap healthcheck + test_types_importable updated to drop the
deleted _types/vio module and pick up _types/inference (AZ-297) in
the same sweep.
Full unit-test sweep: 884 passed, 2 pre-existing environment skips
(cmake, actionlint).
Co-authored-by: Cursor <cursoragent@cursor.com>
Oleksandr Bezdieniezhnykh