# C1 VINS-Mono Strategy — Research-Only Comparative VIO

**Task**: AZ-333_c1_vins_mono_strategy
**Name**: C1 VINS-Mono Strategy
**Description**: Implement `VinsMonoStrategy`, the research-only `VioStrategy` that participates in the IT-12 comparative-study build only. The class is a Python facade over the VINS-Mono C++ loosely-coupled VIO core (sliding-window optimizer with separate IMU pre-integration thread) accessed via a pybind11 wrapper around `cpp/vins_mono/`. Build-time gated by `BUILD_VINS_MONO`; not present in any deployment-bound binary (airborne / operator-tooling / replay-cli all OFF; only research is ON per `module-layout.md` Build-Time Exclusion Map). MRE p95 < 1 px frame-to-frame is **not** required of VINS-Mono per the C1 component's `tests.md` (only Okvis2 + KltRansac are bound by AC-2.2); VINS-Mono is exempt as research-only.
**Complexity**: 5 points
**Dependencies**: AZ-331_c1_vio_strategy_protocol, AZ-263_initial_structure, AZ-269_config_loader, AZ-266_log_module, AZ-276_imu_preintegrator, AZ-277_se3_utils, AZ-272_fdr_record_schema, AZ-273_fdr_client_ringbuf
**Component**: c1_vio (epic AZ-254 / E-C1)
**Tracker**: AZ-333
**Epic**: AZ-254 (E-C1)

### Document Dependencies

- `_docs/02_document/contracts/c1_vio/vio_strategy_protocol.md` — the Protocol this task implements; produced by AZ-331.
- `_docs/02_document/contracts/shared_helpers/imu_preintegrator.md` — IMU substrate (AZ-276).
- `_docs/02_document/contracts/shared_helpers/se3_utils.md` — SE(3) ↔ pose-matrix utilities (AZ-277).
- `_docs/02_document/components/01_c1_vio/description.md` — § 5 implementation details + § 6 helpers; § 7 caveats note VINS-Mono is research-only.
- `_docs/02_document/components/01_c1_vio/tests.md` — § Component-Internal Tests note "VinsMono is research-only and exempt from MRE bound (only IT-12 comparative-study coverage)" (C1-IT-04).

## Problem

Without `VinsMonoStrategy`:

- The IT-12 comparative-study scenario (Mode B FT-P-04 / FT-P-05) cannot run all three VIO backends side-by-side; the research binary's purpose collapses to OKVIS2 + KltRansac only.
- Independent verification that OKVIS2 outperforms a comparable open-source loosely-coupled VIO on the Derkachi fixture has no producer; future architectural decisions to swap the production-default VIO have no comparative basis.
- The composition root's three-strategy switch is asymmetric — adding a fourth strategy in a future cycle would require revisiting the factory pattern instead of simply adding a fourth lazy branch.
- Consumers of `VioOutput` (C5 fusion) would have to be re-validated against a smaller dataset of behaviours; cross-strategy contract tests (deferred to Step 9 / E-BBT) lose a third data point.

This task delivers the comparative-research third strategy. Production binaries do NOT link it; only the IT-12 research binary loads it via `BUILD_VINS_MONO=ON`.

## Outcome

- A `VinsMonoStrategy` class at `src/gps_denied_onboard/components/c1_vio/vins_mono.py` conforming to the `VioStrategy` Protocol from AZ-331; `current_strategy_label() == "vins_mono"`.
- A pybind11 wrapper at `src/gps_denied_onboard/components/c1_vio/_native/vins_mono_binding.cpp` exposing the VINS-Mono C++ estimator (`vins_estimator::Estimator` or equivalent in the pinned upstream HEAD) to Python. The wrapper is built by CMake under `cpp/vins_mono/` (build-time gated by `BUILD_VINS_MONO`); the resulting `.so` is imported lazily inside `vins_mono.py`.
- Constructor `__init__(self, *, calibration: CameraCalibration, preintegrator: ImuPreintegrator, fdr_client: FdrClient, logger: Logger, config: VinsMonoConfig)` — all dependencies constructor-injected per ADR-009. `VinsMonoConfig` (`@dataclass(frozen=True)`) carries the VINS-Mono-specific knobs (sliding-window size, feature tracker thresholds, marginalisation strategy, max optimisation iterations) loaded from `config.vio.vins_mono.*` via AZ-269.
- `process_frame(frame, imu, calibration) -> VioOutput`:
  1. Append IMU samples to the injected `ImuPreintegrator` (strict-monotonic guarded; `ImuPreintegrationError` rewraps to `VioFatalError`).
  2. Feed the nav-camera frame to VINS-Mono via the pybind11 `add_image` wrapper.
  3. If VINS-Mono emits a new estimator update, extract the relative pose (SE(3) via `helpers.se3_utils`), the 6×6 covariance from VINS-Mono's marginalised information matrix, the latest IMU bias, and the feature-quality summary.
  4. Build and return `VioOutput` with `frame_id` echoed.
- `reset_to_warm_start(hint)`: tears down the current VINS-Mono estimator instance, constructs a fresh one, seeds the IMU bias and initial pose from `hint`. The next `config.vio.warm_start_max_frames` frames are allowed to converge before the strategy reports `state == TRACKING`.
- `health_snapshot()` returns `VioHealth(state, consecutive_lost, bias_norm)` derived from VINS-Mono's internal initialiser flag and feature-tracker health: `INIT` until the SfM bootstrap succeeds, `TRACKING` while the optimisation converges, `DEGRADED` when feature count drops below `config.vio.vins_mono.degraded_feature_threshold` or the marginalised information matrix's smallest eigenvalue drops below threshold, `LOST` after `config.vio.lost_frame_threshold` consecutive failed updates.
- The honest-covariance invariant is enforced behaviourally as in OKVIS2: VINS-Mono's marginalised covariance is read directly with no client-side floor or smoother.
- Error envelope is closed: every VINS-Mono / pybind11 / Eigen / Ceres exception is caught and rewrapped into the `VioError` family.
- All FDR records emitted via the injected `FdrClient` use the `kind="vio.health"` schema from AZ-272.

## Scope

### Included

- `VinsMonoStrategy` class implementation + the `VinsMonoConfig` dataclass + the `_native/vins_mono_binding.cpp` pybind11 wrapper.
- CMake target under `cpp/vins_mono/` that links the VINS-Mono upstream pin (BSD-3-Clause-style ROS license) and produces the binding `.so`. Build flag `BUILD_VINS_MONO`; default OFF for airborne / operator-tooling / replay-cli.
- The full `process_frame` / `reset_to_warm_start` / `health_snapshot` / `current_strategy_label` surface conforming to AZ-331's Protocol.
- IMU substrate via the constructor-injected `ImuPreintegrator` (AZ-276).
- Honest-covariance reading from VINS-Mono's marginalised information matrix.
- Lazy import of the `_native` binding inside `vins_mono.py`.
- Per-frame DEBUG log gated by `config.vio.per_frame_debug_log` (default OFF).
- WARN / ERROR / INFO logging per description.md § 9.
- Health-state transitions emitted as FDR records.
- Composition-root wiring (entry to the AZ-331 `build_vio_strategy` factory's `vins_mono` branch).
- VINS-Mono upstream's ROS dependency (if any) MUST be stripped or vendored — VINS-Mono historically ships as a ROS package; this task uses an upstream pin that has been de-ROSified (e.g., the `vins-mono-no-ros` community port) OR vendors only the `vins_estimator` / `feature_tracker` cores. The decision (which upstream to pin) is recorded as an ADR addendum if not already covered by Plan-phase pin selection.

### Excluded

- OKVIS2 strategy — separate task in this epic.
- KLT/RANSAC simple-baseline strategy — separate task in this epic.
- Warm-start hint persistence — separate task in this epic.
- C5 fusion of `VioOutput` — owned by E-C5.
- C13 FDR writer-thread — owned by E-C13.
- IMU preintegration mathematics — owned by AZ-276.
- The C1-IT-01..06 / C1-PT-01 tests themselves — deferred to Step 9 (E-BBT). Note: AC-2.2 MRE bound is exempt for VINS-Mono per `tests.md`.
- The IT-12 comparative-study harness — owned by suite-level test harness (Step 9 / E-BBT or test-spec extension).
- VINS-Mono upstream-source modifications beyond ROS-stripping — bug fixes upstream require a separate ADR.
- Multi-camera VINS-Mono — out of scope.

## Acceptance Criteria

**AC-1: `current_strategy_label()` returns `"vins_mono"`**
Given a `VinsMonoStrategy` constructed via the AZ-331 factory with `config.vio.strategy = "vins_mono"`
When `current_strategy_label()` is called
Then the returned string is exactly `"vins_mono"`

**AC-2: `process_frame` returns `VioOutput` with `frame_id` echoed**
Given a `NavCameraFrame` with `frame_id = "uuid-xyz"` and a populated `ImuWindow`
When `process_frame(frame, imu, calibration)` is called and reaches a successful estimator update
Then the returned `VioOutput.frame_id == "uuid-xyz"`; `pose_covariance_6x6` is symmetric and positive-definite; `imu_bias` is non-`None`

**AC-3: `process_frame` rewraps every backend exception into `VioError`**
Given a malformed input that triggers a VINS-Mono / pybind11 / Eigen / Ceres exception inside the backend
When `process_frame` is called
Then the raised exception is one of `VioInitializingError` / `VioDegradedError` / `VioFatalError`; the original exception is chained via `raise ... from`; no raw backend exception leaks

**AC-4: `reset_to_warm_start` clears state and seeds the hint**
Given a strategy with N processed frames
When `reset_to_warm_start(hint)` is called with a known `hint.bias` and `hint.body_T_world`
Then the next `process_frame` call's `VioOutput.imu_bias` reflects `hint.bias` (within numerical tolerance); calling `reset_to_warm_start` a second time without intervening frames does not raise

**AC-5: `health_snapshot()` reports `INIT` until SfM bootstrap completes**
Given a freshly-constructed strategy
When `health_snapshot()` is called before VINS-Mono's SfM bootstrap has succeeded
Then `state == INIT`; once bootstrap completes (typically 10–20 frames per VINS-Mono behaviour), the next `health_snapshot()` returns `state == TRACKING`

**AC-6: `health_snapshot()` reports `DEGRADED` on feature loss**
Given a strategy in TRACKING state
When `process_frame` is fed a frame with feature count below `config.vio.vins_mono.degraded_feature_threshold` or with the marginalised information matrix's smallest eigenvalue below threshold
Then the returned `VioOutput.pose_covariance_6x6` Frobenius norm is strictly greater than the prior frame's; the next `health_snapshot()` returns `state == DEGRADED`; the strategy MUST emit a `VioOutput` (not raise)

**AC-7: Sustained loss raises `VioFatalError`**
Given a strategy in DEGRADED state
When `config.vio.lost_frame_threshold` consecutive frames fail to update
Then the next `process_frame` call raises `VioFatalError`; subsequent `health_snapshot()` returns `state == LOST`

**AC-8: `BUILD_VINS_MONO=OFF` does not import VINS-Mono native libs**
Given the airborne / operator-tooling / replay-cli binary built with `BUILD_VINS_MONO=OFF`
When `gps_denied_onboard.components.c1_vio` is imported
Then `sys.modules` does NOT contain `gps_denied_onboard.components.c1_vio.vins_mono` or any `_native.vins_mono_binding` entry; AZ-331's factory raises `StrategyNotAvailableError("vins_mono", missing_flag="BUILD_VINS_MONO")` if `vins_mono` is requested

**AC-9: Honest covariance — no shrinkage during DEGRADED**
Given a controlled-degradation 60 s synthetic input
When `process_frame` runs through the degradation event
Then `||pose_covariance_6x6||_F` is monotonically non-decreasing from the moment `health_snapshot().state` first transitions to `DEGRADED` until either `TRACKING` is restored or `LOST` is reached

**AC-10: FDR `vio.health` records emitted on every state transition**
Given the strategy is configured with a real `FdrClient` (or test double)
When `health_snapshot().state` transitions
Then exactly one FDR record with `kind="vio.health"` and the new state is emitted; no records on steady-state frames

## Non-Functional Requirements

**Performance**
- Per-frame latency budget: VINS-Mono is research-only and is NOT bound by C1-PT-01's ≤ 80 ms p95 target. Document VINS-Mono's actual p95 in the Step 9 / E-BBT comparative-study report (no hard threshold).
- Throughput: best-effort; expected to operate at 3 Hz on Tier-2 in the research binary but no failure threshold this cycle.
- CPU / memory: best-effort within the research binary's overall budget (research binary is not deployed; resource limits are looser).

**Compatibility**
- VINS-Mono upstream HEAD (de-ROSified port) pinned per Plan-phase. Upstream-source modifications beyond the ROS-strip require an explicit ADR addendum.
- pybind11 / Eigen / Ceres versions match the OKVIS2 build to avoid ABI conflicts inside the same research binary.

**Reliability**
- Error envelope closed at the `VioError` family; no raw VINS-Mono / Ceres / Eigen exceptions cross the Python boundary.
- Single-threaded by Protocol contract; one instance per camera ingest thread inside the research binary.
- AC-2.2 MRE bound is **exempt** per `tests.md` C1-IT-04 — VINS-Mono is research-only; no per-frame MRE assertion in this task's tests.

**Concurrency**
- One `VinsMonoStrategy` instance per research-binary camera ingest thread.

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| AC-1 | `current_strategy_label()` after factory build with `vins_mono` config | Returns `"vins_mono"` |
| AC-2 | `process_frame` with a fixture frame + IMU window | `VioOutput.frame_id` echoed; covariance SPD; `imu_bias` non-None |
| AC-3 | Inject a malformed frame that triggers a backend exception (mocked binding) | `VioError`-family exception raised; original chained via `__cause__` |
| AC-4 | `reset_to_warm_start` then `process_frame` × N | Bias reflects hint; second `reset_to_warm_start` does not raise |
| AC-5 | Cold construct → process N frames | `INIT` until SfM bootstrap completes; then `TRACKING` |
| AC-6 | Feed degraded fixture | Covariance Frobenius norm strictly increases; `health_snapshot` returns `DEGRADED`; `VioOutput` IS emitted |
| AC-7 | `lost_frame_threshold` consecutive failed frames | `VioFatalError` on next `process_frame`; `health_snapshot` returns `LOST` |
| AC-8 | `BUILD_VINS_MONO=OFF` import + factory call | Module not in `sys.modules`; factory raises `StrategyNotAvailableError` |
| AC-9 | 60 s controlled-degradation synthetic | Covariance Frobenius norm monotonically non-decreasing during DEGRADED window |
| AC-10 | Real / fake `FdrClient` spy through state transitions | Exactly one `vio.health` record per transition |
| NFR-reliability-error-envelope | Raise each backend exception type via mock | All caught and rewrapped to `VioError` family |
| NFR-perf-document | Microbench `process_frame` on Derkachi fixture (research binary) | Document p50/p95 in the Step 9 comparative-study report (no hard threshold) |

## Constraints

- This task implements (does NOT define) the AZ-331 Protocol; signature mismatch is a Spec-Gap finding (High) at code-review.
- The pybind11 binding lives under `_native/` per `module-layout.md`; lazy-imported inside `vins_mono.py`.
- VINS-Mono native source lives under `cpp/vins_mono/` per `module-layout.md` rule #4. The chosen upstream MUST be ROS-free at the source level (either upstream port or in-tree ROS-strip).
- The strategy MUST consume IMU via the AZ-276 `ImuPreintegrator` helper; constructing a second IMU integration path is forbidden.
- This task introduces no new third-party dependencies beyond VINS-Mono + pybind11 + Eigen + Ceres (the Ceres dependency is unique to VINS-Mono among the three strategies; it is pinned via `cpp/vins_mono/CMakeLists.txt` and excluded from airborne / operator-tooling / replay-cli builds because `BUILD_VINS_MONO=OFF` for those binaries).
- Per-frame DEBUG logging defaults OFF.
- The strategy MUST NOT apply a covariance floor or smoother on the read path.
- AC-2.2 MRE bound is exempt per the C1 component's `tests.md`; the test task in Step 9 / E-BBT will configure C1-IT-04 to exclude VINS-Mono.

## Risks & Mitigation

**Risk 1: VINS-Mono upstream ships as a ROS package and ROS deps leak into the research binary**
- *Risk*: A naive vendored VINS-Mono pulls in `roscpp`, `rosbag`, etc., bloating the research binary and creating a build-time mess.
- *Mitigation*: The chosen upstream pin is a de-ROSified community port (or in-tree ROS-strip applied during the CMake build under `cpp/vins_mono/`). If a clean port does not exist at Plan-phase pin time, this task's Plan-phase decision records the chosen approach; CI's research-binary SBOM step asserts no ROS package leaks.

**Risk 2: Ceres + Eigen ABI conflict with OKVIS2's Eigen pin**
- *Risk*: VINS-Mono uses Ceres (for nonlinear optimisation); OKVIS2 also uses Eigen heavily. ABI mismatch between the two builds in the same binary produces silent corruption.
- *Mitigation*: Both `cpp/okvis2/CMakeLists.txt` and `cpp/vins_mono/CMakeLists.txt` link the same Eigen pin from `cpp/_third_party/eigen/`. The research binary's CMake build is the only place both load simultaneously; CI's research build asserts the linked Eigen version with `ldd`-style introspection.

**Risk 3: `BUILD_VINS_MONO=ON` accidentally enabled in a deployment binary**
- *Risk*: A misconfigured build flag could ship VINS-Mono to a deployed Jetson, blowing the binary size and adding an attack surface.
- *Mitigation*: `module-layout.md` Build-Time Exclusion Map locks `BUILD_VINS_MONO=OFF` for airborne / operator-tooling / replay-cli; CI's per-binary SBOM diff (`ci/sbom_diff.py`) fails if `vins_mono` appears in any non-research SBOM. The composition root validator additionally raises `ConfigurationError` at startup if `config.vio.strategy="vins_mono"` is requested in the airborne binary.

**Risk 4: VINS-Mono's loosely-coupled covariance is over-confident vs OKVIS2's tightly-coupled**
- *Risk*: The IT-12 comparative study could mislead an architect into picking VINS-Mono if its covariance under-reports.
- *Mitigation*: AC-9 honest-covariance enforcement applies to VINS-Mono too; the IT-12 report (Step 9 / E-BBT) compares calibrated covariances side-by-side; D-C5-5 captures the architectural decision that production stays on OKVIS2.

## Runtime Completeness

- **Named capability**: VINS-Mono loosely-coupled VIO + sliding-window optimisation + marginalised information matrix → 6×6 covariance (architecture / E-C1 / `solution.md` "research-only IT-12 comparative-study" / D-C5-3 sliding window context).
- **Production code that must exist**: real `VinsMonoStrategy` class implementing the AZ-331 Protocol; real pybind11 binding to `cpp/vins_mono/` (real VINS-Mono upstream, de-ROSified); real per-frame estimator update; real covariance read from VINS-Mono's marginalised information matrix; real bias propagation through AZ-276.
- **Allowed external stubs**: tests MAY use a fake pybind11 binding that returns scripted `VioOutput` payloads (AC-3 / AC-6 / AC-7); production wiring (research binary only) uses the real VINS-Mono upstream.
- **Unacceptable substitutes**: a pure-Python VINS-Mono re-implementation (would defeat the whole point of comparative study); skipping the AZ-276 `ImuPreintegrator` (would break the single-IMU-truth invariant); a covariance floor on the read path; shipping VINS-Mono in a deployment binary by default.
