# AZ-593 — AZ-333 Tier-2 validation: de-ROSified VINS-Mono upstream + binding + CI + Jetson

**Task**: AZ-593_AZ-333_tier2_validation
**Name**: AZ-333 Tier-2 validation bundle (VINS-Mono)
**Description**: Vendor upstream VINS-Mono (with ROS-strip layer), rewrite `_native/vins_mono_binding.cpp` against the real `Estimator` + `FeatureTracker` API, add the Linux CI apt-install block for the research matrix kind, validate against IT-12 comparative-study fixtures on Jetson hardware.
**Complexity**: 5 points (placeholder; likely 8+ if HKUST + ROS-strip path is chosen — re-size when scheduled)
**Dependencies**: AZ-333, AZ-276 (ImuPreintegrator), AZ-277 (SE3Utils), AZ-591 (compose_root per-binary bootstrap), AZ-592 (OKVIS2 Tier-2 — shares CMake / Eigen pin work)
**Component**: c1_vio (epic AZ-254 / E-C1)
**Tracker**: AZ-593
**Epic**: AZ-254 (E-C1)
**Status**: parked in `backlog/` — BLOCKED on Tier-2 prerequisites (see below)

## Problem

AZ-333 shipped the `VinsMonoStrategy` Python facade + `VinsMonoBackend` skeleton C++ binding (same defect pattern as AZ-332) and explicitly deferred the real estimator wiring. AZ-333's Implementation Notes named the follow-up `AZ-333_tier2_validation`.

The cycle-1 gate initially mis-classified AZ-333 as `FAIL` and created `AZ-590_remediate_vins_mono_estimator_wiring`. That ticket has been closed Won't Fix; this task replaces it with the correct scope.

**Additional blocker unique to AZ-593**: `cpp/vins_mono/upstream/` is referenced by `cpp/vins_mono/CMakeLists.txt` but **does not exist** — `.gitmodules` has no entry for it. The original AZ-333 task spec assumed a "de-ROSified VINS-Mono pin" exists; the user / team must pick the vendoring path.

## Outcome

1. **Upstream vendoring decision**: choose between
   - (a) Original HKUST `HKUST-Aerial-Robotics/VINS-Mono` (ROS1-locked). Requires in-tree ROS-strip configure-time hook. More work but no fork drift.
   - (b) A community de-ROSified fork (e.g., `Karaca-VINS-Mono` or `RonaldSun/vins-fusion-no-ros`). Less work but accepts external maintenance drift.

   The decision needs to be made BEFORE work starts. Document in `_docs/03_implementation/refactoring/vins_mono_upstream_choice.md` with the chosen pin commit hash and the rationale.

2. **Add submodule**: `git submodule add <chosen-url> cpp/vins_mono/upstream` against the pinned commit.

3. **ROS-stub layer** (only if option 1a): vendor minimal `cpp/_third_party/vins_mono_ros_stub/` providing the symbols VINS-Mono pulls from `roscpp` / `rosbag` / `std_msgs` / `sensor_msgs` without requiring a real ROS install. Pre-process upstream sources via CMake `configure_file` to redirect ROS headers to the stubs.

4. **C++ binding rewrite**: replace `_native/vins_mono_binding.cpp` skeleton with real `Estimator` + `FeatureTracker` wiring. API surface:
   - Construct `feature_tracker::FeatureTracker` + `vins_estimator::Estimator` after parsing `yaml_config_` via VINS-Mono's `readParameters()` / equivalent.
   - In `add_frame(image)`: call `feature_tracker_.readImage(image_8uc1, ts_seconds)`, retrieve the resulting feature observations, feed them into `estimator_.processImage(image_msg, header)` (mirroring the upstream `feature_tracker_node.cpp` / `estimator_node.cpp` flows but without ROS message types).
   - In `add_imu(ts, accel, gyro)`: `estimator_.processIMU(ts, alpha, omega)`.
   - Periodically (or per-frame) call `estimator_.processMeasurements(...)` and `estimator_.solveOdometry()` to drive the sliding-window optimisation.
   - Extract output: read `estimator_.Ps[WINDOW_SIZE]` (position), `estimator_.Rs[WINDOW_SIZE]` (rotation), `estimator_.Bas[WINDOW_SIZE]` / `estimator_.Bgs[WINDOW_SIZE]` (biases). Pose covariance from `estimator_.last_marginalization_info`.
   - Reset: `estimator_.clearState()` + `estimator_.setParameter()`.

5. **CMake glue**: extend `cpp/vins_mono/CMakeLists.txt` to link the upstream + stub libs against pinned Ceres + OpenCV ≥ 4.2 + Eigen ≥ 3.4. **Pin alignment**: ensure Eigen + Ceres pins match AZ-592 (OKVIS2 Tier-2) to avoid ABI conflict in the research binary which links both.

6. **CI workflow**: gate `BUILD_VINS_MONO=ON` on the `research` / `comparative-study` CI matrix kind only (NOT the airborne kind — `ci/sbom_diff.py` enforces). Apt deps overlap heavily with AZ-592 (Ceres, OpenCV, Eigen, SuiteSparse).

7. **Tier-1 integration test**: `tests/integration/c1_vio/test_az333_vins_mono_real_binding.py` with `@pytest.mark.skipif(not _vins_mono_binding_present())`.

8. **Tier-2 Jetson validation** (comparative-study against AZ-332 OKVIS2): runs IT-12 fixtures, owned by AZ-444 (Tier-2 Jetson harness).

## Prerequisites BLOCKED on

- **Upstream choice (user decision)**: HKUST + ROS-strip (option 1a) vs. community de-ROSified fork (option 1b).
- **AZ-591 landed first**: compose_root per-binary bootstrap so `c1_vio:vins_mono` is registered + reachable on the research binary.
- **AZ-592 landed first or in parallel**: shares Linux CI dep install + Eigen / Ceres pin alignment work.
- **Linux CI runner image with apt deps**: see AZ-592.
- **Jetson hardware**: for IT-12 comparative-study validation.

## Scope notes

- This task as written almost certainly exceeds 5pt. When Tier-2 work actually starts, split into:
  - `AZ-593a` — Upstream vendoring decision + ADR addendum + submodule add (2pt)
  - `AZ-593b` — ROS-stub layer (if option 1a) (5pt)
  - `AZ-593c` — C++ binding rewrite + CMake (5pt)
  - `AZ-593d` — Jetson IT-12 validation (5pt)
- The HKUST + ROS-strip path is the more conservative engineering choice (no fork drift, full upstream maintenance available), but it's also the larger effort. The fork path may be 1-2 weeks faster but introduces a maintenance dependency on a third-party fork.

## Notes

- Coordinate Eigen / Ceres pin work with AZ-592. Both link against Ceres + Eigen; the research binary links both AZ-592 and AZ-593 artifacts, so version mismatch = link-time segfault.
- Upstream VINS-Mono's `feature_tracker_node.cpp` and `estimator_node.cpp` are the reference for the binding's I/O flow. Strip the ROS message types and replace with the binding's `add_frame` / `add_imu` surface.
- `_docs/02_tasks/done/AZ-333_c1_vins_mono_strategy.md` documents the original deferral. Keep intact for audit; this task discharges that contract.
- `AZ-444` (Tier-2 Jetson harness) is the consumer of this task's binding artifact. AZ-444's IT-12 comparative-study runs require both OKVIS2 (AZ-592) and VINS-Mono (AZ-593) bindings to be working.