# VIO Adapter

**Task**: AZ-228_vio_adapter
**Name**: VIO Adapter
**Description**: Wrap the selected relative VIO backend as a replaceable component with health and error behavior.
**Complexity**: 5 points
**Dependencies**: AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry, AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway
**Component**: VIO Adapter
**Tracker**: AZ-228
**Epic**: AZ-213

## Problem

The safety wrapper needs relative VIO state from calibrated frames and FC IMU without inheriting backend-specific internals.

## Outcome

- Backend initialization, processing, and health behavior are exposed through a replaceable adapter.
- Tracking loss and timestamp mismatch are explicit.
- The adapter never emits WGS84 coordinates or safety decisions.

## Scope

### Included
- Initialization and runtime health.
- Frame + IMU processing behavior.
- Relative pose/velocity/bias output and quality metadata.
- Native bridge boundary.

### Excluded
- Absolute anchor fusion and covariance authority.
- Satellite matching fallback implementation.

## Dependencies

### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/geometry_time_sync.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`

## Acceptance Criteria

**AC-1: VIO state emitted**
Given synchronized frame and IMU samples
When processing succeeds
Then a relative VIO state packet with tracking quality is emitted.

**AC-2: Timestamp mismatch is explicit**
Given frame/IMU timestamps are inconsistent
When processing is requested
Then the adapter rejects the packet with a timestamp mismatch error.

**AC-3: Health is observable**
Given initialization or tracking quality changes
When health is requested
Then the adapter reports current VIO readiness and degradation state.

## Non-Functional Requirements

**Performance**
- Adapter processing must be profiled against Jetson latency/memory limits.

**Reliability**
- Backend failures are surfaced, not hidden.

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid synchronized packet | VIO state emitted |
| AC-2 | Bad timestamp window | Explicit error |
| AC-3 | Tracking loss | Health reports degraded |

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Derkachi/public replay | Relative VIO path | Continuous estimates where data supports it | Performance |

## Constraints

- BASALT remains the current selected backend, but package and folder names must stay backend-neutral.
- The VIO adapter is not the safety authority.
- GPL VIO dependencies remain reference-only unless explicitly approved.

## Risks & Mitigation

**Risk 1: Nadir fixed-wing fit**
- *Risk*: The selected VIO backend underperforms on low-parallax terrain.
- *Mitigation*: Representative replay and reference comparisons gate acceptance.