diff --git a/_docs/02_document/architecture.md b/_docs/02_document/architecture.md index 6d62957..f094234 100644 --- a/_docs/02_document/architecture.md +++ b/_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 diff --git a/_docs/02_document/components/02_vio_adapter/description.md b/_docs/02_document/components/02_vio_adapter/description.md index 8c03d3a..a3b6b74 100644 --- a/_docs/02_document/components/02_vio_adapter/description.md +++ b/_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` | -| `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. diff --git a/_docs/02_document/contracts/shared/config_errors_telemetry.md b/_docs/02_document/contracts/shared/config_errors_telemetry.md index fdb669a..cdb689f 100644 --- a/_docs/02_document/contracts/shared/config_errors_telemetry.md +++ b/_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 | diff --git a/_docs/02_document/contracts/shared/runtime_contracts.md b/_docs/02_document/contracts/shared/runtime_contracts.md index cf80353..78d67ce 100644 --- a/_docs/02_document/contracts/shared/runtime_contracts.md +++ b/_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 | diff --git a/_docs/02_document/ripple_log_cycle1.md b/_docs/02_document/ripple_log_cycle1.md index 0e9056e..929bba9 100644 --- a/_docs/02_document/ripple_log_cycle1.md +++ b/_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. diff --git a/_docs/02_document/tests/blackbox-tests.md b/_docs/02_document/tests/blackbox-tests.md index 1e5ee9f..69ba37a 100644 --- a/_docs/02_document/tests/blackbox-tests.md +++ b/_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. diff --git a/_docs/02_document/tests/traceability-matrix.md b/_docs/02_document/tests/traceability-matrix.md index c3b62ea..d63e606 100644 --- a/_docs/02_document/tests/traceability-matrix.md +++ b/_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 diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index 24dfb7b..540f38d 100644 --- a/_docs/_autodev_state.md +++ b/_docs/_autodev_state.md @@ -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: