[AZ-230] Add local VPR retrieval boundary

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 18:49:37 +03:00
parent 087f4dba27
commit 07fb9535a9
8 changed files with 392 additions and 6 deletions
@@ -0,0 +1,89 @@
# 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.