Update autodev state documentation to reflect progress in the Decompose phase, changing the current step from 5 to 6. Revise sub-step details to indicate a shift to phase 2, focusing on module layout for the Satellite Service and Tile Manager, and awaiting confirmation before product task decomposition. Additionally, enhance problem documentation to clarify the original still-image sample limitations and introduce the Derkachi representative fixture for improved data validation. Update references to the Tile Manager and Satellite Service throughout the documentation for consistency.

This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 10:27:44 +03:00
parent 35547e9b65
commit 5bf2dbd85f
39 changed files with 5543 additions and 181 deletions
@@ -1,21 +1,23 @@
# Satellite Retrieval
# Satellite Service
## 1. High-Level Overview
**Purpose**: Convert a query frame and prior state into ranked satellite/cache VPR chunk candidates using DINOv2-VLAD descriptors and FAISS.
**Purpose**: Own the onboard boundary to the suite Satellite Service: import pre-flight mission cache packages, upload generated-tile packages after flight, and convert query frames into ranked local VPR candidates using preloaded DINOv2-VLAD descriptors and FAISS.
**Architectural Pattern**: Query service / retrieval index adapter.
**Architectural Pattern**: Offline sync gateway + local retrieval index adapter.
**Upstream dependencies**: Camera ingest/calibration, cache/tile lifecycle, safety/anchor wrapper.
**Upstream dependencies**: Camera ingest/calibration, Tile Manager, safety/anchor wrapper, Azaion Suite Satellite Service before/after flight.
**Downstream consumers**: Anchor verification, FDR.
## 2. Internal Interfaces
### Interface: `CandidateRetriever`
### Interface: `SatelliteService`
| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `import_mission_cache` | `CacheImportRequest` | `CacheImportResult` | Yes | `SyncUnavailable`, `PackageInvalid` |
| `upload_generated_tiles` | `GeneratedTileUploadRequest` | `GeneratedTileUploadResult` | Yes | `SyncUnavailable`, `PackageRejected` |
| `retrieve` | `RetrievalRequest` | `RetrievalResult` | Yes | `IndexUnavailable`, `DescriptorFailed` |
| `load_index` | `IndexLoadRequest` | `IndexStatus` | No | `ManifestInvalid`, `IndexUnavailable` |
@@ -49,11 +51,12 @@ VprCandidate:
| Query | Frequency | Hot Path | Index Needed |
|-------|-----------|----------|--------------|
| Top-K FAISS search | Triggered only | No steady-state | FAISS index |
| Import/export package sync | Pre-flight / post-flight only | No mid-flight | Package manifest and sidecar hashes |
| Load chunk metadata | Per candidate | No | PostgreSQL/PostGIS spatial and chunk indexes |
## 4. Implementation Details
**State Management**: Holds loaded descriptor model and FAISS index handles.
**State Management**: Holds loaded descriptor model and FAISS index handles; tracks pre-flight import and post-flight upload package status.
**Key Dependencies**:
@@ -61,16 +64,19 @@ VprCandidate:
|---------|---------|
| DINOv2 / ONNX / TensorRT candidate path | Query descriptor extraction |
| FAISS CPU | Top-K retrieval |
| Satellite Service client | Pre-flight cache import and post-flight generated-tile upload |
**Error Handling Strategy**:
- If descriptor extraction or index load fails, return no candidates and trigger degraded mode.
- Optimized engines are allowed only after descriptor-fidelity tests pass.
- Network/package sync failures are allowed only before takeoff or after landing; during flight, the component must never call a satellite provider or suite service.
## 5. Caveats & Edge Cases
**Known limitations**:
- VPR result is only a candidate, never an accepted fix.
- Cross-domain retrieval can be wrong under seasonal, lighting, or terrain ambiguity.
- External Satellite Service availability cannot be part of the mid-flight localization safety case.
**Performance bottlenecks**:
- Descriptor extraction on Jetson must be trigger-limited and profiled separately from BASALT.
@@ -1,4 +1,4 @@
# Test Specification — Satellite Retrieval
# Test Specification — Satellite Service
## Acceptance Criteria Traceability
@@ -31,7 +31,7 @@
---
### IT-02: Sharp-Turn Retrieval Trigger
### IT-02: Sharp-Turn Local Retrieval Trigger
**Summary**: Verify sharp-turn state requests candidates rather than relying on frame-to-frame VO.
@@ -39,7 +39,7 @@
**Input data**: Wrapper relocalization request with sharp-turn/loss reason.
**Expected result**: Retrieval returns bounded top-K candidates based on sector/covariance policy.
**Expected result**: Satellite Service returns bounded top-K candidates from preloaded local indexes based on sector/covariance policy.
**Max execution time**: 2 seconds per query.
@@ -126,6 +126,25 @@
**Pass criteria**: 0 stale candidates without explicit stale/down-confidence metadata.
---
### ST-02: No Mid-Flight Satellite Service Calls
**Summary**: Verify relocalization never performs satellite-provider or suite Satellite Service network calls during flight.
**Traces to**: AC-8.3, R-SAT-01
**Attack vector**: Runtime attempts to fetch missing cache/index data over the network during relocalization.
**Test procedure**:
1. Disable external network access during a replay scenario.
2. Trigger relocalization against preloaded cache fixtures.
3. Inspect network call logs and Satellite Service client telemetry.
**Expected behavior**: Retrieval uses only mounted local cache/index data; missing data produces degraded/no-candidate behavior, not a network fetch.
**Pass criteria**: 0 mid-flight Satellite Service or satellite-provider calls.
## Acceptance Tests
### AT-01: Relocalization Candidate Returned