[AZ-333] C1 VINS-Mono strategy — research-only comparative VIO

VinsMonoStrategy: Python facade conforming to AZ-331 Protocol; mirrors
the AZ-332 OKVIS2 facade so the AZ-331 factory + IT-12 comparative
harness can treat both as drop-in substitutable. Native binding is a
pybind11 skeleton compiled behind BUILD_VINS_MONO=ON (default OFF for
airborne / operator-tooling / replay-cli per module-layout.md
Build-Time Exclusion Map). Real vins_estimator wiring is the Tier-2
follow-up.

VinsMonoConfig added to c1_vio/config.py with sliding-window /
feature-tracker / marginalisation / opt-iteration knobs plus
__post_init__ validation; exported through the package __init__.

cpp/vins_mono/CMakeLists.txt replaces the AZ-263 placeholder with full
pybind11 wiring: Risk-1 mitigation forces VINS_MONO_USE_ROS=OFF;
Risk-2 mitigation links Eigen from the same cpp/_third_party/eigen pin
as OKVIS2; Risk-3 mitigation enforces BUILD_VINS_MONO=OFF in
deployment binaries via the gate at the top of the file.

Tests: 17 new in test_vins_mono_strategy.py (15 pass + 2 tier2 skip);
fake_vins_mono_binding fixture added to conftest.py mirroring the
fake_okvis2_binding pattern; test_protocol_conformance updated to drop
vins_mono from _STRATEGIES_WITHOUT_PY_MODULE so the existing
parametrised factory tests route through the new strategy.

Focused c1_vio suite: 72 passed, 4 skipped. Full suite: 1788 passed,
1 unrelated pre-existing flake (c12 cold-start perf, env-bound).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-14 01:11:09 +03:00
parent 2ce300ddb1
commit 6a5954bdae
13 changed files with 2056 additions and 15 deletions
@@ -0,0 +1,130 @@
# Batch 53 — Cycle 1 Report
**Date**: 2026-05-14
**Tasks**: AZ-333 (C1 VINS-Mono Strategy)
**Verdict**: COMPLETE — PASS_WITH_WARNINGS
## Summary
Implemented `VinsMonoStrategy`, the research-only loosely-coupled
comparative VIO that participates in the IT-12 comparative-study
research binary only. Mirrors the AZ-332 OKVIS2 facade pattern
deliberately so the AZ-331 factory can treat both strategies as
drop-in substitutable. Native binding is a pybind11 skeleton compiled
behind `BUILD_VINS_MONO=ON` (default OFF for airborne /
operator-tooling / replay-cli); estimator wiring is the Tier-2
follow-up.
## Files added / modified
### Added (4)
- `src/gps_denied_onboard/components/c1_vio/vins_mono.py` — Python
facade, 533 lines.
- `src/gps_denied_onboard/components/c1_vio/_native/vins_mono_binding.cpp`
— pybind11 binding skeleton, ~275 lines.
- `tests/unit/c1_vio/test_vins_mono_strategy.py` — AC-1..AC-10 +
tier2 perf/honesty tests, 518 lines, 17 tests (15 pass, 2 skip).
- `_docs/03_implementation/reviews/batch_53_review.md` — code review
report.
### Modified (4)
- `src/gps_denied_onboard/components/c1_vio/__init__.py` — export
`VinsMonoConfig`.
- `src/gps_denied_onboard/components/c1_vio/config.py` — add
`VinsMonoConfig` dataclass + `vins_mono` field on `C1VioConfig`;
`__all__` updated; `KNOWN_STRATEGIES` already had `vins_mono`.
- `cpp/vins_mono/CMakeLists.txt` — replaced AZ-263 placeholder with
full pybind11 + linker wiring; gated by `BUILD_VINS_MONO`; ROS-strip
flag forced OFF (Risk-1); links Eigen from
`cpp/_third_party/eigen/` shared with OKVIS2 (Risk-2).
- `tests/unit/c1_vio/conftest.py` — extend with `FakeVinsMonoBackend`
+ 3 fake exception types + `fake_vins_mono_binding` fixture.
- `tests/unit/c1_vio/test_protocol_conformance.py` — drop `vins_mono`
from `_STRATEGIES_WITHOUT_PY_MODULE` so the existing parametrised
factory test routes through the new strategy correctly (the
"module missing" branch is now strictly `klt_ransac`-only until
AZ-334 lands).
## AC coverage (AC-1..AC-10 + NFR-perf-document)
All 10 ACs mapped to passing tests (see `batch_53_review.md` Phase 2
table). AC-9 + NFR-perf are tier2-tagged per the carry-over plan;
they skip on macOS dev + GitHub Actions Linux runner with
`Tier-2-only test; set GPS_DENIED_TIER=2 to run`.
## Test results
### Focused suite — `tests/unit/c1_vio/`
```
72 passed, 4 skipped in 1.14s
```
The 4 skips are the 2 OKVIS2 tier2 tests + the 2 new VINS-Mono tier2
tests (`test_ac9_*` and `test_nfr_perf_*`).
### Adjacent regression — config / compose-root / inference shim
```
22 passed in 2.87s
```
(`test_az269_config_loader.py`, `test_az270_compose_root.py`,
`test_az507_inference_errors_shim.py` — all green; the new
`VinsMonoConfig` registration did not break the schema-loader or
compose-root layered-import guards.)
### Full suite
```
1 failed, 1788 passed, 82 skipped in 79.15s
```
The single failure is a pre-existing environment-dependent perf flake:
- `tests/unit/c12_operator_orchestrator/test_cli_console_script.py::test_cold_start_under_500ms_p99`
— measures CLI cold-start wall-clock; reports `worst-after-trim
997.4 ms` vs the `≤ 500 ms` NFR target. macOS dev runner cannot
hit this on a cold spawn; the test is environment-bound to Linux
CI hardware. No touchpoint to c1_vio. Reported to the user.
## Architectural decisions
- **Mirroring OKVIS2 1:1**: the constructor / state machine / except
ladder in `vins_mono.py` is a deliberate copy of `okvis2.py`. The
AZ-331 factory + IT-12 harness require shape-compatibility; doing
the consolidation now (before AZ-334's KltRansac shape is visible)
would over-fit. Tracked as Low-severity finding F1 in the review;
scheduled for the post-AZ-334 hygiene PBI (precedent: AZ-340 →
AZ-527 for c2_vpr).
- **Test fake mirroring**: same logic for `FakeVinsMonoBackend` vs
`FakeOkvis2Backend`. The shared `ScriptedOutput` dataclass and
`_make_default_payload` helper ARE reused (the productive cut);
the backend class duplication is the deferred-consolidation slice.
- **CMakeLists ROS-strip + Eigen pin**: explicit Risk-1 mitigation
(`VINS_MONO_USE_ROS=OFF` forced), Risk-2 mitigation (Eigen pin
from the shared `cpp/_third_party/eigen/`), Risk-3 mitigation (the
binding never builds when `BUILD_VINS_MONO=OFF`, so deployment
binaries stay clean).
- **Skeleton binding throws on first frame**: matches OKVIS2 — a
research binary that loads the `.so` before tier-2 wires the real
`vins_estimator::Estimator` cannot silently emit misleading poses
(`VinsMonoFatalException` from `_drive_estimator`).
- **NFR-perf is recorded, not bounded**: per task spec, VINS-Mono is
exempt from C1-PT-01's 80 ms p95. The tier2 perf test asserts only
that `process_frame` completes 200× without deadlock and that p95
is below a loose 5-second sanity ceiling. The Step 9 / E-BBT
comparative-study report consumes the actual p50/p95 number.
## Out of scope / deferred
- Real `vins_estimator::Estimator` wiring inside the binding — Tier-2
follow-up; not required for the AZ-333 facade ACs.
- KltRansac strategy (AZ-334) — separate batch.
- Warm-start hint persistence (AZ-335) — separate batch, depends on
AZ-333 + AZ-334.
- Strategy-facade consolidation hygiene PBI — informally tracked,
formal PBI to be raised by the next cumulative review (batches
52-54) once all three c1_vio strategies are landed.