feat(tools): real-data observability / null-space-leak diagnostic

[Ravenwater]

Summary

Adds obs_inspect, the real-data companion to the synthetic observability_probe (#337). It localizes the #212 over-confidence to the yaw gauge on real EuRoC data — the first per-update measurement of the null-space leak on a real sequence.

What it measures

A monocular VIO has a 4-DoF unobservable gauge — global translation (3) + rotation-about-gravity, yaw (1). A consistent filter must never gain information along it: the stacked camera Jacobian must annihilate the gauge, ‖H·N‖ ≈ 0. That holds only at a single consistent linearization; a standard EKF re-linearizes each clone at its own drifted estimate, so the gauge leaks and the filter fabricates information → over-confidence.

obs_inspect taps every MSCKF update, drives the shipped CameraUpdater::projection_jacobians over the live clone window + triangulated feature, and reports two leaks per update:

• consistent (H, N at the same estimate) — the gauge-annihilation sanity check, must be ~machine-ε;
• real (H perturbed by the filter's own per-clone σ from P, N at the unperturbed gauge) — the synthetic σ-sweep evaluated at the uncertainty the filter actually claims.

Measured result (V2_03_difficult, 2,918 updates)

	value	meaning
consistent leak	yaw 1.75e-15, trans 0	shipped Jacobian is correct (not a code bug)
translation leak (real)	exactly 0	structurally protected (±Hf cancellation)
yaw leak (real)	mean 0.39, 100% of updates leak	over-confidence enters the yaw gauge
yaw leak vs clone σθ	0.12 → 0.19 → 0.63 as σθ → [2°,…)	grows with the window's attitude drift

→ localizes #212 to yaw, pointing at the right-invariant (R-IEKF) fix (estimate-independent gauge directions).

Changes

• tools/include/branes/tools/observability_inspect.hpp — testable core (build_H/build_N/leak), fully-qualified types so it composes with the backend headers (no using namespace Vec3-ambiguity).
• tools/src/obs_inspect.cpp — EuRoC driver (read-only, not a CI gate).
• tests/tools/observability_inspect.cpp — gates the gauge property on a constructed clone window.
• tools/README.md — entry + section.

Test Results

Target	gcc build	gcc test	clang build	clang test
observability_inspect	OK	PASS (6 assertions / 2 cases)	OK	PASS (6 / 2)
obs_inspect	OK	(developer tool)	—	—

Test plan

• Fast CI passes (gcc + clang + MSVC + lint)
• Promote to ready when satisfied

Relates to #212, #337

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8c222a9f-9c0e-4957-9c2b-be3c693ac78d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch diag/obs-inspect-observability-leak

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}