[AZ-243] Sync native VIO test docs

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/02_document/architecture.md

@@ -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

@@ -16,17 +16,23 @@
 
 | Method | Input | Output | Async | Error Types |
 |--------|-------|--------|-------|-------------|
-| `initialize` | `VioInitRequest` | `VioInitResult` | No | `CalibrationInvalid`, `DatasetUnsupported` |
+| `initialize` | selected `VioBackend` / `VioRuntimeConfig` | updates `VioHealthReport` | No | backend initialization / native prerequisite errors |
-| `process` | `VioInputPacket` | `VioStatePacket` | Yes | `TrackingLost`, `TimestampMismatch` |
+| `process` | `VioInputPacket` | `VioProcessingResult` | No | timestamp mismatch, backend runtime errors |
-| `health` | none | `VioHealth` | No | none |
+| `health` | none | `VioHealthReport` | No | none |
 
 **Input DTOs**:
 
 ```yaml
 VioInputPacket:
   frame: FramePacket
-  imu_samples: list[TelemetrySample]
+  telemetry_samples: list[TelemetrySample]
-  attitude_sample: TelemetrySample optional
+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

@@ -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,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

@@ -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

@@ -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

@@ -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,8 +2,8 @@
 
 ## Current Step
 flow: greenfield
-step: 8
+step: 14
-name: Code Testability Revision
+name: Security Audit
 status: not_started
 tracker: jira
 sub_step: