azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-22 11:41:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

start over again

Browse Source
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-07 04:08:03 +03:00
parent ee6606a9c2
commit 8382cdae10
351 changed files with 0 additions and 30337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_tasks/_dependencies_table.md
-51
View File
@@ -1,51 +0,0 @@
# Dependencies Table
**Date**: 2026-05-05
**Total Tasks**: 25
**Total Complexity Points**: 113
**Lessons applied**: No `_docs/LESSONS.md` file exists; no prior estimation or dependency lessons were available.
| Task | Name | Complexity | Dependencies | Epic |
|------|------|------------|--------------|------|
| AZ-219 | initial_structure | 5 | None | AZ-206 |
| AZ-220 | shared_runtime_contracts | 3 | AZ-219 | AZ-206 |
| AZ-221 | shared_geometry_time_sync | 3 | AZ-219, AZ-220 | AZ-207 |
| AZ-222 | runtime_config_errors_telemetry | 3 | AZ-219, AZ-220 | AZ-208 |
| AZ-223 | camera_ingest_calibration | 5 | AZ-220, AZ-221, AZ-222 | AZ-209 |
| AZ-224 | mavlink_gcs_gateway | 3 | AZ-220, AZ-222 | AZ-210 |
| AZ-225 | tile_manager_cache_manifest | 5 | AZ-220, AZ-221, AZ-222 | AZ-211 |
| AZ-226 | generated_tile_orthorectification | 5 | AZ-223, AZ-225 | AZ-211 |
| AZ-227 | fdr_event_recorder | 5 | AZ-220, AZ-222 | AZ-212 |
| AZ-228 | vio_adapter | 5 | AZ-221, AZ-222, AZ-223, AZ-224 | AZ-213 |
| AZ-229 | satellite_service_sync | 3 | AZ-222, AZ-225, AZ-226 | AZ-214 |
| AZ-230 | satellite_service_vpr_retrieval | 5 | AZ-223, AZ-225, AZ-229 | AZ-214 |
| AZ-231 | anchor_verification_matching | 5 | AZ-223, AZ-225, AZ-230 | AZ-215 |
| AZ-232 | safety_anchor_state_machine | 5 | AZ-223, AZ-224, AZ-227, AZ-228, AZ-231 | AZ-216 |
| AZ-240 | native_vio_backend_integration | 5 | AZ-228 | AZ-213 |
| AZ-243 | integrate_production_native_vio_runtime | 5 | AZ-240 | AZ-213 |
| AZ-241 | real_satellite_vpr_descriptor_retrieval | 5 | AZ-230 | AZ-214 |
| AZ-242 | real_anchor_feature_matching_ransac | 5 | AZ-231, AZ-241 | AZ-215 |
| AZ-233 | test_infrastructure | 5 | AZ-243, AZ-241, AZ-242 | AZ-218 |
| AZ-234 | replay_geolocation_confidence_tests | 3 | AZ-233 | AZ-218 |
| AZ-235 | vio_replay_performance_tests | 5 | AZ-233, AZ-240 | AZ-218 |
| AZ-236 | satellite_anchor_cache_tests | 5 | AZ-233, AZ-241, AZ-242 | AZ-218 |
| AZ-237 | mavlink_blackout_spoofing_tests | 5 | AZ-233 | AZ-218 |
| AZ-238 | cold_start_restart_tests | 5 | AZ-233 | AZ-218 |
| AZ-239 | jetson_resource_endurance_tests | 5 | AZ-233 | AZ-218 |
## Verification Notes
- No task exceeds 5 complexity points.
- Test implementation tasks are appended under Blackbox Tests (AZ-218); the test infrastructure bootstrap now depends on the product remediation tasks so tests do not validate scaffold behavior.
- The graph is acyclic: product foundations precede adapters/stores, then VIO/retrieval/matching, then safety wrapper orchestration; remediation tasks close native VIO, real VPR, and real matching gaps before affected blackbox tests run.
- Step 9 resume verification confirmed AZ-233 through AZ-239 already exist in Jira and remain ready for test implementation after product remediation completion.
## Test Coverage Verification
- AZ-234 covers FT-P-01, FT-P-02, and NFT-PERF-01.
- AZ-235 covers FT-P-03 and NFT-PERF-02 after AZ-243 provides the real native VIO path.
- AZ-236 covers FT-P-04, FT-N-01, FT-N-03, NFT-PERF-03, NFT-RES-04, NFT-SEC-01, NFT-SEC-02, NFT-SEC-04, and NFT-RES-LIM-03 after AZ-241 and AZ-242 provide real VPR retrieval and anchor matching.
- AZ-237 covers FT-N-02, NFT-RES-01, and NFT-SEC-03.
- AZ-238 covers NFT-RES-02, NFT-RES-03, NFT-PERF-04, and NFT-RES-LIM-05.
- AZ-239 covers NFT-RES-LIM-01, NFT-RES-LIM-02, and NFT-RES-LIM-04.
- All traceability-matrix AC and restriction groups remain covered by at least one test task.
_docs/02_tasks/done/AZ-219_initial_structure.md
-289
View File
@@ -1,289 +0,0 @@
# Initial Project Structure
**Task**: AZ-219_initial_structure
**Name**: Initial Structure
**Description**: Scaffold the project skeleton for the Jetson-hosted GPS-denied localization runtime, replay harness, local infrastructure, CI, and deployment evidence paths.
**Complexity**: 5 points
**Dependencies**: None
**Component**: Bootstrap
**Tracker**: AZ-219
**Epic**: AZ-206
## Project Folder Layout
```text
project-root/
├── src/
│ ├── __init__.py
│ ├── camera_ingest_calibration/
│ ├── vio_adapter/
│ │ └── native/
│ ├── safety_anchor_wrapper/
│ ├── satellite_service/
│ │ └── native/
│ ├── anchor_verification/
│ │ └── native/
│ ├── tile_manager/
│ ├── mavlink_gcs_integration/
│ ├── fdr_observability/
│ ├── shared/
│ │ ├── contracts/
│ │ ├── geo_geometry/
│ │ ├── time_sync/
│ │ ├── config/
│ │ ├── errors/
│ │ └── telemetry/
├── migrations/
│ ├── postgresql/
│ └── seed/
├── tests/
│ ├── unit/
│ ├── integration/
│ ├── blackbox/
│ ├── fixtures/
│ ├── sitl/
│ └── e2e/
├── e2e/
│ ├── replay/
│ └── reports/
├── deployment/
│ ├── docker/
│ ├── compose/
│ ├── jetson/
│ └── scripts/
├── config/
│ ├── development/
│ ├── ci/
│ ├── jetson/
│ └── production/
├── data/
│ ├── input/
│ ├── expected/
│ ├── cache/
│ ├── fdr/
│ └── test-results/
├── .github/
│ └── workflows/
│ └── ci.yml
├── docker-compose.yml
├── docker-compose.test.yml
├── .dockerignore
└── .env.example
```
### Layout Rationale
The runtime is organized directly under `src/` because this repository already represents the GPS-denied onboard system. Component directories live at the source root, and native bridges stay inside the component folder that owns the backend or hot path. Shared contracts, geometry, time-sync, configuration, error envelopes, and telemetry DTOs are centralized so component tasks consume a single public interface instead of duplicating cross-cutting logic.
The scaffold separates runtime source, migrations, tests, deployment assets, configuration, and mutable data. Production runs on Jetson hardware, while Docker/compose is used for replay, SITL, and deterministic CI environments.
## DTOs and Interfaces
### Shared DTOs
| DTO Name | Used By Components | Fields Summary |
|----------|--------------------|----------------|
| `FramePacket` | Camera ingest, BASALT VIO, Satellite Service, anchor verification, Tile Manager, FDR | Frame ID, timestamp, image reference, camera calibration ID, occlusion status, quality metrics |
| `TelemetrySample` | MAVLink/GCS, BASALT VIO, safety wrapper, FDR, e2e tests | Timestamp, IMU, attitude, airspeed, altitude, GPS health |
| `VioStatePacket` | BASALT VIO, safety wrapper, FDR, e2e tests | Timestamp, relative pose, velocity, bias, tracking quality, covariance hint |
| `PositionEstimate` | Safety wrapper, MAVLink/GCS, Tile Manager, FDR, e2e tests | WGS84 coordinates, covariance semi-major axis, source label, fix type, horizontal accuracy, anchor age |
| `VprCandidate` | Satellite Service, anchor verification, FDR | Chunk ID, tile ID, score, footprint, freshness status |
| `AnchorDecision` | Anchor verification, safety wrapper, FDR | Candidate ID, acceptance result, estimated pose, inliers, MRE, rejection reason |
| `CacheTileRecord` | Tile Manager, Satellite Service, anchor verification, FDR | Tile ID, type, CRS, meters per pixel, capture date, signature/hash status, trust level |
| `FdrEvent` | All runtime components, e2e tests | Event type, timestamp, component, severity, payload reference, mission/run ID |
| `ScenarioReport` | Separate e2e test suite, CI/CD, release evidence | Scenario ID, result, metrics, artifacts, failure reason |
### Component Interfaces
| Component | Interface | Methods | Exposed To |
|-----------|-----------|---------|------------|
| Camera ingest/calibration | `FrameProvider` | `next_frame`, `detect_occlusion`, `classify_quality` | VIO Adapter, Satellite Service, anchor verification, Tile Manager |
| VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, e2e tests |
| Safety/anchor wrapper | `LocalizationStateMachine` | `update_vio`, `consider_anchor`, `degrade`, `propagate_imu_only`, `tile_write_eligibility` | MAVLink/GCS, Tile Manager, FDR, e2e tests |
| Satellite Service | `SatelliteService` | `import_mission_cache`, `load_index`, `retrieve`, `upload_generated_tiles` | Safety wrapper, anchor verification, Tile Manager |
| Anchor verification | `AnchorVerifier` | `verify`, `benchmark_matcher` | Safety wrapper, FDR |
| Tile Manager | `TileManager` | `validate_cache`, `get_tile_window`, `orthorectify_frame`, `write_generated_tile`, `package_sync` | Satellite Service, anchor verification, post-flight sync |
| MAVLink/GCS integration | `MavlinkGateway` | `subscribe_telemetry`, `emit_gps_input`, `emit_status` | BASALT VIO, safety wrapper, QGC, FDR |
| FDR/observability | `FlightRecorder` | `append_event`, `rollover`, `export` | All runtime components, e2e tests |
## CI/CD Pipeline
| Stage | Purpose | Trigger |
|-------|---------|---------|
| Format / lint | Enforce code style and static quality | Every PR and push to `dev` |
| Unit tests | Validate component-local behavior and shared contracts | Every PR and push to `dev` |
| Replay black-box smoke | Run deterministic still-image/cache/SITL subsets | Every PR |
| Cache/security fixture tests | Validate signed manifests, stale-tile rejection, and no mid-flight provider/Satellite Service calls | Every PR |
| Plane SITL spoof/failsafe | Validate ArduPilot Plane `GPS_INPUT`, failsafe, spoofing promotion | Nightly and release candidate |
| Public dataset replay | Exercise VIO, retrieval, and anchor behavior against pinned public slices | Nightly and release candidate |
| Jetson latency/resource tests | Measure p95 latency, memory, cold start, TensorRT/ONNX fidelity | Release candidate |
| Thermal/FDR endurance | Prove 8-hour 25 W no-throttle and <=64 GB FDR rollover | Hardware qualification |
| Build / package | Produce replay-compatible and Jetson deployment artifacts | Release candidate |
| Deploy staging evidence | Publish reports, tlogs, FDR summaries, cache validation artifacts | Release candidate |
### Pipeline Configuration Notes
CI uses Docker/compose for replay and SITL gates. Jetson, thermal, camera, and representative replay gates run on dedicated hardware runners and block release rather than every PR. Dataset downloads are license-tagged and not baked into images. Secrets, signing keys, and Satellite Service credentials are never cached.
## Environment Strategy
| Environment | Purpose | Configuration Notes |
|-------------|---------|---------------------|
| Development replay | Fast local iteration | Small fixture cache, local PostgreSQL/PostGIS, replay frames, test keys only |
| CI replay | Deterministic PR checks | Docker services for runtime, replay consumer, cache stub, and reports |
| Public dataset replay | Algorithm de-risking | Pinned dataset slices with license metadata and ground-truth reports |
| Plane SITL | MAVLink/failsafe validation | ArduPilot Plane SITL, QGC/tlog observer, production-like `GPS_INPUT` parameters |
| Jetson hardware validation | Production path profiling | JetPack/CUDA/TensorRT, local camera/GPU/MAVLink access, resource monitoring |
| Representative flight/replay | Final acceptance evidence | Target-like UAV, FC, camera, synchronized telemetry, ground truth |
| Production | Onboard mission runtime | Preloaded signed cache, local PostGIS, per-flight FDR, no provider network calls |
### Environment Variables
| Variable | Dev | Staging | Production | Description |
|----------|-----|---------|------------|-------------|
| `GPSD_ENV` | `development` | `staging` | `production` | Selects runtime profile |
| `GPSD_CONFIG_DIR` | local path | staged config path | onboard config path | Versioned configuration root |
| `GPSD_CACHE_DIR` | fixture cache | staged mission cache | onboard mission cache | COG, manifest, sidecar, descriptor root |
| `GPSD_FDR_DIR` | temp output | staged evidence path | per-flight NVMe path | Flight data recorder output |
| `GPSD_DATABASE_URL` | local PostGIS | staging PostGIS | onboard local PostGIS | Manifest, mission state, FDR event index |
| `GPSD_MAVLINK_URL` | SITL/replay | SITL/hardware rig | FC telemetry link | MAVLink connection endpoint |
| `GPSD_CAMERA_SOURCE` | fixture/replay | fixture or hardware | live camera | Navigation frame source |
| `GPSD_SIGNING_KEY_REF` | test key ref | staging secret ref | mission secret ref | Cache/sidecar signature verification |
| `GPSD_MAX_FDR_BYTES` | small fixture cap | release-like cap | `68719476736` | FDR rollover threshold |
| `GPSD_LOG_LEVEL` | debug/info | info | info/warn | Runtime logging level |
## Database Migration Approach
**Migration tool**: Versioned PostgreSQL migration scripts, with PostGIS extension setup and deterministic seed scripts.
**Strategy**: Additive migrations by default. Database, table, and column renames require explicit approval before implementation. Runtime rejects unknown required schema versions loudly.
### Initial Schema
- Mission profile tables for route geometry, sector classification, altitude band, and cache budget.
- Camera calibration tables for camera model, intrinsics, extrinsics, and verification status.
- Cache manifest tables for COG tiles, generated tiles, freshness, signatures, sidecar hashes, trust level, and PostGIS footprints.
- VPR chunk tables for retrieval footprints, descriptor metadata, multi-scale index references, and sector top-K policy.
- FDR event index tables for mission/run IDs, timestamps, event type, component, severity, and CBOR segment references.
- Validation run tables or report records for scenario IDs, metrics, artifacts, and release evidence pointers.
## Test Structure
```text
tests/
├── unit/
│ ├── shared/
│ ├── camera_ingest_calibration/
│ ├── vio_adapter/
│ ├── safety_anchor_wrapper/
│ ├── satellite_service/
│ ├── anchor_verification/
│ ├── tile_manager/
│ ├── mavlink_gcs_integration/
│ ├── fdr_observability/
├── integration/
│ ├── contracts/
│ ├── cache_postgis/
│ ├── mavlink/
│ └── fdr/
├── blackbox/
│ ├── still_image_geolocation/
│ ├── satellite_anchor/
│ ├── visual_blackout_spoofing/
│ ├── cache_freshness/
│ └── resource_limits/
├── fixtures/
│ ├── project_60_images/
│ ├── expected_results/
│ ├── satellite_cache/
│ ├── telemetry/
│ └── public_dataset_slices/
├── sitl/
│ ├── plane_gps_input/
│ ├── spoofing_promotion/
│ └── failsafe/
└── e2e/
├── replay/
├── reports/
└── release_evidence/
```
### Test Configuration Notes
Unit tests validate contracts and component behavior without external hardware. Integration tests exercise PostGIS, MAVLink, FDR segments, and cache fixtures. Black-box tests interact only through public inputs and outputs: frames, telemetry, offline cache, `GPS_INPUT`, QGC status, and FDR. Release gates add Jetson hardware, thermal/endurance, and representative replay evidence.
## Health Checks
| Service / Component | Liveness | Readiness |
|---------------------|----------|-----------|
| GPS-denied service | Process event loop responsive | Config, PostGIS, cache, FDR path, MAVLink, and camera/replay source validated |
| Replay consumer | Runner process responsive | Fixtures, expected results, and output path available |
| Satellite cache stub | Fixture volume mounted | Manifests, sidecars, descriptors, and signatures validated |
| ArduPilot Plane SITL | SITL process responsive | MAVLink ports accepting telemetry and production parameters loaded |
| QGC observer/log parser | Parser process responsive | Tlog/status stream connected |
Each deployable service exposes `/health/live`, `/health/ready`, and `/metrics` where HTTP is available. Non-HTTP hardware processes write equivalent structured health events to FDR and CI reports.
## Docker And Compose Requirements
- Create a replay-compatible Dockerfile for the Python runtime and native optional stubs.
- Create a replay-consumer Dockerfile for black-box test execution.
- Create a satellite-cache-stub fixture image or volume contract.
- Create an ArduPilot Plane SITL service for integration tests.
- Use non-root users, pinned base images, multi-stage builds where native compilation is needed, and health checks for long-running services.
- Provide `docker-compose.yml` for local development/replay and `docker-compose.test.yml` for black-box/SITL test execution.
- Do not bake secrets, provider credentials, mission signing keys, or public dataset payloads into images.
## Implementation Order
| Order | Component | Reason |
|-------|-----------|--------|
| 1 | Bootstrap and shared contracts | Establish package, configuration, migrations, CI, DTOs, and error envelopes |
| 2 | Shared geometry/time helpers | Foundational math and timestamp contracts used by camera, VIO, cache, wrapper, and validation |
| 3 | Runtime configuration and error handling | Prevent duplicated config/error behavior across components |
| 4 | Camera ingest/calibration | Produces the frame and occlusion signals required by VIO, anchor, cache, and tests |
| 5 | MAVLink/GCS integration | Supplies FC telemetry DTOs and validates `GPS_INPUT` output contract early |
| 6 | Tile Manager | Owns PostGIS cache manifest, sidecars, COG access, freshness gates, and generated-tile orthorectification |
| 7 | FDR/observability | Provides audit path for all components and validation reports |
| 8 | VIO adapter | Depends on frame and telemetry contracts, blocks wrapper integration |
| 9 | Satellite Service | Depends on tile schema and frame DTOs, feeds anchor verification, and handles pre-flight/post-flight package sync |
| 10 | Anchor verification | Depends on retrieval candidates and cache tile access |
| 11 | Safety/anchor wrapper | Consumes VIO, anchor, camera degradation, MAVLink, and FDR contracts |
| 12 | Validation harness | Uses public interfaces once contracts and runtime components are stable |
| 13 | Black-box, SITL, Jetson, and endurance test tasks | Exercise release gates and acceptance criteria end to end |
## Acceptance Criteria
**AC-1: Project scaffolded**
Given the structure plan above
When the implementer executes this task
Then source, test, migration, deployment, configuration, and data directories exist with placeholder files where needed so empty directories are retained.
**AC-2: Shared contracts initialized**
Given the planned component interfaces
When the scaffold is complete
Then shared DTO, error, configuration, telemetry, geometry, and time-sync contract locations exist and are importable from component skeletons.
**AC-3: Local infrastructure defined**
Given the system requires local PostGIS, replay, SITL, cache, and FDR paths
When the scaffold is complete
Then `docker-compose.yml`, `docker-compose.test.yml`, `.env.example`, and migration seed directories describe all required local services and volumes.
**AC-4: CI/CD configured**
Given the pipeline stages in the planning artifacts
When CI runs on a PR
Then format/lint, unit tests, replay black-box smoke, cache/security fixture tests, and artifact collection stages are defined.
**AC-5: Test harness skeleton ready**
Given black-box tests must use public interfaces only
When the scaffold is complete
Then unit, integration, black-box, fixtures, and SITL test locations exist with runner entry points ready for implementation tasks.
**AC-6: Deployment evidence paths ready**
Given release requires Jetson, SITL, FDR, cache, and representative replay evidence
When the scaffold is complete
Then deployment scripts, report output paths, and documentation placeholders exist for those evidence artifacts.
**AC-7: No production secrets or raw frames committed**
Given onboard runtime must not retain raw frames and must protect signing credentials
When the scaffold is reviewed
Then `.gitignore`, `.dockerignore`, and `.env.example` exclude secrets, generated FDR payloads, raw frame dumps, cache payloads, and test result artifacts unless explicitly fixture-scoped.
_docs/02_tasks/done/AZ-220_shared_runtime_contracts.md
-78
View File
@@ -1,78 +0,0 @@
# Shared Runtime Contracts
**Task**: AZ-220_shared_runtime_contracts
**Name**: Shared Runtime Contracts
**Description**: Define the shared DTO and event contract surface used across the onboard runtime.
**Complexity**: 3 points
**Dependencies**: AZ-219_initial_structure
**Component**: Bootstrap / Shared Contracts
**Tracker**: AZ-220
**Epic**: AZ-206
## Problem
Runtime components need common shapes for frames, telemetry, VIO state, position estimates, candidates, anchors, cache tiles, and FDR events.
## Outcome
- Components consume one documented shared contract surface.
- Cross-component DTO drift is prevented before implementation begins.
## Scope
### Included
- Shared runtime DTO names, fields, invariants, versioning rules, and contract tests.
- Public contract document for consumers.
### Excluded
- Component-specific algorithms.
- E2E runner-only report schemas.
## Acceptance Criteria
**AC-1: Shared contract exists**
Given runtime components need common DTOs
When the shared contracts are implemented
Then each runtime component can import or reference the same contract surface.
**AC-2: Contract validation exists**
Given a malformed shared DTO
When validation runs
Then the input is rejected with a structured error.
## Non-Functional Requirements
**Compatibility**
- Contract changes follow documented versioning rules.
**Reliability**
- Invalid or missing required fields are not silently ignored.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | DTO construction for valid minimal values | Accepted |
| AC-2 | Missing required timestamp or ID | Rejected with structured error |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Runtime started with contract consumers | Public interfaces exchange typed records | No component-specific duplicate shape required | Compatibility |
## Constraints
- Contracts are shared API surface and must be consumed through documented public modules.
- Raw frame payloads are referenced, not retained in shared DTOs.
## Risks & Mitigation
**Risk 1: Contract drift**
- *Risk*: Consumers create local incompatible DTOs.
- *Mitigation*: Contract file is required dependency for consuming tasks.
## Contract
This task produces/implements the contract at `_docs/02_document/contracts/shared/runtime_contracts.md`.
Consumers MUST read that file — not this task spec — to discover the interface.
_docs/02_tasks/done/AZ-221_shared_geometry_time_sync.md
-78
View File
@@ -1,78 +0,0 @@
# Shared Geometry And Time Sync
**Task**: AZ-221_shared_geometry_time_sync
**Name**: Shared Geometry And Time Sync
**Description**: Provide shared geospatial and timestamp helper behavior for runtime components.
**Complexity**: 3 points
**Dependencies**: AZ-219_initial_structure, AZ-220_shared_runtime_contracts
**Component**: Shared Geometry And Time Sync
**Tracker**: AZ-221
**Epic**: AZ-207
## Problem
Camera, VIO, Tile Manager, Satellite Service, Anchor Verification, safety, and FDR need consistent coordinate, footprint, homography, and timestamp behavior.
## Outcome
- Shared helpers provide deterministic geometry and time-sync behavior.
- Components do not duplicate geospatial or timestamp alignment logic.
## Scope
### Included
- WGS84/local conversions, distance/GSD helpers, footprint projection, homography/covariance conversion support.
- Monotonic timestamp checks, frame-to-IMU window selection, replay ordering, gap/jitter metrics.
### Excluded
- VIO estimation.
- Cache policy and safety degrade decisions.
## Acceptance Criteria
**AC-1: Geometry helpers are deterministic**
Given the same calibration, attitude, altitude, and coordinates
When geometry helpers run
Then they return repeatable footprint and metric outputs.
**AC-2: Time-sync violations are explicit**
Given frame and telemetry timestamps with a gap or mismatch
When alignment runs
Then the result reports the violation instead of dropping data silently.
## Non-Functional Requirements
**Performance**
- Helpers are suitable for hot-path use under the system latency budget.
**Reliability**
- Invalid calibration, CRS, or timestamp inputs fail explicitly.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | WGS84/local round-trip | Error within tolerance |
| AC-2 | Non-monotonic timestamps | Explicit mismatch result |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Derkachi/replay frame metadata | Footprint and ordering evidence | Deterministic helper outputs in reports | Performance |
## Constraints
- Shared helpers do not own policy decisions.
- Timestamp units must match the shared runtime contract.
## Risks & Mitigation
**Risk 1: Coordinate-frame confusion**
- *Risk*: Components interpret helper outputs differently.
- *Mitigation*: Contract documents units, frames, and error semantics.
## Contract
This task produces/implements the contract at `_docs/02_document/contracts/shared/geometry_time_sync.md`.
Consumers MUST read that file — not this task spec — to discover the interface.
_docs/02_tasks/done/AZ-222_runtime_config_errors_telemetry.md
-80
View File
@@ -1,80 +0,0 @@
# Runtime Config Errors And Telemetry
**Task**: AZ-222_runtime_config_errors_telemetry
**Name**: Runtime Config Errors And Telemetry
**Description**: Provide shared configuration, error envelope, health, and telemetry behavior for runtime components.
**Complexity**: 3 points
**Dependencies**: AZ-219_initial_structure, AZ-220_shared_runtime_contracts
**Component**: Runtime Configuration And Errors
**Tracker**: AZ-222
**Epic**: AZ-208
## Problem
Runtime components need common configuration loading, readiness validation, error handling, and telemetry metadata.
## Outcome
- Environment profiles are validated before runtime use.
- Errors and health events are structured and FDR-safe.
- Secrets are referenced without leaking into logs or reports.
## Scope
### Included
- Runtime profile validation.
- Shared error/result envelopes.
- Health and metrics metadata.
### Excluded
- Component-specific business logic.
- FDR storage implementation.
## Acceptance Criteria
**AC-1: Required settings are validated**
Given a production profile is missing a required setting
When startup/readiness validation runs
Then the component reports a structured failure.
**AC-2: Errors are not silent**
Given a dependency failure occurs
When a component reports it
Then the error includes component, category, severity, and retryability.
## Non-Functional Requirements
**Reliability**
- Missing configuration and dependency failures are never silently ignored.
**Compatibility**
- Error categories and config keys follow the contract versioning rules.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Missing production cache dir | Readiness failure |
| AC-2 | Dependency error envelope | Structured fields present |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Invalid env profile | Runtime readiness | Service refuses ready state | Reliability |
## Constraints
- Secrets must not be serialized into logs, FDR, or metrics.
- Error handling must not use silent suppression.
## Risks & Mitigation
**Risk 1: Environment-specific behavior drifts**
- *Risk*: Development and production profiles behave differently in unsafe ways.
- *Mitigation*: Profile validation is shared and tested.
## Contract
This task produces/implements the contract at `_docs/02_document/contracts/shared/config_errors_telemetry.md`.
Consumers MUST read that file — not this task spec — to discover the interface.
_docs/02_tasks/done/AZ-223_camera_ingest_calibration.md
-89
View File
@@ -1,89 +0,0 @@
# Camera Ingest Calibration And Frame Quality
**Task**: AZ-223_camera_ingest_calibration
**Name**: Camera Ingest Calibration And Frame Quality
**Description**: Ingest navigation frames, attach calibration/timestamp metadata, classify quality, detect occlusion, and provide north-up normalization hints.
**Complexity**: 5 points
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry
**Component**: Camera Ingest And Calibration
**Tracker**: AZ-223
**Epic**: AZ-209
## Problem
Downstream VIO, retrieval, anchor verification, Tile Manager, and FDR need trustworthy frame metadata and quality decisions before using image data.
## Outcome
- Replay and live-source frames are exposed with timestamps, calibration ID, quality, occlusion, and normalization hints.
- Total occlusion/blackout frames are marked unusable for VIO and anchor paths.
## Scope
### Included
- Frame source abstraction for replay/live camera boundary.
- Calibration metadata loading and validation.
- Quality and occlusion reports.
- North-up/orthorectification hints as metadata, not unconditional frame mutation.
### Excluded
- Tile writing and generated COG persistence.
- BASALT processing.
## 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: Usable frame packet emitted**
Given a valid replay frame and calibration
When the frame is ingested
Then a frame packet includes timestamp, calibration ID, quality report, occlusion report, and normalization hint.
**AC-2: Blackout bypass signal emitted**
Given an unreadable, covered, or total-occlusion frame
When quality classification runs
Then the frame is marked unusable for VIO and anchor matching.
**AC-3: Raw frames are not retained**
Given normal runtime operation
When a frame is processed
Then only allowed metadata/references are retained outside explicit fixture/test paths.
## Non-Functional Requirements
**Performance**
- Frame preprocessing must fit within the system p95 latency budget.
**Reliability**
- Missing calibration blocks production readiness.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid frame with calibration | Frame packet contains required metadata |
| AC-2 | Total occlusion input | `usable_for_vio=false` and `usable_for_anchor=false` |
| AC-3 | Processed frame cleanup | No raw-frame persistence |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Derkachi replay fixture | Frame/telemetry alignment | Accepted frame packets are timestamped | Performance |
| AC-2 | Blackout fixture | Occlusion handling | Visual path degrades safely | Reliability |
## Constraints
- Do not rotate every frame in ingest; emit normalization hints for downstream use.
- ADTi hardware assumptions remain blocked until exact specs are verified.
## Risks & Mitigation
**Risk 1: False-negative occlusion**
- *Risk*: Bad frames enter VIO or matching.
- *Mitigation*: Conservative occlusion gate and explicit quality flags.
_docs/02_tasks/done/AZ-224_mavlink_gcs_gateway.md
-84
View File
@@ -1,84 +0,0 @@
# MAVLink GCS Gateway
**Task**: AZ-224_mavlink_gcs_gateway
**Name**: MAVLink GCS Gateway
**Description**: Subscribe to FC telemetry, emit `GPS_INPUT`, and publish QGC-visible status/failsafe messages.
**Complexity**: 3 points
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry
**Component**: MAVLink And GCS Integration
**Tracker**: AZ-224
**Epic**: AZ-210
## Problem
The runtime needs a strict protocol boundary for ArduPilot Plane telemetry in and GPS-denied estimates/status out.
## Outcome
- FC telemetry is normalized into shared samples.
- `GPS_INPUT` is emitted only from validated position estimates.
- QGC status is rate-limited and safety-relevant.
## Scope
### Included
- Telemetry subscription behavior.
- `GPS_INPUT` field validation and emission result.
- QGC status/failsafe message emission.
### Excluded
- Safety policy and covariance calculation.
- SITL test runner implementation.
## Dependencies
### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
## Acceptance Criteria
**AC-1: Telemetry sample emitted**
Given a valid FC telemetry stream
When the gateway subscribes
Then normalized telemetry samples are available to consumers.
**AC-2: Invalid GPS_INPUT is rejected**
Given a malformed or unsafe position estimate
When emission is requested
Then no invalid `GPS_INPUT` packet is emitted.
**AC-3: Operator status is rate-limited**
Given repeated mode changes or warnings
When status is emitted
Then QGC-visible messages stay within the configured rate.
## Non-Functional Requirements
**Reliability**
- Connection loss is surfaced to wrapper/FDR.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Telemetry normalization | Shared sample emitted |
| AC-2 | Invalid fix type/accuracy | Emission rejected |
| AC-3 | Status burst | Rate limit enforced |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Plane SITL | `GPS_INPUT` output | Fields match ArduPilot expectations | Reliability |
## Constraints
- v1 emits `GPS_INPUT` only.
- Do not hide MAVLink disconnects or invalid output errors.
## Risks & Mitigation
**Risk 1: ArduPilot parameter mismatch**
- *Risk*: Plane ignores or mishandles emitted estimates.
- *Mitigation*: SITL validation remains a release gate.
_docs/02_tasks/done/AZ-225_tile_manager_cache_manifest.md
-89
View File
@@ -1,89 +0,0 @@
# Tile Manager Cache Manifest
**Task**: AZ-225_tile_manager_cache_manifest
**Name**: Tile Manager Cache Manifest
**Description**: Validate local cache manifests, signed sidecars, tile freshness, and spatial/descriptor metadata access.
**Complexity**: 5 points
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry
**Component**: Tile Manager
**Tracker**: AZ-225
**Epic**: AZ-211
## Problem
The runtime must trust only preloaded offline cache tiles with valid signatures, hashes, freshness, resolution, and spatial metadata.
## Outcome
- Mission cache validation blocks invalid cache usage.
- Tile windows and descriptor metadata are queryable through local PostGIS-backed metadata.
- Stale or tampered tiles cannot become trusted anchor inputs.
## Scope
### Included
- Cache package validation.
- Signed sidecar/hash/freshness checks.
- Tile window and descriptor metadata lookup.
- Cache validation report events.
### Excluded
- Satellite Service package transfer.
- Generated tile orthorectification/write-back.
## 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: Valid cache activates**
Given a cache package with valid manifests, sidecars, hashes, freshness, and spatial coverage
When cache validation runs
Then the cache becomes available to retrieval and anchor paths.
**AC-2: Invalid cache is rejected**
Given a stale, unsigned, or hash-mismatched tile
When validation runs
Then the tile is rejected and an auditable reason is recorded.
**AC-3: Tile metadata is queryable**
Given a candidate footprint or chunk ID
When a consumer requests tile metadata
Then the Tile Manager returns a valid local record or explicit rejection.
## Non-Functional Requirements
**Performance**
- Indexed tile lookups meet relocalization-path latency needs.
**Reliability**
- Local PostgreSQL/PostGIS unavailability blocks mission cache activation.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid fixture | Cache available |
| AC-2 | Tampered sidecar | Tile rejected |
| AC-3 | Chunk metadata lookup | Correct record or explicit error |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Stale/unsigned fixtures | Cache security gate | No invalid tile reaches retrieval | Reliability |
## Constraints
- Runtime never fetches satellite data mid-flight.
- Large imagery/descriptors stay as files, not DB blobs.
## Risks & Mitigation
**Risk 1: Cache poisoning**
- *Risk*: Bad cache entries influence anchor decisions.
- *Mitigation*: Signature, hash, freshness, and provenance gates are mandatory.
_docs/02_tasks/done/AZ-226_generated_tile_orthorectification.md
-88
View File
@@ -1,88 +0,0 @@
# Generated Tile Orthorectification And Sync Package
**Task**: AZ-226_generated_tile_orthorectification
**Name**: Generated Tile Orthorectification And Sync Package
**Description**: Convert eligible nadir frames into generated orthorectified COG tiles and prepare post-flight sync packages.
**Complexity**: 5 points
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-225_tile_manager_cache_manifest
**Component**: Tile Manager
**Tracker**: AZ-226
**Epic**: AZ-211
## Problem
Generated tiles must be written only when pose, frame quality, and provenance gates make them safe to retain for post-flight Satellite Service review.
## Outcome
- Eligible nadir frames can become generated COG candidates with sidecars.
- Unsafe or over-confident tile writes are rejected.
- Post-flight generated-tile packages carry enough metadata for Satellite Service ingest/voting.
## Scope
### Included
- Orthorectification request handling.
- Generated COG + sidecar metadata creation.
- Covariance/quality gates and trust level assignment.
- Sync package preparation.
### Excluded
- Satellite Service upload transport.
- Promotion to trusted basemap onboard.
## Dependencies
### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/geometry_time_sync.md`
## Acceptance Criteria
**AC-1: Eligible frame writes generated tile**
Given a high-confidence pose and usable frame
When tile generation runs
Then a generated COG candidate and sidecar are staged.
**AC-2: Unsafe frame is rejected**
Given high covariance or unusable frame quality
When tile generation runs
Then no trusted tile is written.
**AC-3: Sync package is auditable**
Given generated candidate tiles exist
When a package is prepared
Then it includes manifest delta, sidecars, parent covariance, and trust level.
## Non-Functional Requirements
**Reliability**
- Generated tiles are never promoted directly to trusted basemap onboard.
**Performance**
- Tile generation must not block localization output.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid tile request | COG + sidecar staged |
| AC-2 | Covariance too high | Write rejected |
| AC-3 | Package creation | Required metadata present |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Poisoning fixture | Generated tile gate | No direct trusted promotion | Reliability |
## Constraints
- Tile Manager performs generated tile writes; camera ingest only provides metadata/hints.
- Missing sidecars make generated tiles ineligible for upload.
## Risks & Mitigation
**Risk 1: Misaligned generated tile**
- *Risk*: Wrong pose creates harmful future anchor data.
- *Mitigation*: Parent covariance, frame quality, and post-flight validation gates.
_docs/02_tasks/done/AZ-227_fdr_event_recorder.md
-88
View File
@@ -1,88 +0,0 @@
# FDR Event Recorder And Export Surface
**Task**: AZ-227_fdr_event_recorder
**Name**: FDR Event Recorder And Export Surface
**Description**: Record bounded replayable mission evidence and expose exportable post-flight summaries.
**Complexity**: 5 points
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry
**Component**: FDR And Observability
**Tracker**: AZ-227
**Epic**: AZ-212
## Problem
The system needs compact, bounded, queryable evidence for estimates, inputs, health, anchors, tile writes, and safety transitions.
## Outcome
- Runtime components can append structured FDR events.
- Storage rollover and health behavior are explicit.
- Post-flight exports are available for analysis and release evidence.
## Scope
### Included
- Append event behavior.
- PostgreSQL event index and CBOR segment payload contract.
- Rollover and storage-full handling.
- Export request/result behavior.
### Excluded
- Component-specific event payload generation.
- E2E report collation.
## Dependencies
### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
## Acceptance Criteria
**AC-1: Events are appendable**
Given a valid FDR event
When a component appends it
Then metadata is indexed and payload is stored within bounds.
**AC-2: Storage pressure is handled**
Given segment or storage limits are reached
When append continues
Then rollover or critical status behavior is explicit.
**AC-3: Export produces evidence**
Given a completed run
When export is requested
Then queryable evidence and optional analytics artifacts are produced.
## Non-Functional Requirements
**Performance**
- FDR appends must not block hot-path localization.
**Reliability**
- Append failures are surfaced to callers and health state.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid event append | Indexed metadata and payload reference |
| AC-2 | Rollover threshold | Rollover event recorded |
| AC-3 | Export request | Evidence artifact produced |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | 8-hour synthetic load | FDR cap and rollover | <=64 GB or explicit rollover evidence | Performance |
## Constraints
- Raw frames are not retained by default.
- Secrets are not logged in FDR payloads.
## Risks & Mitigation
**Risk 1: FDR affects latency**
- *Risk*: Append pressure slows localization.
- *Mitigation*: Bounded segments and async-friendly append semantics.
_docs/02_tasks/done/AZ-228_vio_adapter.md
-90
View File
@@ -1,90 +0,0 @@
# 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.
_docs/02_tasks/done/AZ-229_satellite_service_sync.md
-87
View File
@@ -1,87 +0,0 @@
# Satellite Service Sync Boundary
**Task**: AZ-229_satellite_service_sync
**Name**: Satellite Service Sync Boundary
**Description**: Import mission cache packages before flight and upload generated-tile packages after flight.
**Complexity**: 3 points
**Dependencies**: AZ-222_runtime_config_errors_telemetry, AZ-225_tile_manager_cache_manifest, AZ-226_generated_tile_orthorectification
**Component**: Satellite Service
**Tracker**: AZ-229
**Epic**: AZ-214
## Problem
The onboard runtime needs a clear boundary for Satellite Service package exchange without allowing mid-flight network calls.
## Outcome
- Pre-flight cache packages can be imported and handed to Tile Manager validation.
- Post-flight generated-tile packages can be uploaded/retried.
- Mid-flight provider or Satellite Service calls are explicitly blocked.
## Scope
### Included
- Pre-flight import behavior.
- Post-flight generated-tile upload behavior.
- Package status and retry/error reporting.
### Excluded
- In-flight retrieval ranking.
- Tile manifest validation and generated tile creation.
## Dependencies
### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
## Acceptance Criteria
**AC-1: Pre-flight package import succeeds**
Given a valid Satellite Service mission cache package
When import runs before flight
Then the package is available for Tile Manager validation.
**AC-2: Post-flight upload is auditable**
Given a generated-tile package exists after landing
When upload runs
Then success, rejection, or retryable failure is recorded.
**AC-3: Mid-flight network calls are blocked**
Given the runtime is in flight mode
When cache data is missing
Then the component does not call a satellite provider or suite service.
## Non-Functional Requirements
**Reliability**
- Upload failures retain packages for retry.
**Security**
- Signing credentials are never logged.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid import package | Package ready for validation |
| AC-2 | Upload unavailable | Retryable failure recorded |
| AC-3 | Flight-mode missing data | No network call |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-3 | Network disabled in replay | Relocalization missing data | Degraded/no-candidate behavior, no fetch | Security |
## Constraints
- No in-flight Satellite Service or satellite-provider network dependency.
- Package sync is before takeoff or after landing only.
## Risks & Mitigation
**Risk 1: Boundary confusion**
- *Risk*: Retrieval code starts fetching provider data mid-flight.
- *Mitigation*: Flight-mode invariant is acceptance-tested.
_docs/02_tasks/done/AZ-230_satellite_service_vpr_retrieval.md
-89
View File
@@ -1,89 +0,0 @@
# Satellite Service Local VPR Retrieval
**Task**: AZ-230_satellite_service_vpr_retrieval
**Name**: Satellite Service Local VPR Retrieval
**Description**: Retrieve local VPR candidates from preloaded descriptors and FAISS indexes.
**Complexity**: 5 points
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-225_tile_manager_cache_manifest, AZ-229_satellite_service_sync
**Component**: Satellite Service
**Tracker**: AZ-230
**Epic**: AZ-214
## Problem
Relocalization needs ranked satellite/cache candidates, but retrieval must be trigger-based and use only local preloaded cache/index data.
## Outcome
- DINOv2-VLAD descriptor extraction and CPU FAISS top-K candidate retrieval are available.
- Candidate freshness and dynamic top-K policy are carried forward.
- No-candidate/index failures produce degraded behavior rather than unsafe anchors.
## Scope
### Included
- Index load/readiness behavior.
- Query descriptor and top-K candidate retrieval.
- Freshness tagging and retrieval result metadata.
- Descriptor fidelity gate for optimized engines.
### Excluded
- Local matching/RANSAC.
- In-flight network fetches.
## 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: Index loads before retrieval**
Given a valid local descriptor/index package
When index loading runs
Then retrieval readiness is reported.
**AC-2: Top-K candidates returned**
Given a relocalization request and loaded local index
When retrieval runs
Then bounded candidates include tile/chunk IDs, scores, footprints, and freshness status.
**AC-3: Missing candidates degrade safely**
Given no valid candidates or index failure
When retrieval runs
Then the result is explicit no-candidate/degraded behavior.
## Non-Functional Requirements
**Performance**
- Retrieval is trigger-based and profiled against Jetson limits.
**Security**
- Retrieval never performs mid-flight provider calls.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid index | Ready status |
| AC-2 | Query frame | Candidate list with freshness |
| AC-3 | Missing index | Explicit degraded/no-candidate result |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Public/cache fixture | VPR recall and top-K policy | Correct candidate bounds and freshness | Performance |
## Constraints
- Retrieval is not per-frame steady-state work.
- TensorRT/ONNX path is accepted only after descriptor-fidelity tests pass.
## Risks & Mitigation
**Risk 1: Trigger path exceeds Jetson budget**
- *Risk*: Descriptor extraction or FAISS query is too slow.
- *Mitigation*: CPU-first FAISS, bounded top-K, and profiling gates.
_docs/02_tasks/done/AZ-231_anchor_verification_matching.md
-88
View File
@@ -1,88 +0,0 @@
# Anchor Verification Matching And Geometry Gates
**Task**: AZ-231_anchor_verification_matching
**Name**: Anchor Verification Matching And Geometry Gates
**Description**: Verify retrieved candidates with ALIKED/DISK + LightGlue and geometric safety gates.
**Complexity**: 5 points
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-225_tile_manager_cache_manifest, AZ-230_satellite_service_vpr_retrieval
**Component**: Anchor Verification
**Tracker**: AZ-231
**Epic**: AZ-215
## Problem
VPR candidates are not trusted fixes; they require local feature matching, RANSAC geometry, provenance checks, and measurable rejection evidence.
## Outcome
- Anchor candidates are accepted or rejected with MRE, inlier count, homography, freshness/provenance, and reason metadata.
- Matcher profiles can be benchmarked without making learned matching a per-frame VIO hot path.
## Scope
### Included
- ALIKED/DISK + LightGlue matching profile behavior.
- SIFT/ORB baseline profile.
- OpenCV RANSAC/USAC geometry checks.
- Anchor decision output and rejection reasons.
### Excluded
- VPR retrieval ranking.
- Safety wrapper anchor fusion.
## 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: Candidate verification emits evidence**
Given retrieved candidates and a usable frame
When verification runs
Then each result includes acceptance state, MRE, inlier count, and rejection/acceptance reason.
**AC-2: Unsafe candidates are rejected**
Given low inliers, high MRE, stale provenance, or geometry failure
When verification runs
Then no accepted anchor decision is emitted for that candidate.
**AC-3: Matcher benchmark is reportable**
Given configured matcher profiles
When benchmark runs
Then profile runtime and quality metrics are reported.
## Non-Functional Requirements
**Performance**
- Learned matching is trigger-based and profiled separately from BASALT.
**Reliability**
- SuperPoint is excluded from production unless legal approval exists.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid matching fixture | Evidence fields present |
| AC-2 | Bad geometry fixture | Rejected decision |
| AC-3 | Benchmark profiles | Metrics emitted |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Aerial/cache fixture | Anchor verification path | Accepted anchors meet MRE/inlier gates | Performance |
## Constraints
- ALIKED/DISK + LightGlue supplies correspondences, not full VIO.
- Anchor verification does not decide final safety fusion.
## Risks & Mitigation
**Risk 1: False anchor acceptance**
- *Risk*: Cross-domain match looks plausible but is wrong.
- *Mitigation*: Geometry, freshness, provenance, and downstream Mahalanobis gates.
_docs/02_tasks/done/AZ-232_safety_anchor_state_machine.md
-97
View File
@@ -1,97 +0,0 @@
# Safety Anchor State Machine
**Task**: AZ-232_safety_anchor_state_machine
**Name**: Safety Anchor State Machine
**Description**: Own authoritative localization state, confidence, anchor fusion, degraded modes, tile-write eligibility, and MAVLink output semantics.
**Complexity**: 5 points
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway, AZ-227_fdr_event_recorder, AZ-228_vio_adapter, AZ-231_anchor_verification_matching
**Component**: Safety And Anchor Wrapper
**Tracker**: AZ-232
**Epic**: AZ-216
## Problem
The product needs one safety authority that converts VIO, telemetry, camera quality, and anchor evidence into honest localization outputs and degraded/failsafe behavior.
## Outcome
- Wrapper updates localization state from VIO and anchors.
- Covariance grows honestly in degraded modes.
- `GPS_INPUT` semantics, source labels, and tile-write eligibility are controlled by the wrapper.
## Scope
### Included
- VIO update handling.
- Anchor acceptance/rejection integration.
- IMU-only degraded propagation.
- Covariance/source-label/fix-type behavior.
- Tile-write eligibility decisions.
### Excluded
- VIO backend internals.
- MAVLink transport implementation.
- Generated tile writing.
## 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 updates position estimate**
Given valid VIO state and telemetry context
When the wrapper processes the update
Then it emits an estimate with source label and honest covariance.
**AC-2: Accepted anchor can correct state**
Given an anchor decision that passes safety gates
When the wrapper considers it
Then the state may become `satellite_anchored` with recorded evidence.
**AC-3: Blackout degrades safely**
Given total visual blackout or tracking loss
When degraded propagation runs
Then covariance grows monotonically and failsafe/no-fix semantics occur at thresholds.
**AC-4: Tile-write eligibility is conservative**
Given a frame and current estimate
When tile eligibility is requested
Then only sufficiently trusted poses are eligible for generated tile writes.
## Non-Functional Requirements
**Safety**
- Confidence must not be optimistic relative to known error/covariance.
**Reliability**
- State invariant violations are surfaced and recorded.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Healthy VIO update | Estimate emitted |
| AC-2 | Accepted/rejected anchors | State updates only on accepted evidence |
| AC-3 | Blackout thresholds | `dead_reckoned` then no-fix/failsafe |
| AC-4 | Tile eligibility | Covariance/quality gates enforced |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-3 | Blackout + spoofing SITL | Degraded behavior | QGC/FDR/fix fields match thresholds | Safety |
## Constraints
- The VIO backend is not the safety authority.
- The wrapper does not call Tile Manager directly during anchor acceptance; freshness/provenance arrives through anchor evidence.
## Risks & Mitigation
**Risk 1: Over-trusted dead reckoning**
- *Risk*: IMU-only propagation is believed for too long.
- *Mitigation*: Monotonic covariance growth and no-fix/failsafe thresholds.
_docs/02_tasks/done/AZ-233_test_infrastructure.md
-163
View File
@@ -1,163 +0,0 @@
# Test Infrastructure
**Task**: AZ-233_test_infrastructure
**Name**: Test Infrastructure
**Description**: Scaffold the blackbox and e2e test project: runner, deterministic fixtures, isolated replay/SITL environment, reporting, and external dependency stubs.
**Complexity**: 5 points
**Dependencies**: AZ-240_native_vio_backend_integration, AZ-241_real_satellite_vpr_descriptor_retrieval, AZ-242_real_anchor_feature_matching_ransac
**Component**: Blackbox Tests
**Tracker**: AZ-233
**Epic**: AZ-218
## Test Project Folder Layout
```text
e2e/
├── replay/
│ ├── run_replay.py
│ ├── scenarios/
│ └── reports/
├── fixtures/
│ ├── cache/
│ ├── mavlink/
│ ├── telemetry/
│ └── expected/
├── tests/
│ ├── test_still_image_replay.py
│ ├── test_vio_replay.py
│ ├── test_satellite_anchor.py
│ ├── test_blackout_spoofing.py
│ ├── test_resource_limits.py
│ └── test_security_gates.py
├── mocks/
│ ├── satellite_cache_stub/
│ ├── ardupilot_sitl/
│ └── qgc_observer/
└── reports/
```
### Layout Rationale
The test project keeps blackbox/e2e runner code outside product runtime internals. Scenario definitions, fixtures, mocks, and reports are separated so tests can reset state between runs and produce release evidence without importing private component modules.
Test implementation starts only after remediation tasks AZ-240, AZ-241, and AZ-242 close the native VIO, real satellite VPR, and real anchor matching gaps found during autodev verification.
## Mock Services
| Mock Service | Replaces | Interfaces | Behavior |
|-------------|----------|------------|----------|
| `satellite_cache_stub` | Offline Azaion Suite Satellite Service cache package | Local COG/manifest/descriptor fixture volume | Serves preloaded valid, stale, unsigned, hash-mismatched, and low-resolution cache fixtures; never performs network fetches during flight-mode tests. |
| `ardupilot_sitl` | ArduPilot Plane flight controller | MAVLink telemetry and `GPS_INPUT` receiving path | Emits generated IMU, attitude, GPS health, spoofing, and failsafe traces; records injected `GPS_INPUT` for assertions. |
| `qgc_observer` | QGroundControl status consumer | MAVLink/tlog parser | Records downsampled `STATUSTEXT`, status, and failsafe messages for rate and content assertions. |
### Mock Control API
Each mock or runner fixture must expose deterministic scenario controls for normal replay, stale cache, missing cache, spoofed GPS, blackout, restart, and resource-load modes. Recorded interactions must be queryable after each test run for assertions.
## Docker Test Environment
### `docker-compose.test.yml` Structure
| Service | Image / Build | Purpose | Depends On |
|---------|---------------|---------|------------|
| `gps-denied-service` | Project runtime image or local package mount | System under test | `satellite-cache-stub` |
| `replay-consumer` | Python replay/test harness | Feeds frames, telemetry, cache data, and faults | `gps-denied-service`, mock services |
| `satellite-cache-stub` | Fixture volume/service | Provides offline cache manifests, sidecars, descriptors, and generated invalid variants | none |
| `ardupilot-plane-sitl` | SITL container or local process wrapper | Validates `GPS_INPUT`, spoofing, and failsafe behavior | `gps-denied-service` |
| `qgc-observer` | MAVLink log parser | Verifies GCS-visible status output | `ardupilot-plane-sitl` |
### Networks and Volumes
- `replay-net`: connects the runtime, replay consumer, and satellite-cache stub.
- `sitl-net`: connects the runtime, ArduPilot Plane SITL, and QGC observer.
- `input-data`: read-only mount for `_docs/00_problem/input_data/`.
- `expected-results`: read-only mount for expected coordinate and report fixtures.
- `derkachi-replay`: read-only mount for `flight_derkachi.mp4` and `data_imu.csv`.
- `satellite-cache`: fixture cache volume with valid and invalid manifests.
- `fdr-output`: fresh per-run output volume for FDR and report artifacts.
## Test Runner Configuration
**Framework**: Python pytest-style replay harness.
**Entry point**: `run-blackbox-replay` or equivalent pytest command that executes scenario groups and writes reports.
**Reports**: CSV summary plus FDR validation Markdown.
### Fixture Strategy
| Fixture | Scope | Purpose |
|---------|-------|---------|
| `project_60_still_images` | session | Provides 60 nadir images and expected WGS84 centers. |
| `derkachi_video_telemetry` | session | Provides synchronized video, IMU, and `GLOBAL_POSITION_INT` replay data. |
| `cache_integrity_fixtures` | function | Provides valid, stale, unsigned, hash-mismatched, and low-resolution cache variants. |
| `sitl_spoofing_scenarios` | function | Provides generated GPS loss/spoofing and blackout traces. |
| `public_nadir_vio_candidates` | optional/session | Provides public or representative synchronized datasets when available. |
## Test Data Fixtures
| Data Set | Source | Format | Used By |
|----------|--------|--------|---------|
| `project_60_still_images` | `_docs/00_problem/input_data/` | JPG + metadata | Still-image accuracy, confidence, latency smoke |
| `expected_frame_centers` | `_docs/00_problem/input_data/coordinates.csv` and expected-results report | CSV/Markdown | Geolocation assertions |
| `derkachi_video_telemetry` | `_docs/00_problem/input_data/flight_derkachi/` | MP4 + CSV | VIO replay, latency, resilience |
| `cache_integrity_fixtures` | generated fixture volume | COG/manifest/sidecar/index fixtures | Cache freshness, poisoning, no-fetch tests |
| `sitl_spoofing_scenarios` | generated by SITL harness | MAVLink/tlog traces | Spoofing, blackout, failsafe, GCS status |
| `public_nadir_vio_candidates` | pinned external fixtures | dataset-specific | Final VIO and satellite-anchor validation |
### Data Isolation
Every run uses read-only input fixtures and fresh run-scoped output directories. FDR, generated tiles, tlogs, and reports are written only to per-run output volumes. Mock state and generated fixtures are reset before each scenario group.
## Test Reporting
**Format**: CSV summary and Markdown evidence report.
**Output paths**: `test-results/blackbox-report.csv` and `test-results/fdr-validation-summary.md`.
**Required columns**: Test ID, test name, input dataset, execution time, result, error distance, source label, covariance 95% semi-major, `GPS_INPUT.fix_type`, and error message.
## Acceptance Criteria
**AC-1: Test environment starts**
Given the Docker/replay test environment
When the test stack starts
Then the runtime, replay consumer, cache fixture, SITL, and observer services are reachable or report a clear blocked prerequisite.
**AC-2: External dependency stubs are deterministic**
Given a scenario config for cache, MAVLink, QGC, or fixture behavior
When the replay consumer executes it
Then mocks produce repeatable responses and expose recorded interactions for assertions.
**AC-3: Test runner executes scenario groups**
Given valid fixtures and a running test environment
When the test runner starts
Then it discovers and executes blackbox, performance, resilience, security, and resource-limit scenario groups.
**AC-4: Reports are generated**
Given a completed or blocked test run
When reporting finishes
Then CSV and Markdown evidence files are written with the required columns, metrics, artifact paths, and blocked-prerequisite reasons.
## Non-Functional Requirements
**Reliability**
- Missing hardware, public datasets, calibration, or SITL prerequisites are reported as `blocked`, not `passed`.
**Security**
- Fixture stubs must not access external satellite-provider or Suite service networks during in-flight test scenarios.
**Data Isolation**
- No test may mutate source fixtures or write FDR/generated-tile artifacts outside run-scoped output paths.
## Constraints
- The test suite must use public runtime boundaries only: navigation frames, telemetry, offline cache, MAVLink output, QGC status, and FDR outputs.
- The suite must not import private estimator, BASALT, wrapper, or tile-manager internals.
- Hardware-specific Jetson gates remain release-gate tests and may be skipped or blocked in ordinary local replay.
## Risks & Mitigation
**Risk 1: Environment prerequisites hide real failures**
- *Risk*: Missing hardware, calibration, or datasets could be treated as success.
- *Mitigation*: Report unavailable prerequisites as `blocked` with explicit artifact evidence.
**Risk 2: Fixture mutation contaminates later runs**
- *Risk*: Generated FDR, cache, or SITL output changes expected input fixtures.
- *Mitigation*: Use read-only fixture mounts and fresh run-scoped output volumes for every execution.
_docs/02_tasks/done/AZ-234_replay_geolocation_confidence_tests.md
-88
View File
@@ -1,88 +0,0 @@
# Replay Geolocation And Confidence Tests
**Task**: AZ-234_replay_geolocation_confidence_tests
**Name**: Replay Geolocation And Confidence Tests
**Description**: Implement blackbox tests for still-image geolocation, confidence/source-label output, and replay latency smoke.
**Complexity**: 3 points
**Dependencies**: AZ-233_test_infrastructure
**Component**: Blackbox Tests
**Tracker**: AZ-234
**Epic**: AZ-218
## Problem
The project needs deterministic blackbox evidence that the 60-image replay path emits WGS84 frame-center estimates with required confidence fields and latency metrics.
## Outcome
- Still-image replay reports per-frame coordinate error and aggregate threshold results.
- Every emitted estimate includes covariance, source label, and anchor-age fields.
- Replay smoke latency and dropped-frame metrics are captured in the shared report format.
## Scope
### Included
- FT-P-01 Still-Image Frame Center Geolocation.
- FT-P-02 Position Confidence Output Contract.
- NFT-PERF-01 Per-Frame Latency On Project Still Images.
- CSV and Markdown evidence output for these scenarios.
### Excluded
- Synchronized VIO video/IMU replay.
- Satellite-anchor VPR/local matching.
- Jetson-only release-gate profiling.
## Acceptance Criteria
**AC-1: Still-image coordinates are validated**
Given the 60-image project fixture and expected frame-center coordinates
When the replay test runs
Then per-frame WGS84 error is reported and aggregate 50 m / 20 m thresholds are evaluated.
**AC-2: Confidence output contract is validated**
Given emitted position estimates from the replay
When the test inspects public output fields
Then each estimate includes WGS84 coordinates, 95% covariance semi-major axis, source label, and anchor age.
**AC-3: Replay latency is measured**
Given the still-image replay runs at the configured smoke rate
When processing completes
Then capture-to-output latency and dropped-frame rate are recorded with pass/fail or blocked status.
## Non-Functional Requirements
**Performance**
- Replay smoke evidence includes p50/p95/p99 latency and dropped-frame rate.
**Reliability**
- Missing or invalid expected-coordinate fixtures fail fixture validation before scenario execution.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Expected-coordinate loader validation | Invalid coordinates are rejected before replay |
| AC-2 | Report field validation | Missing confidence/source fields fail the scenario |
| AC-3 | Latency metric aggregation | p50/p95/p99 and dropped-frame metrics are emitted |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | `project_60_still_images`, `expected_frame_centers` | FT-P-01 | >=80% within 50 m and >=50% within 20 m or explicit failure | Reliability |
| AC-2 | Same replay output | FT-P-02 | 100% of emitted estimates include required confidence fields | Reliability |
| AC-3 | Replay smoke run | NFT-PERF-01 | Latency and drop-rate metrics are recorded | Performance |
## Constraints
- Tests must use public replay input and output artifacts only.
- Input fixtures must be mounted read-only.
- Blocked prerequisites must be reported as `blocked`, not `passed`.
## Risks & Mitigation
**Risk 1: Calibration limits are mistaken for product failure**
- *Risk*: Fixture limits can make absolute accuracy inconclusive.
- *Mitigation*: Report the fixture source and threshold basis with each failure.
_docs/02_tasks/done/AZ-235_vio_replay_performance_tests.md
-89
View File
@@ -1,89 +0,0 @@
# VIO Replay Performance Tests
**Task**: AZ-235_vio_replay_performance_tests
**Name**: VIO Replay Performance Tests
**Description**: Implement synchronized video/IMU replay tests for VIO output, covariance evidence, and replay performance metrics.
**Complexity**: 5 points
**Dependencies**: AZ-233_test_infrastructure, AZ-240_native_vio_backend_integration
**Component**: Blackbox Tests
**Tracker**: AZ-235
**Epic**: AZ-218
## Problem
The runtime needs blackbox evidence that synchronized navigation video and flight-controller telemetry can drive VIO/wrapper output with honest confidence and measurable performance.
This test task must run after AZ-240 so it validates the real native VIO path rather than the deterministic scaffold.
## Outcome
- Derkachi video/telemetry fixture alignment is validated before replay.
- Synchronized replay produces frame-by-frame output or a clear blocked/failure reason.
- Latency, completion rate, memory, trajectory comparison, and calibration-gated checks are reported.
## Scope
### Included
- FT-P-03 BASALT VIO Replay With Synchronized Video/Telemetry.
- NFT-PERF-02 BASALT + Wrapper Replay Latency.
- Public/representative dataset prerequisite reporting.
### Excluded
- Satellite-anchor local verification.
- SITL spoofing/failsafe scenarios.
- Thermal/endurance release gates.
## Acceptance Criteria
**AC-1: Replay fixture alignment is validated**
Given the Derkachi MP4 and telemetry CSV
When fixture validation runs
Then duration, frame-to-telemetry ratio, and timestamp monotonicity are verified before replay.
**AC-2: Synchronized replay emits estimates**
Given a valid synchronized video/IMU replay fixture
When replay executes
Then estimates are emitted frame-by-frame with source labels, covariance, and segment evidence.
**AC-3: VIO performance evidence is reported**
Given replay completed or blocked
When reporting finishes
Then latency, completion rate, memory, and calibration/public-dataset prerequisite status are written.
## Non-Functional Requirements
**Performance**
- Reports include per-frame latency and memory metrics where the environment can measure them.
**Reliability**
- Calibration-gated absolute accuracy checks must be marked explicitly instead of silently passing.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Video/telemetry validator | Invalid duration or timestamp alignment blocks replay |
| AC-2 | Replay result parser | Missing per-frame confidence fields fail the scenario |
| AC-3 | Calibration gate reporting | Missing calibration/public data is reported as blocked |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | `derkachi_video_telemetry` | FT-P-03 fixture validation | Fixture accepted only when alignment rules pass | Reliability |
| AC-2 | Valid synchronized replay | FT-P-03 output | Continuous estimates for normal overlapping segments or explicit degradation | Reliability |
| AC-3 | Replay performance run | NFT-PERF-02 | Latency, completion rate, and memory evidence are recorded | Performance |
## Constraints
- Tests must not import BASALT/OpenVINS/Kimera internals directly.
- Public/representative datasets are optional prerequisites and may produce blocked results.
- Raw input video and telemetry fixtures remain read-only.
## Risks & Mitigation
**Risk 1: Hardware or dataset prerequisites are unavailable**
- *Risk*: The scenario cannot produce final accuracy evidence locally.
- *Mitigation*: Emit blocked results with exact missing prerequisite and continue other scenario groups.
_docs/02_tasks/done/AZ-236_satellite_anchor_cache_tests.md
-102
View File
@@ -1,102 +0,0 @@
# Satellite Anchor Cache Tests
**Task**: AZ-236_satellite_anchor_cache_tests
**Name**: Satellite Anchor Cache Tests
**Description**: Implement blackbox, security, and performance tests for satellite-anchor retrieval, local verification, cache integrity, and no in-flight external access.
**Complexity**: 5 points
**Dependencies**: AZ-233_test_infrastructure, AZ-241_real_satellite_vpr_descriptor_retrieval, AZ-242_real_anchor_feature_matching_ransac
**Component**: Blackbox Tests
**Tracker**: AZ-236
**Epic**: AZ-218
## Problem
Satellite anchors and cache fixtures are safety-critical: invalid, stale, poisoned, or externally fetched data must not become trusted localization output.
This test task must run after AZ-241 and AZ-242 so it validates real local VPR retrieval and real anchor feature matching rather than scaffold evidence gates.
## Outcome
- Accepted anchors include retrieval, matching, geometry, freshness, and provenance evidence.
- Invalid/stale/poisoned cache fixtures cannot produce trusted anchors or trusted generated tiles.
- No in-flight Satellite Service or provider access occurs when cache data is missing.
## Scope
### Included
- FT-P-04 Satellite Service And Anchor Verification.
- FT-N-01 Repetitive Or Low-Texture Imagery.
- FT-N-03 Invalid Or Stale Satellite Cache.
- NFT-PERF-03 Relocalization Trigger Path Latency.
- NFT-RES-04 Tile Cache Freshness Degradation.
- NFT-SEC-01 Signed Cache Manifest Enforcement.
- NFT-SEC-02 Cache Poisoning Write Gate.
- NFT-SEC-04 No In-Flight Satellite Provider Access.
- NFT-RES-LIM-03 Satellite Cache Storage Budget.
### Excluded
- VIO synchronized replay.
- MAVLink spoofing/failsafe behavior.
- Jetson thermal endurance.
## Acceptance Criteria
**AC-1: Verified anchors include evidence**
Given a valid local cache/index fixture and relocalization trigger
When retrieval and verification run
Then accepted anchors include candidate IDs, scores, MRE, inliers, covariance, and tile provenance.
**AC-2: Unsafe candidates are rejected**
Given low-texture, stale, unsigned, hash-mismatched, or low-resolution fixtures
When anchor/cache tests run
Then no invalid candidate emits a trusted `satellite_anchored` estimate or trusted generated tile.
**AC-3: No in-flight external access occurs**
Given flight-mode replay with missing cache data
When relocalization is requested
Then the system reports degraded/no-candidate behavior without satellite-provider or Suite service network calls.
**AC-4: Cache and trigger-path metrics are reported**
Given cache and relocalization scenarios complete
When reporting finishes
Then latency, MRE, trust level, freshness, and storage-budget evidence are written.
## Non-Functional Requirements
**Security**
- Invalid cache data must not be trusted or promoted.
**Performance**
- Trigger-path latency and bounded top-K behavior are measured.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Anchor evidence parser | Required evidence fields are present |
| AC-2 | Invalid cache fixture generator | Stale/unsigned/hash-mismatched fixtures are produced deterministically |
| AC-3 | Network-block assertion | Unexpected external calls fail the scenario |
| AC-4 | Cache metrics report | Latency, freshness, and storage metrics are present |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Public/cache fixture | FT-P-04 | Accepted anchors meet MRE/evidence requirements | Performance |
| AC-2 | Ambiguous and invalid cache fixtures | FT-N-01, FT-N-03, NFT-SEC-01, NFT-SEC-02 | 0 unsafe trusted outputs | Security |
| AC-3 | Network-blocked flight-mode replay | NFT-SEC-04 | Missing cache causes degraded behavior, not fetch | Security |
| AC-4 | Relocalization/cache runs | NFT-PERF-03, NFT-RES-04, NFT-RES-LIM-03 | Metrics and storage evidence are recorded | Performance |
## Constraints
- Tests must use local preloaded cache/index fixtures only.
- External network access during flight-mode scenarios is a failure.
- VPAir and UZH FPV licensing must be respected before use as commercial acceptance evidence.
## Risks & Mitigation
**Risk 1: Dataset licensing blocks final anchor evidence**
- *Risk*: Public dataset terms prevent commercial acceptance use.
- *Mitigation*: Mark dataset-specific checks blocked and keep generated cache fixtures for deterministic security coverage.
_docs/02_tasks/done/AZ-237_mavlink_blackout_spoofing_tests.md
-94
View File
@@ -1,94 +0,0 @@
# MAVLink Blackout Spoofing Tests
**Task**: AZ-237_mavlink_blackout_spoofing_tests
**Name**: MAVLink Blackout Spoofing Tests
**Description**: Implement SITL/replay tests for visual blackout, spoofed GPS, MAVLink source validation, degraded covariance, no-fix thresholds, and QGC status.
**Complexity**: 5 points
**Dependencies**: AZ-233_test_infrastructure
**Component**: Blackbox Tests
**Tracker**: AZ-237
**Epic**: AZ-218
## Problem
The system must prove that spoofed GPS and unauthorized MAVLink messages cannot override estimator state during visual blackout or degraded operation.
## Outcome
- Blackout and spoofing traces drive visible degraded-mode transitions.
- Covariance, `GPS_INPUT`, QGC status, and FDR evidence match the safety thresholds.
- Unauthorized MAVLink sources are rejected and recorded.
## Scope
### Included
- FT-N-02 GPS Spoofing During Total Visual Blackout.
- NFT-RES-01 Total Visual Blackout With GPS Spoofing.
- NFT-SEC-03 MAVLink Source And Spoofing Rejection.
### Excluded
- Still-image geolocation accuracy.
- Satellite-anchor cache poisoning.
- Cold-start and restart trials.
## Acceptance Criteria
**AC-1: Blackout transitions to dead reckoning**
Given a replay/SITL trace with total camera blackout and spoofed GPS
When the scenario runs
Then the system enters `dead_reckoned` mode within the required frame or timing threshold.
**AC-2: Degraded output thresholds are enforced**
Given blackout continues beyond configured thresholds
When estimates are emitted
Then covariance grows monotonically and `GPS_INPUT` fields degrade to no-fix/failsafe values at the specified limits.
**AC-3: Spoofed or unauthorized MAVLink inputs are rejected**
Given spoofed real-GPS measurements or unauthorized MAVLink source IDs
When messages arrive during normal or blackout operation
Then no confident position estimate is produced from those inputs.
**AC-4: Operator and FDR evidence is visible**
Given degraded-mode transitions occur
When reporting completes
Then QGC status and FDR evidence show promotion, demotion, blackout, and failsafe events at expected rates.
## Non-Functional Requirements
**Safety**
- Spoofed GPS must not be promoted during blackout without the documented recovery gates.
**Reliability**
- Missing SITL prerequisites are reported as blocked with exact setup evidence.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Scenario trigger builder | Blackout and spoofing events are generated deterministically |
| AC-2 | Threshold assertion logic | Fix type, covariance, and `horiz_accuracy` thresholds are checked |
| AC-3 | MAVLink source filter assertion | Unauthorized source messages fail the scenario |
| AC-4 | Status/FDR parser | Expected status events and rates are validated |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | SITL or replay spoofing trace | FT-N-02, NFT-RES-01 | Dead-reckoned transition within timing threshold | Safety |
| AC-2 | Continued blackout | FT-N-02, NFT-RES-01 | Monotonic covariance and no-fix/failsafe fields | Safety |
| AC-3 | Unauthorized/spoofed MAVLink messages | NFT-SEC-03 | No confident estimate from bad source | Safety |
| AC-4 | QGC/FDR outputs | FT-N-02, NFT-SEC-03 | Status and evidence are visible and rate-limited | Reliability |
## Constraints
- ArduPilot Plane SITL is the authoritative autopilot target.
- v1 asserts `GPS_INPUT` output and intentional absence of ODOMETRY.
- Tests must not depend on Mission Planner or PX4 behavior.
## Risks & Mitigation
**Risk 1: SITL setup varies by environment**
- *Risk*: Local runs may not have SITL installed or configured.
- *Mitigation*: Report blocked prerequisites clearly and keep replay-level assertions runnable where possible.
_docs/02_tasks/done/AZ-238_cold_start_restart_tests.md
-95
View File
@@ -1,95 +0,0 @@
# Cold Start Restart Tests
**Task**: AZ-238_cold_start_restart_tests
**Name**: Cold Start Restart Tests
**Description**: Implement tests for cold start, companion restart, sharp-turn/disconnected relocalization, and first-fix resource spikes.
**Complexity**: 5 points
**Dependencies**: AZ-233_test_infrastructure
**Component**: Blackbox Tests
**Tracker**: AZ-238
**Epic**: AZ-218
## Problem
The test suite must prove that the runtime recovers from disconnected visual segments and companion restarts without hiding missing prerequisites or unsafe degraded behavior.
## Outcome
- Sharp-turn/disconnected-segment scenarios trigger relocalization or explicit degraded output.
- Companion restart scenarios measure first valid output timing and FDR evidence.
- Cold-start trials record first-fix latency and resource spikes.
## Scope
### Included
- NFT-RES-02 Sharp Turn And Disconnected Segment Relocalization.
- NFT-RES-03 Companion Computer Restart Mid-Flight.
- NFT-PERF-04 Cold Boot Time To First Fix.
- NFT-RES-LIM-05 Cold Start Resource Spike.
### Excluded
- Long thermal endurance.
- FDR 8-hour rollover load.
- Cache poisoning and no-fetch security tests.
## Acceptance Criteria
**AC-1: Disconnected segments trigger relocalization**
Given a sharp-turn or disconnected segment fixture
When replay reaches the low-overlap transition
Then relocalization is requested and the system either reconnects via verified anchor or reports degraded status.
**AC-2: Companion restart recovery is measured**
Given a replay/SITL mission in progress
When the GPS-denied service is restarted
Then first valid output timing, FC-state handoff behavior, and FDR restart evidence are recorded.
**AC-3: Cold-start trials report first-fix timing**
Given cold-start conditions and local cache/index prerequisites
When 50 trials run or are blocked
Then the p95 time-to-first-fix result or exact blocked prerequisite is reported.
**AC-4: Cold-start resource spikes are captured**
Given initialization begins
When engines/indexes/cache are loaded
Then peak memory and initialization-stage timing are recorded where measurable.
## Non-Functional Requirements
**Reliability**
- Missing calibration, public datasets, or hardware prerequisites must not be treated as passing.
**Performance**
- First-fix timing and peak memory are reported with percentile summaries where enough trials run.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Relocalization trigger assertion | Missing-position thresholds trigger request checks |
| AC-2 | Restart report parser | Restart and first-output events are present |
| AC-3 | Trial aggregation | p95 first-fix summary or blocked reason is emitted |
| AC-4 | Resource metric parser | Peak memory and stage timings are captured |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Sharp-turn/disconnected replay | NFT-RES-02 | Verified relocalization or degraded evidence | Reliability |
| AC-2 | Mission restart trace | NFT-RES-03 | First valid output and FDR restart evidence | Reliability |
| AC-3 | Cold-start harness | NFT-PERF-04 | p95 first fix <30 s or blocked prerequisite | Performance |
| AC-4 | Cold-start resource monitoring | NFT-RES-LIM-05 | Peak memory <8 GB or blocked/failure evidence | Performance |
## Constraints
- Restart tests must preserve fixture read-only guarantees.
- Trial loops must be bounded and report partial results if interrupted.
- Hardware-only assertions must be clearly marked when not runnable locally.
## Risks & Mitigation
**Risk 1: Long cold-start trials are expensive**
- *Risk*: Full 50-run evidence may not be practical on every PR.
- *Mitigation*: Support smoke mode for PRs and full mode for release gates, with clear report labels.
_docs/02_tasks/done/AZ-239_jetson_resource_endurance_tests.md
-94
View File
@@ -1,94 +0,0 @@
# Jetson Resource Endurance Tests
**Task**: AZ-239_jetson_resource_endurance_tests
**Name**: Jetson Resource Endurance Tests
**Description**: Implement release-gate resource and endurance tests for Jetson memory, thermal/power behavior, and FDR rollover.
**Complexity**: 5 points
**Dependencies**: AZ-233_test_infrastructure
**Component**: Blackbox Tests
**Tracker**: AZ-239
**Epic**: AZ-218
## Problem
Release readiness requires hardware/resource evidence that cannot be proven by ordinary unit tests or short local replay runs.
## Outcome
- Jetson memory and thermal/power metrics are captured where hardware is available.
- FDR 8-hour synthetic load verifies rollover, storage cap, and retained payload classes.
- Hardware-only prerequisites are reported as blocked when not available.
## Scope
### Included
- NFT-RES-LIM-01 Jetson Memory Budget.
- NFT-RES-LIM-02 Thermal And Power Envelope.
- NFT-RES-LIM-04 Flight Data Recorder Rollover.
### Excluded
- Still-image replay accuracy.
- Satellite anchor/cache security tests.
- Cold-start first-fix trials.
## Acceptance Criteria
**AC-1: Jetson memory budget is measured**
Given Jetson hardware or equivalent production target is available
When sustained replay and trigger-path workload runs
Then CPU/GPU shared memory, process RSS, CUDA allocations, and OOM/throttle status are recorded.
**AC-2: Thermal and power endurance is validated or blocked**
Given thermal test prerequisites are available
When the sustained 25 W workload runs
Then throttle flags, temperatures, clocks, and latency are recorded for the required duration; otherwise the run reports blocked prerequisites.
**AC-3: FDR rollover is validated**
Given an 8-hour synthetic mission load
When FDR output reaches rollover conditions
Then storage remains within the cap, rollover is logged, and no payload class is silently dropped.
**AC-4: Evidence artifacts are complete**
Given resource/endurance scenarios complete or block
When reporting finishes
Then metrics, duration, environment, status, and artifact paths are written.
## Non-Functional Requirements
**Performance**
- Resource evidence must include duration and sampling interval.
**Reliability**
- Hardware-unavailable results are `blocked`, not `passed`.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Resource metric parser | Memory and throttle fields are present |
| AC-2 | Blocked prerequisite reporter | Missing hardware/thermal setup records blocked status |
| AC-3 | FDR rollover report parser | Storage, rollover, and payload-class fields are validated |
| AC-4 | Evidence manifest writer | Artifact paths and run metadata are present |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Jetson/prod-equivalent hardware | NFT-RES-LIM-01 | Peak memory <8 GB or explicit failure | Performance |
| AC-2 | Thermal/power test setup | NFT-RES-LIM-02 | No throttle over required duration or blocked/failure | Performance |
| AC-3 | Synthetic 8-hour mission load | NFT-RES-LIM-04 | FDR cap and rollover behavior are evidenced | Reliability |
| AC-4 | Resource/endurance reports | All included scenarios | Complete artifact manifest and status | Reliability |
## Constraints
- These tests are release-gate oriented and may be skipped or blocked in ordinary PR mode.
- Raw frames must not be retained during FDR load tests.
- Resource tests must not write outside run-scoped output directories.
## Risks & Mitigation
**Risk 1: Hardware gates are unavailable during local development**
- *Risk*: Developers cannot run full evidence locally.
- *Mitigation*: Support blocked status and separate PR smoke mode from release-gate execution.
_docs/02_tasks/done/AZ-240_native_vio_backend_integration.md
-95
View File
@@ -1,95 +0,0 @@
# Native VIO Backend Integration
**Task**: AZ-240_native_vio_backend_integration
**Name**: Native VIO Backend Integration
**Description**: Replace the deterministic VIO placeholder path with a real native backend integration boundary for representative replay.
**Complexity**: 5 points
**Dependencies**: AZ-228_vio_adapter
**Component**: VIO Adapter
**Tracker**: AZ-240
**Epic**: AZ-213
## Problem
The current VIO adapter satisfies the public contract with deterministic scaffold behavior, but it does not exercise a real native VIO backend for synchronized replay.
## Outcome
- A production-capable native VIO bridge is available behind the existing `VioBackend` protocol.
- Backend-specific setup remains isolated from the public VIO adapter boundary.
- Existing timestamp mismatch, tracking-loss, health, and no-WGS84-authority behavior is preserved.
## Scope
### Included
- Native/backend bridge implementation behind `VioBackend`.
- Backend initialization and runtime failure mapping into explicit health/error states.
- Replay-driven relative pose, velocity, bias, tracking quality, and covariance output.
- Tests that prove the real backend path is selected when configured.
### Excluded
- Absolute WGS84 authority or safety fusion.
- Satellite-anchor fallback logic.
- Direct test imports of backend internals.
## Dependencies
### Document Dependencies
- `_docs/02_document/components/02_vio_adapter/description.md`
- `_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: Native backend path emits VIO state**
Given synchronized replay frames and telemetry
When VIO processing runs with the native backend enabled
Then the adapter emits a relative VIO state packet from the native path.
**AC-2: Backend failures are explicit**
Given backend initialization or runtime failure
When VIO processing or health reporting runs
Then the adapter surfaces an explicit error and degraded or failed health state.
**AC-3: Existing safety boundaries remain intact**
Given timestamp mismatch, low tracking quality, or successful native output
When the adapter returns a result
Then degraded behavior, tracking quality, and absence of WGS84 authority remain intact.
## Non-Functional Requirements
**Performance**
- Replay execution must expose latency and memory metrics for later Jetson profiling gates.
**Reliability**
- Backend failures must not be hidden behind deterministic fallback success.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Configured native backend path | Native estimate is used, not deterministic fallback |
| AC-2 | Backend init/runtime failure | Explicit error and degraded/failed health |
| AC-3 | Timestamp/quality boundaries | Existing degraded/no-WGS84 behavior preserved |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Derkachi or representative synchronized replay | Native VIO replay path | Relative estimates are emitted or blocked with a real prerequisite reason | Performance |
## Constraints
- Keep backend-specific dependencies behind the `vio_adapter` native boundary.
- Do not make the VIO adapter the safety or WGS84 authority.
- If required native packages are unavailable locally, tests must skip or block with explicit prerequisite evidence rather than passing through the deterministic fallback.
## Risks & Mitigation
**Risk 1: Native dependency unavailable in local CI**
- *Risk*: The real backend cannot run on all developer machines.
- *Mitigation*: Provide dependency-gated tests that fail only when the backend is configured but broken, and report blocked prerequisites for full replay gates.
_docs/02_tasks/done/AZ-241_real_satellite_vpr_descriptor_retrieval.md
-95
View File
@@ -1,95 +0,0 @@
# Real Satellite VPR Descriptor Retrieval
**Task**: AZ-241_real_satellite_vpr_descriptor_retrieval
**Name**: Real Satellite VPR Descriptor Retrieval
**Description**: Replace the tuple-similarity satellite retrieval scaffold with the real local descriptor/index retrieval path promised by the Satellite Service design.
**Complexity**: 5 points
**Dependencies**: AZ-230_satellite_service_vpr_retrieval
**Component**: Satellite Service
**Tracker**: AZ-241
**Epic**: AZ-214
## Problem
The current Satellite Service can load in-memory descriptor records and rank them with local tuple similarity, but it does not yet integrate the real offline descriptor/index retrieval path.
## Outcome
- Local mission cache descriptor/index packages can be loaded by the runtime retrieval path.
- Retrieval uses the selected CPU FAISS/DINOv2-VLAD-compatible boundary where available.
- Freshness filtering, bounded top-K output, descriptor-fidelity checks, and no in-flight network behavior remain intact.
## Scope
### Included
- Local descriptor/index package loading from the offline cache boundary.
- Real local VPR retrieval implementation behind the public Satellite Service API.
- Explicit degraded/no-candidate/index failure behavior.
- Tests that distinguish the real retrieval path from the current tuple-similarity scaffold.
### Excluded
- Local feature matching, RANSAC, or anchor acceptance.
- In-flight provider or Suite service calls.
- TensorRT/ONNX optimization unless descriptor-fidelity gates are in place.
## Dependencies
### Document Dependencies
- `_docs/02_document/components/04_satellite_retrieval/description.md`
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
- `_docs/02_document/components/06_cache_tile_lifecycle/description.md`
## Acceptance Criteria
**AC-1: Real local index readiness is reported**
Given a valid local descriptor/index package
When the Satellite Service loads the package
Then readiness reflects the real local index and loaded record count.
**AC-2: Real top-K retrieval returns candidates**
Given a relocalization request and loaded local index
When retrieval runs
Then bounded candidates come from the real local descriptor/index path with scores, footprints, and freshness state.
**AC-3: Missing or invalid indexes degrade safely**
Given missing, corrupt, incompatible, or empty local index data
When retrieval runs
Then the result is explicit degraded/no-candidate behavior without unsafe anchors or network calls.
## Non-Functional Requirements
**Performance**
- Retrieval remains trigger-based and exposes latency metrics for Jetson profiling.
**Security**
- Retrieval must not perform in-flight provider or Suite service calls.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Real index package load | Ready status references loaded real index data |
| AC-2 | Query against fixture index | Candidates come from the real retrieval path |
| AC-3 | Missing/corrupt index | Explicit degraded/no-candidate result |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Public/cache fixture with descriptor index | VPR recall and top-K policy | Candidate bounds, freshness, and latency evidence are reported | Performance |
## Constraints
- Use only local preloaded cache/index data during flight-mode retrieval.
- Keep optional optimized engines behind descriptor-fidelity gates.
- Missing native/index prerequisites must be reported as blocked, not silently passed by the scaffold path.
## Risks & Mitigation
**Risk 1: Heavy native/index dependencies do not run in ordinary CI**
- *Risk*: The real retrieval path needs packages or data unavailable in local CI.
- *Mitigation*: Keep fast contract tests for package parsing and dependency-gated integration tests for real index execution.
_docs/02_tasks/done/AZ-242_real_anchor_feature_matching_ransac.md
-94
View File
@@ -1,94 +0,0 @@
# Real Anchor Feature Matching And RANSAC
**Task**: AZ-242_real_anchor_feature_matching_ransac
**Name**: Real Anchor Feature Matching And RANSAC
**Description**: Replace the precomputed evidence gate-only scaffold with real local feature matching and geometry verification behind the Anchor Verification boundary.
**Complexity**: 5 points
**Dependencies**: AZ-231_anchor_verification_matching, AZ-241_real_satellite_vpr_descriptor_retrieval
**Component**: Anchor Verification
**Tracker**: AZ-242
**Epic**: AZ-215
## Problem
The current Anchor Verification component can classify precomputed `MatchEvidence`, but it does not yet run real feature extraction, matching, homography estimation, or RANSAC/USAC geometry checks.
## Outcome
- Approved matcher profiles can compute correspondence evidence from frame imagery and candidate tile data.
- Geometry verification produces inliers, MRE, homography/provenance, runtime, and rejection reasons.
- Existing safety gates continue to reject unsafe candidates before any anchor is trusted.
## Scope
### Included
- Matcher bridge for approved ALIKED/DISK + LightGlue and SIFT/ORB baseline profiles where dependencies are available.
- Homography and RANSAC/USAC evidence generation from local imagery/tile fixtures.
- Integration with existing `GeometryGatedAnchorVerifier` decision output.
- Benchmark reporting from actual matching paths.
### Excluded
- VPR candidate ranking.
- Safety wrapper fusion/promotion policy.
- Per-frame steady-state VIO hot path execution.
## Dependencies
### Document Dependencies
- `_docs/02_document/components/05_anchor_verification/description.md`
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/components/04_satellite_retrieval/description.md`
## Acceptance Criteria
**AC-1: Matching path computes evidence**
Given a usable frame and fresh candidate tile
When anchor verification runs
Then matcher evidence is computed from local imagery and includes inliers, MRE, homography, provenance, and runtime.
**AC-2: Unsafe candidates are rejected**
Given low inliers, high reprojection error, stale or untrusted provenance, or geometry failure
When verification runs
Then no accepted anchor decision is emitted for that candidate.
**AC-3: Real matcher benchmark is reportable**
Given configured matcher profiles and fixture inputs
When benchmark runs
Then runtime and quality metrics are reported from actual matching paths.
## Non-Functional Requirements
**Performance**
- Learned matching remains trigger-based and benchmarked separately from the VIO hot path.
**Reliability**
- Missing matcher dependencies or fixture data must be explicit blocked prerequisites, not passing scaffold behavior.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Fixture matching path | Evidence is computed from imagery/tile input |
| AC-2 | Bad geometry/provenance | Candidate is rejected with reason |
| AC-3 | Matcher benchmark | Runtime and quality metrics come from real path |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1 | Aerial/cache fixture pair | Anchor verification path | Accepted anchors meet MRE/inlier gates with real evidence | Performance |
## Constraints
- Keep native feature extraction and RANSAC acceleration under `anchor_verification`.
- Do not trust precomputed evidence in production paths without provenance checks.
- SuperPoint or other legally restricted models remain excluded unless explicitly approved.
## Risks & Mitigation
**Risk 1: False anchor acceptance**
- *Risk*: Real cross-domain matching can produce plausible but unsafe geometry.
- *Mitigation*: Preserve freshness, provenance, inlier, MRE, and downstream safety gates; add negative fixtures for low-texture and stale-cache cases.
_docs/02_tasks/done/AZ-243_integrate_production_native_vio_runtime.md
-96
View File
@@ -1,96 +0,0 @@
# Integrate Production Native VIO Runtime
**Task**: AZ-243_integrate_production_native_vio_runtime
**Name**: Integrate Production Native VIO Runtime
**Description**: Close the VIO completeness gap by making production VIO execution use a real native runtime path instead of replay/scaffold behavior.
**Complexity**: 5 points
**Dependencies**: AZ-240_native_vio_backend_integration
**Component**: VIO Adapter
**Tracker**: AZ-243
**Epic**: AZ-213
## Problem
The VIO adapter exposes a native backend boundary, but the product completeness gate found that production behavior still does not execute a real native/BASALT VIO runtime. This lets downstream tests pass against scaffold behavior while the promised runtime capability is missing.
## Outcome
- Production VIO configuration selects and executes a real native runtime path.
- Missing native prerequisites fail closed with explicit configuration or runtime errors.
- Replay-only behavior remains available only for replay/development modes that explicitly opt into it.
## Scope
### Included
- Production native VIO runtime selection behind the VIO adapter boundary.
- Explicit startup/runtime errors when native runtime prerequisites are missing or invalid.
- Preservation of replay behavior for replay-only tests and development workflows.
- Tests proving production configuration does not silently fall back to replay behavior.
### Excluded
- Absolute WGS84 authority or safety fusion.
- Satellite-anchor fallback logic.
- Jetson performance tuning beyond reporting the native runtime prerequisite state.
## Dependencies
### Document Dependencies
- `_docs/02_document/components/02_vio_adapter/description.md`
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
- `_docs/03_implementation/implementation_completeness_cycle1_report.md`
## Acceptance Criteria
**AC-1: Production profile requires native VIO**
Given the system is configured for production VIO execution
When VIO initialization runs
Then the adapter selects the native runtime path and does not silently use replay behavior.
**AC-2: Missing native runtime fails closed**
Given production VIO configuration and an unavailable or invalid native runtime prerequisite
When VIO initialization or processing runs
Then the adapter reports an explicit configuration or runtime failure instead of emitting a successful replay-derived VIO state.
**AC-3: Replay mode remains explicit**
Given a replay-only development or test configuration
When VIO processing runs
Then replay behavior remains available only through that explicit mode and cannot be mistaken for production native execution.
## Non-Functional Requirements
**Reliability**
- Production startup must not hide missing native VIO capability behind deterministic or replay fallback success.
**Compatibility**
- Existing public VIO adapter contracts must remain stable for downstream safety, FDR, and test consumers.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Production VIO configuration | Native runtime path is selected, not replay fallback |
| AC-2 | Missing native runtime prerequisite | Explicit failure is surfaced and no successful replay-derived state is emitted |
| AC-3 | Replay-only configuration | Replay path works only when explicitly configured |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-1, AC-2 | Representative synchronized replay with production VIO profile | Runtime path selection and prerequisite handling | Native execution runs when available, or blocks with a real prerequisite reason | Reliability |
## Constraints
- Keep backend-specific dependencies behind the VIO adapter native boundary.
- Do not make the VIO adapter the safety or WGS84 authority.
- Do not satisfy production runtime behavior with a fake, deterministic, scaffold, or test-only backend.
- If local machines cannot execute the native runtime, tests must skip or block with an explicit prerequisite reason rather than passing through replay fallback.
## Risks & Mitigation
**Risk 1: Native runtime unavailable in local CI**
- *Risk*: The real native VIO runtime may not be installed on all developer machines.
- *Mitigation*: Gate native execution tests on explicit prerequisites, while still testing that production configuration fails closed when prerequisites are absent.