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.

2026-06-21 08:21:13 +00:00 · 2026-05-03 10:27:44 +03:00
parent 35547e9b65
commit 5bf2dbd85f
39 changed files with 5543 additions and 181 deletions
@@ -8,7 +8,7 @@

 **Upstream dependencies**: Navigation camera, camera calibration files.

-**Downstream consumers**: BASALT VIO adapter, satellite retrieval, anchor verification, cache/tile lifecycle, FDR.
+**Downstream consumers**: BASALT VIO adapter, Satellite Service, anchor verification, Tile Manager, FDR.

 ## 2. Internal Interfaces

@@ -82,7 +82,7 @@ ImageQualityReport:

 | Helper | Purpose | Used By |
 |--------|---------|---------|
-| `geo_geometry_helper` | Coordinate transforms, GSD, WGS84/local conversions | Camera ingest, safety wrapper, cache lifecycle |
+| `geo_geometry_helper` | Coordinate transforms, GSD, WGS84/local conversions | Camera ingest, safety wrapper, Tile Manager |

 ## 6. Caveats & Edge Cases

@@ -98,7 +98,7 @@ ImageQualityReport:

 **Must be implemented after**: none.

-**Can be implemented in parallel with**: cache/tile lifecycle, MAVLink/GCS integration.
+**Can be implemented in parallel with**: Tile Manager, MAVLink/GCS integration.

 **Blocks**: BASALT VIO adapter, anchor verification, generated tile lifecycle.

@@ -58,7 +58,7 @@

 **Max execution time**: 100 ms per frame.

-**Dependencies**: Cache lifecycle test double.
+**Dependencies**: Tile Manager test double.

 ## Performance Tests

@@ -75,7 +75,7 @@ No persistent production data ownership. Reads calibration/config at startup and

 **Must be implemented after**: Camera ingest/calibration, MAVLink telemetry DTO definitions.

-**Can be implemented in parallel with**: satellite retrieval, cache lifecycle.
+**Can be implemented in parallel with**: Satellite Service, Tile Manager.

 **Blocks**: Safety/anchor wrapper final integration.

@@ -21,9 +21,9 @@

 **Traces to**: AC-2.1a, AC-2.2

-**Input data**: MUN-FRL preferred slice, or representative synchronized nav-camera + IMU + ground truth.
+**Input data**: Derkachi cropped nadir video + `SCALED_IMU2` + `GLOBAL_POSITION_INT`, MUN-FRL preferred slice, or representative synchronized nav-camera + IMU + ground truth.

-**Expected result**: VO registration succeeds for >95% of normal usable frames; frame-to-frame MRE <1.0 px where ground-truth/feature evaluation supports it.
+**Expected result**: VO registration succeeds for >95% of normal usable frames; frame-to-frame MRE <1.0 px where ground-truth/feature evaluation supports it. Derkachi runs are accepted as calibration-limited until intrinsics, distortion, and camera-to-body transform are pinned.

 **Max execution time**: Dataset-dependent; report per-frame latency.

@@ -82,7 +82,7 @@
 **Traces to**: AC-4.1, AC-4.2

 **Load scenario**:
- Input: synchronized public/representative replay.
+- Input: Derkachi synchronized replay and public/representative replay.
 - Duration: 30 minutes plus release long-run slice.
 - Target: Jetson Orin Nano Super.

@@ -130,8 +130,9 @@

 | Data Set | Description | Source | Size |
 |----------|-------------|--------|------|
+| `derkachi_video_telemetry` | Cropped nadir MP4 + synchronized IMU and `GLOBAL_POSITION_INT` trajectory | Project fixture | ~282 MB video + CSV |
 | `public_nadir_vio_candidates` | MUN-FRL/ALTO/Kagaru/EPFL slices | Public pinned fixtures | Dataset-dependent |
-| `representative_sync_replay` | Target camera + FC IMU + ground truth | Project collection | TBD |
+| `representative_sync_replay` | Target camera + FC IMU + calibrated ground truth | Project collection | TBD |

 **Setup procedure**: Pin calibration/extrinsics and mount read-only synchronized replay data.

@@ -8,7 +8,7 @@

 **Upstream dependencies**: BASALT VIO adapter, anchor verification, MAVLink telemetry, camera quality reports.

-**Downstream consumers**: MAVLink/GCS integration, FDR, cache/tile lifecycle, validation harness.
+**Downstream consumers**: MAVLink/GCS integration, FDR, Tile Manager, validation harness.

 ## 2. Internal Interfaces

@@ -73,7 +73,7 @@ No direct tile/image storage ownership. Writes all decisions to FDR via observab
 - Never emit optimistic accuracy when confidence is degraded.
 - On total occlusion or visual blackout, do not call VIO for that frame; propagate from the last trusted state with IMU-only dynamics, set `source_label=dead_reckoned`, and grow covariance monotonically.
 - If covariance or blackout thresholds exceed AC limits, emit no-fix/failsafe semantics.
- Treat cache freshness and provenance as evidence carried by `AnchorDecision`; do not call the cache lifecycle component directly during anchor acceptance.
+- Treat cache freshness and provenance as evidence carried by `AnchorDecision`; do not call the Tile Manager directly during anchor acceptance.

 ## 5. Caveats & Edge Cases

@@ -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
@@ -6,7 +6,7 @@

 **Architectural Pattern**: Validation pipeline.

-**Upstream dependencies**: Satellite retrieval, camera ingest/calibration, cache/tile lifecycle.
+**Upstream dependencies**: Satellite Service, camera ingest/calibration, Tile Manager.

 **Downstream consumers**: Safety/anchor wrapper, FDR.

@@ -74,7 +74,7 @@ AnchorDecision:

 ## 6. Dependency Graph

-**Must be implemented after**: satellite retrieval candidate DTOs, cache tile access.
+**Must be implemented after**: Satellite Service candidate DTOs, Tile Manager tile access.

 **Can be implemented in parallel with**: BASALT VIO adapter.

@@ -1,23 +1,24 @@
-# Cache And Tile Lifecycle
+# Tile Manager

 ## 1. High-Level Overview

-**Purpose**: Manage offline service-source tiles, manifests, descriptor metadata, freshness/provenance checks, generated tile writes, and post-flight sync packaging.
+**Purpose**: Manage local tiles: service-source COGs, manifests, descriptor metadata, freshness/provenance checks, nadir-image orthorectification into generated tiles, generated tile writes, and post-flight package preparation.

 **Architectural Pattern**: Repository + policy gate.

 **Upstream dependencies**: Satellite Service cache packages, safety/anchor wrapper, camera ingest/calibration.

-**Downstream consumers**: Satellite retrieval, anchor verification, FDR, post-flight sync.
+**Downstream consumers**: Satellite Service, anchor verification, FDR, post-flight sync.

 ## 2. Internal Interfaces

-### Interface: `CacheRepository`
+### Interface: `TileManager`

 | Method | Input | Output | Async | Error Types |
 |--------|-------|--------|-------|-------------|
 | `validate_cache` | `CacheValidationRequest` | `CacheValidationReport` | No | `ManifestInvalid`, `SignatureInvalid` |
 | `get_tile_window` | `TileWindowRequest` | `TileWindow` | No | `TileUnavailable`, `TileRejected` |
+| `orthorectify_frame` | `TileGenerationRequest` | `GeneratedTileCandidate` | Yes | `TileWriteRejected`, `FrameNotUsable` |
 | `write_generated_tile` | `GeneratedTileRequest` | `GeneratedTileRecord` | Yes | `TileWriteRejected`, `StorageFull` |
 | `package_sync` | `SyncPackageRequest` | `SyncPackage` | Yes | `PackageFailed` |

@@ -26,7 +27,7 @@
 | Query | Frequency | Hot Path | Index Needed |
 |-------|-----------|----------|--------------|
 | Tile by footprint/time/freshness | Per retrieval/anchor | Yes during relocalization | Spatial/time indexes |
-| Descriptor metadata by chunk | Per retrieval | Yes during relocalization | Chunk ID index |
+| Descriptor metadata by chunk | Per Satellite Service retrieval | Yes during relocalization | Chunk ID index |
 | Generated tile by mission/sector | Post-flight | No | Mission ID index |

 ### Caching Strategy
@@ -53,6 +54,7 @@
 |---------|---------|
 | PostgreSQL + PostGIS | Manifest, spatial metadata, freshness queries, and generated-tile metadata |
 | GDAL/rasterio candidate | COG read/write |
+| OpenCV/GDAL geometry utilities | Nadir-frame orthorectification into generated COG tiles |
 | Cryptographic hash/signature library | Sidecar validation |

 **Error Handling Strategy**:
@@ -75,7 +77,7 @@

 **Can be implemented in parallel with**: camera ingest, MAVLink integration.

-**Blocks**: satellite retrieval, anchor verification, generated tile lifecycle.
+**Blocks**: Satellite Service retrieval, anchor verification, generated tile lifecycle.

 ## 7. Logging Strategy

@@ -1,4 +1,4 @@
-# Test Specification — Cache And Tile Lifecycle
+# Test Specification — Tile Manager

 ## Acceptance Criteria Traceability

@@ -47,7 +47,7 @@

 ### IT-03: Generated Tile Write

-**Summary**: Verify generated tiles are written only when pose and frame quality gates pass.
+**Summary**: Verify nadir frames are orthorectified and written as generated tiles only when pose and frame quality gates pass.

 **Traces to**: AC-8.4

@@ -111,7 +111,7 @@

 ### ST-02: Raw Frame Persistence Check

-**Summary**: Verify cache lifecycle persists tiles, not raw frames.
+**Summary**: Verify Tile Manager persists tiles, not raw frames.

 **Traces to**: AC-8.5

@@ -149,7 +149,7 @@

 | Step | Action | Expected Result |
 |------|--------|-----------------|
-| 1 | Write generated candidate tile | COG + sidecar + PostGIS manifest row created |
+| 1 | Orthorectify and write generated candidate tile | COG + sidecar + PostGIS manifest row created |
 | 2 | Package post-flight sync | Manifest delta includes trust level and parent covariance |
 | 3 | Inspect package | No tile is marked trusted basemap by onboard runtime |

@@ -52,7 +52,7 @@ No persistent data ownership; telemetry and emitted packets are mirrored to FDR.

 **Must be implemented after**: position estimate DTO and MAVLink output contract.

-**Can be implemented in parallel with**: cache lifecycle, camera ingest.
+**Can be implemented in parallel with**: Tile Manager, camera ingest.

 **Blocks**: SITL integration and production FC output.

@@ -30,15 +30,15 @@

 ---

-### IT-02: Public VIO Replay Runner
+### IT-02: Synchronized VIO Replay Runner

-**Summary**: Verify public/representative synchronized data can drive BASALT/wrapper tests.
+**Summary**: Verify Derkachi and public/representative synchronized data can drive BASALT/wrapper tests.

 **Traces to**: AC-1.3, AC-2.1a, AC-2.2

-**Input data**: MUN-FRL preferred slice or representative synchronized dataset.
+**Input data**: Derkachi cropped nadir video + telemetry fixture, MUN-FRL preferred slice, or representative synchronized dataset.

-**Expected result**: Runner validates trajectory, VIO registration, latency, and covariance calibration.
+**Expected result**: Runner validates fixture alignment, trajectory comparison, VIO registration, latency, and covariance calibration where calibration data supports it.

 **Max execution time**: Dataset-dependent.

@@ -128,7 +128,7 @@

 ---

-### IT-09: Cache And Tile Lifecycle Runner
+### IT-09: Tile Manager Runner

 **Summary**: Verify cache, generated tiles, and storage tests are executable.