[AZ-228] [AZ-229] Add VIO and satellite sync boundaries

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 18:31:04 +03:00
parent 2db50bc124
commit 087f4dba27
13 changed files with 625 additions and 8 deletions
+90
View File
@@ -0,0 +1,90 @@
# 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.