# Satellite Retrieval

## 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.

**Architectural Pattern**: Query service / retrieval index adapter.

**Upstream dependencies**: Camera ingest/calibration, cache/tile lifecycle, safety/anchor wrapper.

**Downstream consumers**: Anchor verification, FDR.

## 2. Internal Interfaces

### Interface: `CandidateRetriever`

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `retrieve` | `RetrievalRequest` | `RetrievalResult` | Yes | `IndexUnavailable`, `DescriptorFailed` |
| `load_index` | `IndexLoadRequest` | `IndexStatus` | No | `ManifestInvalid`, `IndexUnavailable` |

**Input DTOs**:

```yaml
RetrievalRequest:
  frame: FramePacket
  prior_estimate: PositionEstimate optional
  search_radius_m: number optional
  max_candidates: integer
```

**Output DTOs**:

```yaml
RetrievalResult:
  query_descriptor_id: string
  candidates: list[VprCandidate]

VprCandidate:
  chunk_id: string
  tile_id: string
  score: number
  footprint: geometry
  freshness_status: enum
```

## 3. Data Access Patterns

| Query | Frequency | Hot Path | Index Needed |
|-------|-----------|----------|--------------|
| Top-K FAISS search | Triggered only | No steady-state | FAISS index |
| 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.

**Key Dependencies**:

| Library | Purpose |
|---------|---------|
| DINOv2 / ONNX / TensorRT candidate path | Query descriptor extraction |
| FAISS CPU | Top-K retrieval |

**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.

## 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.

**Performance bottlenecks**:
- Descriptor extraction on Jetson must be trigger-limited and profiled separately from BASALT.

## 6. Dependency Graph

**Must be implemented after**: cache manifest/index schema, camera frame DTOs.

**Can be implemented in parallel with**: anchor verification.

**Blocks**: satellite relocalization flow.

## 7. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| ERROR | Index unavailable | `faiss_index_unavailable id=...` |
| WARN | No candidates | `vpr_no_candidates frame_id=...` |
| INFO | Retrieval invoked | `vpr_query candidates=... latency_ms=...` |

**Log format**: FDR structured event.

**Log storage**: FDR segment.