feat(sdk): R-IEKF system-level NEES verdict via the VioEstimator front-end (#347)

[Ravenwater]

Why

The R-IEKF observability fix (epic #347) is unit-proven and merged — SE2(3) state (#353), invariant propagation (#354), invariant camera update (#356), and MsckfInvariantBackend (#357). Each piece annihilates / preserves the 4-DoF unobservable gauge (global translation + gravity-yaw) by construction, at any state, with no FEJ.

What's missing is a trustworthy system-level verdict: does that unit-level fix actually yield a consistent filter end to end?

The current attempt — the hand-rolled Monte-Carlo loop in tools/src/invariant_nees_verdict.cpp (#360) — is broadly over-confident, but the attitude split shows why: yaw ≈ 7× vs roll/pitch ≈ 3400×. Roll/pitch is gravity-observable and cannot leak yaw, so the over-confidence is driver over-fusion / marginal stability in the hand-rolled loop (clone correlation, relinearization, triangulation at drifted poses), not a failure of the observability fix. The loop is the confounder.

Goal

Drive MsckfInvariantBackend through the validated VioEstimator front-end / track manager (the same path the body-frame filter and tests/sdk/vio_euroc.cpp use) instead of the hand-rolled loop, and produce a gauge-anchored attitude-NEES verdict that is trustworthy.

Scope

• Adapter: implement a VioBackend-conforming wrapper around MsckfInvariantBackend so VioEstimator can drive it — initialize (seed nav + prior), process_imu (propagate), process_camera (augment clone, run the existing track lifecycle, triangulate, invariant_update on tracks leaving the window), and expose NavState + covariance for the consistency harness.
• Reuse the track manager: the over-fusion in the hand-rolled loop must be avoided by reusing the validated feature-track lifecycle / triangulation / clone-window management (either a thin adapter over the front-end, or factor the body-frame backend's track lifecycle into a shared component both backends use — author's choice).
• Measure: run the gauge-anchored NEES machinery (eval/nav_consistency.hpp, consistency.hpp) on the assembled invariant filter over the synthetic Monte-Carlo (CI-runnable; real EuRoC is env-gated), reporting full-nav NEES, per-block NEES, and the yaw vs roll/pitch attitude split (the discriminator).

Acceptance criteria

• The invariant backend is driven by the real front-end / track manager — no hand-rolled update loop.
• Gauge-anchored attitude-NEES is reported, alongside the body-frame baseline on the same data, with the yaw-vs-roll/pitch split.
• Verdict, one of:
  • attitude-NEES lands near consistent (≈ dof) → the R-IEKF fix is confirmed end-to-end ⇒ flip the default backend and close out the NEES over-confidence; or
  • the residual over-confidence is localized to a specific, named cause (with a follow-up issue), and the result is documented.

Out of scope

• The observability math itself (proven; do not re-derive).
• A real-EuRoC-only verdict (env-gated, not CI-runnable) — the synthetic Monte-Carlo with the EuRoC camera model is the proxy.

References

• Epic epic(sdk): Right-Invariant EKF (R-IEKF) backend — fix the #212 yaw observability leak by construction #347 (R-IEKF); merged pieces feat(math): add SE2(3) extended-pose Lie group — the R-IEKF state manifold (#347) #353 / feat(sdk): add the R-IEKF invariant IMU propagation on SE2(3) (#347) #354 / feat(sdk): add the R-IEKF invariant camera measurement update (#347) #356 / feat(sdk): wire the MsckfInvariantBackend (R-IEKF filter) (#347) #357.
• Diagnostic chore(tools): add the R-IEKF system-level NEES diagnostic (#212) #360 (tools/src/invariant_nees_verdict.cpp) — the localization that motivates this.
• FEJ was refuted by measurement (feat(sdk): First-Estimates Jacobians (FEJ) — fix the yaw null-space leak / NEES over-confidence (#212) #339 / fix(sdk): first-estimates Jacobians for MSCKF observability consistency (#212 root cause) #280, closed) — this is the chosen alternative path.
• Note: the original fix(sdk): reduce MSCKF translation drift on EuRoC (RPE ~18%) #212 (translation drift / RPE) is itself closed; this targets the NEES over-confidence tracked under that number.

[Ravenwater]

Progress (2026-06-14) — adapter built, the verdict localized a real bug

The adapter InvariantVioBackend (#PR) drives MsckfInvariantBackend through the validated body-frame track lifecycle (MsckfBackend::process_camera), so the verdict is measured through correct fusion — not the hand-rolled loop (#360).

Driving it end to end answers "is the R-IEKF fix real end-to-end?" with: not yet — the invariant measurement update is harmful in the assembled continuous filter.

run	RMS pos err (synthetic)
pure propagation, no update	~15 m (expected dead-reckoning)
with the invariant update	~160 m (~10× worse)

The update being worse than no-update rules out track management (mirrors the validated lifecycle), geometry (more feature transit → worse), and propagation (no-update is fine). Since the measurement H's nav columns are zero, the nav is corrected entirely through the nav↔clone cross-covariance — so the bug is a cross-cov / SE2(3)-retraction convention error the unit tests miss (they use a fresh covariance + single update, no continuous propagate→update→retract loop).

Filed #366 for the fix (finite-difference-validate the joint EKF step over multiple cycles). The verdict (this issue) can't resolve until #366 lands — the integration is ready; the update math needs the convention bug fixed first.