mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 13:21:13 +00:00
[AZ-240] [AZ-241] [AZ-242] Add native retrieval remediation
Implement the product remediation paths required before greenfield code testability revision: native VIO backend selection, local VPR descriptor index retrieval, and computed anchor matching gates. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user