azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-21 07:01:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-243] Sync native VIO test docs

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-07 01:04:01 +03:00
parent 2425f8e6fd
commit a8e7199f30
8 changed files with 40 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_document/architecture.md
+1
View File
@@ -88,6 +88,7 @@ Build a Jetson-hosted onboard localization pipeline for fixed-wing GPS-denied fl
| Secrets/signing | Local test keys | Mission/cache signing keys from Suite process |
| FDR | Local temp output | Per-flight bounded NVMe storage |
| MAVLink | SITL/replay | Physical FC telemetry link |
| VIO runtime | Explicit replay profile | Native BASALT-compatible runtime required; missing runtime blocks startup/readiness |
## 4. Data Model Overview
_docs/02_document/components/02_vio_adapter/description.md
+19 -6
View File
@@ -16,17 +16,23 @@
| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `initialize` | `VioInitRequest` | `VioInitResult` | No | `CalibrationInvalid`, `DatasetUnsupported` |
| `process` | `VioInputPacket` | `VioStatePacket` | Yes | `TrackingLost`, `TimestampMismatch` |
| `health` | none | `VioHealth` | No | none |
| `initialize` | selected `VioBackend` / `VioRuntimeConfig` | updates `VioHealthReport` | No | backend initialization / native prerequisite errors |
| `process` | `VioInputPacket` | `VioProcessingResult` | No | timestamp mismatch, backend runtime errors |
| `health` | none | `VioHealthReport` | No | none |
**Input DTOs**:
```yaml
VioInputPacket:
frame: FramePacket
imu_samples: list[TelemetrySample]
attitude_sample: TelemetrySample optional
telemetry_samples: list[TelemetrySample]
VioRuntimeConfig:
environment: development | ci | staging | jetson | production
mode: replay | native optional
native_backend_name: string
native_runner_module: string
native_runner_factory: string
native_runner_config: object
```
**Output DTOs**:
@@ -38,8 +44,12 @@ VioStatePacket:
velocity: vector3
bias_estimate: object optional
tracking_quality: number
completed: boolean
covariance_hint: matrix optional
VioProcessingResult:
state_packet: VioStatePacket optional
health: VioHealthReport
processing_latency_ms: number optional
error: ErrorEnvelope optional
```
## 3. Data Access Patterns
@@ -50,6 +60,8 @@ No persistent production data ownership. Reads calibration/config at startup and
**State Management**: Owns selected VIO backend runtime state and resets only through explicit wrapper command.
**Runtime Selection**: `create_vio_adapter` selects replay mode only for explicit development/replay configuration. Production and Jetson profiles derive native mode, instantiate `ConfiguredNativeVioBackend`, and load a BASALT-compatible runner through `BasaltNativeRunner`.
**Key Dependencies**:
| Library | Purpose |
@@ -58,6 +70,7 @@ No persistent production data ownership. Reads calibration/config at startup and
| Eigen/Sophus or backend-native math stack | Pose and transform representation |
**Error Handling Strategy**:
- Missing or invalid production native runtime prerequisites fail initialization with explicit health/error state and no replay-derived successful VIO output.
- Tracking loss is surfaced to the safety/anchor wrapper, not hidden.
- Timestamp/camera-IMU sync violations fail the packet and are logged.
- The adapter never emits WGS84 coordinates; absolute semantics belong to the wrapper.
_docs/02_document/contracts/shared/config_errors_telemetry.md
+3 -1
View File
@@ -2,7 +2,7 @@
**Component**: shared/config, shared/errors, shared/telemetry
**Producer task**: AZ-222 — AZ-222_runtime_config_errors_telemetry.md
**Consumer tasks**: AZ-223, AZ-224, AZ-225, AZ-226, AZ-227, AZ-228, AZ-229, AZ-230, AZ-231, AZ-232
**Consumer tasks**: AZ-223, AZ-224, AZ-225, AZ-226, AZ-227, AZ-228, AZ-229, AZ-230, AZ-231, AZ-232, AZ-243
**Version**: 1.0.0
**Status**: draft
**Last Updated**: 2026-05-03
@@ -19,6 +19,7 @@ Defines shared runtime configuration, error/result envelope, health, and telemet
| Error envelope | component, category, message, cause, retryability, severity |
| Health event | liveness/readiness status, dependency state, timestamp, component |
| Metrics labels | bounded component/action/status labels suitable for runtime reports |
| VIO runtime profile | production/Jetson VIO requires native mode; replay is explicit for development/replay checks |
## Invariants
@@ -41,6 +42,7 @@ Defines shared runtime configuration, error/result envelope, health, and telemet
| Case | Input | Expected | Notes |
|------|-------|----------|-------|
| missing-required-prod | production profile missing cache dir | readiness/startup failure | Clear error category |
| missing-native-vio-runtime | production VIO profile without installed native runtime | failed VIO health and explicit native runtime prerequisite error | No replay-derived success |
| secret-value | signing key ref present | only key ref logged | No secret leakage |
| component-error | component reports dependency failure | structured envelope emitted | FDR-safe |
_docs/02_document/contracts/shared/runtime_contracts.md
+2 -1
View File
@@ -2,7 +2,7 @@
**Component**: shared/contracts
**Producer task**: AZ-220 — AZ-220_shared_runtime_contracts.md
**Consumer tasks**: AZ-223, AZ-224, AZ-225, AZ-226, AZ-227, AZ-228, AZ-229, AZ-230, AZ-231, AZ-232
**Consumer tasks**: AZ-223, AZ-224, AZ-225, AZ-226, AZ-227, AZ-228, AZ-229, AZ-230, AZ-231, AZ-232, AZ-243
**Version**: 1.0.0
**Status**: draft
**Last Updated**: 2026-05-03
@@ -18,6 +18,7 @@ Defines the shared runtime DTO/event contract surface that component implementat
| `FramePacket` | frame ID, timestamp, image reference, calibration ID, occlusion, quality, normalization hint | camera, VIO, Satellite Service, Anchor Verification, Tile Manager, FDR |
| `TelemetrySample` | timestamp, IMU, attitude, altitude, airspeed, GPS health | MAVLink, VIO, safety wrapper, FDR |
| `VioStatePacket` | timestamp, relative pose, velocity, bias, tracking quality, covariance hint | VIO, safety wrapper, FDR |
| `VioProcessingResult` | optional VIO state, health report, latency, error envelope | VIO, safety wrapper, FDR |
| `PositionEstimate` | WGS84 coordinates, covariance, source label, fix type, horizontal accuracy, anchor age | safety wrapper, MAVLink, Tile Manager, FDR |
| `VprCandidate` | chunk ID, tile ID, score, footprint, freshness status | Satellite Service, Anchor Verification, FDR |
| `AnchorDecision` | candidate ID, acceptance result, estimated pose, inliers, MRE, rejection reason | Anchor Verification, safety wrapper, FDR |
_docs/02_document/ripple_log_cycle1.md
+6 -2
View File
@@ -2,7 +2,7 @@
## Scope
Task-mode documentation refresh for Cycle 1 test implementation tasks `AZ-233` through `AZ-239`, plus Step 11 replay-gate fixes.
Task-mode documentation refresh for Cycle 1 test implementation tasks `AZ-233` through `AZ-239`, Step 11 replay-gate fixes, and `AZ-243` native VIO runtime remediation.
## Ripple Analysis
@@ -11,7 +11,11 @@ Task-mode documentation refresh for Cycle 1 test implementation tasks `AZ-233` t
- `_docs/02_document/architecture.md` was refreshed because the validation harness responsibility now includes the implemented Docker replay smoke gate.
- `_docs/02_document/tests/environment.md` was refreshed because the replay harness entry points, output paths, and local-vs-Jetson gate behavior changed.
- `_docs/02_document/tests/*` and `_docs/02_document/tests/traceability-matrix.md` were refreshed during Step 12 to capture implementation-learned replay-smoke scenario IDs.
- `_docs/02_document/components/02_vio_adapter/description.md` was refreshed because `AZ-243` added production native runtime selection, explicit replay mode, and BASALT prerequisite errors.
- `_docs/02_document/contracts/shared/config_errors_telemetry.md` was refreshed because production VIO runtime mode is now a configuration/readiness invariant.
- `_docs/02_document/contracts/shared/runtime_contracts.md` was refreshed because `VioProcessingResult` is the public adapter result envelope consumed downstream.
- `_docs/02_document/architecture.md` was refreshed because environment-specific configuration now distinguishes explicit replay from production native VIO runtime.
## Import-Graph Result
No reverse-import product ripple was found or required. The replay harness imports product runtime modules only from tests; product runtime modules do not import the replay harness.
No reverse-import product ripple outside VIO was found. The replay harness imports product runtime modules only from tests; product runtime modules do not import the replay harness. `AZ-243` changed VIO public exports, so only VIO component docs and shared public-contract docs were refreshed.
_docs/02_document/tests/blackbox-tests.md
+4 -1
View File
@@ -64,6 +64,7 @@
- Derkachi replay fixture is mounted from `input_data/flight_derkachi/`.
- `flight_derkachi.mp4` is readable as cropped nadir video: 880 x 720, 30 fps, approximately 490.07 s.
- `data_imu.csv` contains monotonic 10 Hz `Time`, `timestamp(ms)`, `SCALED_IMU2.*`, and `GLOBAL_POSITION_INT.*` fields for 4,900 rows.
- Production or Jetson VIO profile is configured for native mode; replay mode is allowed only for explicit development replay checks.
- Camera intrinsics, lens distortion, and camera-to-body transform are either pinned or the run is marked as calibration-limited.
- Public synchronized dataset slice remains useful for calibrated final comparison. Strongest candidates: MUN-FRL, ALTO, EPFL fixed-wing, Kagaru; EuRoC/UZH FPV are proxy-only.
@@ -76,8 +77,10 @@
| 3 | Compare output trajectory to `GLOBAL_POSITION_INT` lat/lon/alt/heading | Error, covariance, source label, and anchor age are reported per segment |
| 4 | Compare calibrated public/representative replay against ground truth when available | BASALT + wrapper does not materially under-report uncertainty relative to error |
| 5 | Compare against OpenVINS reference replay when available | BASALT + wrapper does not materially under-report uncertainty relative to error |
| 6 | Start with production VIO profile when the BASALT-compatible runtime is not installed | System reports an explicit native runtime prerequisite error and emits no replay-derived successful VIO state |
| 7 | Start with explicit development replay profile | Replay VIO behavior is available only through the explicit replay profile and cannot satisfy production native-mode checks |
**Expected outcome**: Derkachi replay is accepted as a synchronized representative fixture and produces continuous estimates for >95% of normal overlapping frames. Absolute geolocation and covariance pass/fail thresholds are calibration-gated until camera intrinsics, distortion, and camera-to-body transform are pinned. For calibrated datasets, VO homography MRE is <1.0 px where homography validation is applicable.
**Expected outcome**: Derkachi replay is accepted as a synchronized representative fixture and produces continuous estimates for >95% of normal overlapping frames when native prerequisites are available. Missing native runtime prerequisites block production VIO with an explicit error rather than replay success. Absolute geolocation and covariance pass/fail thresholds are calibration-gated until camera intrinsics, distortion, and camera-to-body transform are pinned. For calibrated datasets, VO homography MRE is <1.0 px where homography validation is applicable.
**Max execution time**: Dataset-dependent, but replay must report per-frame latency.
_docs/02_document/tests/traceability-matrix.md
+3
View File
@@ -89,6 +89,9 @@
| AZ-239 AC-2 | Thermal/power endurance is validated or blocked with reason | NFT-RES-LIM-02, NFT-RES-LIM-INFRA | Covered |
| AZ-239 AC-3 | FDR rollover behavior is validated | NFT-RES-LIM-04 | Covered |
| AZ-239 AC-4 | Resource/endurance evidence artifacts are complete | NFT-RES-LIM-01, NFT-RES-LIM-02, NFT-RES-LIM-04, NFT-RES-LIM-INFRA | Covered |
| AZ-243 AC-1 | Production VIO profile selects native runtime path | FT-P-03 | Covered |
| AZ-243 AC-2 | Missing native runtime prerequisite fails closed with explicit error | FT-P-03 | Covered |
| AZ-243 AC-3 | Replay mode remains explicit and cannot satisfy production native checks | FT-P-03 | Covered |
## Coverage Summary
_docs/_autodev_state.md
+2 -2
View File
@@ -2,8 +2,8 @@
## Current Step
flow: greenfield
step: 8
name: Code Testability Revision
step: 14
name: Security Audit
status: not_started
tracker: jira
sub_step: