mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 12:41:13 +00:00
Revise acceptance criteria and restrictions documentation to clarify recent updates and specifications. Key changes include enhanced definitions for position accuracy, image processing quality, and operational parameters, as well as updates to camera specifications and validation requirements. This revision aims to improve clarity and ensure alignment with project goals.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,90 @@
|
||||
# Cache And Tile Lifecycle
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Manage offline service-source tiles, manifests, descriptor metadata, freshness/provenance checks, generated tile writes, and post-flight sync packaging.
|
||||
|
||||
**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.
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Interface: `CacheRepository`
|
||||
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `validate_cache` | `CacheValidationRequest` | `CacheValidationReport` | No | `ManifestInvalid`, `SignatureInvalid` |
|
||||
| `get_tile_window` | `TileWindowRequest` | `TileWindow` | No | `TileUnavailable`, `TileRejected` |
|
||||
| `write_generated_tile` | `GeneratedTileRequest` | `GeneratedTileRecord` | Yes | `TileWriteRejected`, `StorageFull` |
|
||||
| `package_sync` | `SyncPackageRequest` | `SyncPackage` | Yes | `PackageFailed` |
|
||||
|
||||
## 3. Data Access Patterns
|
||||
|
||||
| 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 |
|
||||
| Generated tile by mission/sector | Post-flight | No | Mission ID index |
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
| Data | Cache Type | TTL | Invalidation |
|
||||
|------|------------|-----|--------------|
|
||||
| Manifest metadata | PostgreSQL/PostGIS query cache / process cache | Mission duration | New mission cache load |
|
||||
| Sidecar verification | In-memory result cache | Mission duration | File hash change |
|
||||
|
||||
### Storage Estimates
|
||||
|
||||
| Table/Collection | Est. Row Count | Row Size | Total Size | Growth Rate |
|
||||
|------------------|----------------|----------|------------|-------------|
|
||||
| Cache manifest tiles | Mission-dependent | Small metadata | Within ~10 GB package with imagery | Per mission |
|
||||
| Generated tiles | Flight-dependent | Metadata + COG payload | FDR/cache budget constrained | Per flight |
|
||||
|
||||
## 4. Implementation Details
|
||||
|
||||
**State Management**: Owns PostgreSQL/PostGIS manifest connection, sidecar verification state, and generated tile staging area.
|
||||
|
||||
**Key Dependencies**:
|
||||
|
||||
| Library | Purpose |
|
||||
|---------|---------|
|
||||
| PostgreSQL + PostGIS | Manifest, spatial metadata, freshness queries, and generated-tile metadata |
|
||||
| GDAL/rasterio candidate | COG read/write |
|
||||
| Cryptographic hash/signature library | Sidecar validation |
|
||||
|
||||
**Error Handling Strategy**:
|
||||
- Invalid signatures/hashes reject tiles.
|
||||
- Storage-full blocks generated tile writes without affecting localization output.
|
||||
- Cache validation failure blocks mission cache usage.
|
||||
|
||||
## 5. Caveats & Edge Cases
|
||||
|
||||
**Known limitations**:
|
||||
- JSON-only manifests are avoided for scale and queryability, but signed JSON sidecars remain required for audit/interchange.
|
||||
- PostgreSQL/PostGIS must be available locally before flight; runtime cannot depend on a remote DB link.
|
||||
|
||||
**Potential race conditions**:
|
||||
- Generated tile and PostgreSQL manifest update must be atomic enough to avoid orphan trusted metadata.
|
||||
|
||||
## 6. Dependency Graph
|
||||
|
||||
**Must be implemented after**: data model schema decisions.
|
||||
|
||||
**Can be implemented in parallel with**: camera ingest, MAVLink integration.
|
||||
|
||||
**Blocks**: satellite retrieval, anchor verification, generated tile lifecycle.
|
||||
|
||||
## 7. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | Cache package invalid | `cache_manifest_invalid reason=signature` |
|
||||
| WARN | Tile rejected | `tile_rejected reason=stale tile_id=...` |
|
||||
| INFO | Generated tile staged | `generated_tile_written tile_id=...` |
|
||||
|
||||
**Log format**: FDR structured event.
|
||||
|
||||
**Log storage**: FDR segment plus cache validation report.
|
||||
@@ -0,0 +1,167 @@
|
||||
# Test Specification — Cache And Tile Lifecycle
|
||||
|
||||
## Acceptance Criteria Traceability
|
||||
|
||||
| AC ID | Acceptance Criterion | Test IDs | Coverage |
|
||||
|-------|---------------------|----------|----------|
|
||||
| AC-4.2 | Memory/storage pressure | PT-01 | Covered |
|
||||
| AC-8.1 | Resolution at cache interface | IT-01 | Covered |
|
||||
| AC-8.2 | Freshness thresholds | IT-02, ST-01 | Covered |
|
||||
| AC-8.3 | Preloaded/preprocessed offline cache | IT-01 | Covered |
|
||||
| AC-8.4 | Mid-flight tile generation/write-back | IT-03, AT-01 | Covered |
|
||||
| AC-8.5 | Persistent imagery policy | ST-02 | Covered |
|
||||
| AC-8.6 | VPR chunk metadata | IT-04 | Covered |
|
||||
| AC-NEW-3 | FDR/tile storage cap interaction | PT-01 | Covered |
|
||||
| AC-NEW-6 | Imagery freshness enforcement | IT-02, ST-01 | Covered |
|
||||
| AC-NEW-7 | Cache-poisoning safety budget | ST-03, AT-01 | Covered |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
### IT-01: Mission Cache Validation
|
||||
|
||||
**Summary**: Verify preloaded COGs, PostGIS metadata, sidecars, descriptors, and indexes validate before flight.
|
||||
|
||||
**Traces to**: AC-8.1, AC-8.3
|
||||
|
||||
**Input data**: Mission cache package with COGs, signed JSON sidecars, PostGIS manifest seed, FAISS index files.
|
||||
|
||||
**Expected result**: Valid cache passes resolution, hash, signature, descriptor-reference, and spatial coverage checks.
|
||||
|
||||
**Max execution time**: 5 minutes per cache fixture.
|
||||
|
||||
---
|
||||
|
||||
### IT-02: Freshness Gate
|
||||
|
||||
**Summary**: Verify active-conflict and stable-rear freshness rules.
|
||||
|
||||
**Traces to**: AC-8.2, AC-NEW-6
|
||||
|
||||
**Input data**: Tiles at fresh, grace, and stale ages for both sector classes.
|
||||
|
||||
**Expected result**: Fresh tiles pass, grace tiles are down-confidence weighted if allowed, stale tiles are rejected and cannot emit `satellite_anchored`.
|
||||
|
||||
**Max execution time**: 2 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-03: Generated Tile Write
|
||||
|
||||
**Summary**: Verify generated tiles are written only when pose and frame quality gates pass.
|
||||
|
||||
**Traces to**: AC-8.4
|
||||
|
||||
**Input data**: Frame metadata, pose covariance <=3 m, <=5 m, and >5 m.
|
||||
|
||||
**Expected result**: <=3 m writes full-quality candidate, 3-5 m writes soft candidate, >5 m rejects write.
|
||||
|
||||
**Max execution time**: 2 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-04: VPR Chunk Metadata
|
||||
|
||||
**Summary**: Verify chunk metadata supports retrieval rules.
|
||||
|
||||
**Traces to**: AC-8.6
|
||||
|
||||
**Input data**: Operational-area cache manifest.
|
||||
|
||||
**Expected result**: Chunks are 600-800 m equivalent footprint with 40-50% overlap and multi-scale active-sector descriptors.
|
||||
|
||||
**Max execution time**: 2 minutes.
|
||||
|
||||
## Performance Tests
|
||||
|
||||
### PT-01: Cache And FDR Storage Budget
|
||||
|
||||
**Summary**: Verify cache metadata and generated tile writes stay within storage/memory budgets.
|
||||
|
||||
**Traces to**: AC-4.2, AC-NEW-3
|
||||
|
||||
**Load scenario**:
|
||||
- Mission cache: up to operational budget.
|
||||
- Generated tiles: 8-hour synthetic flight.
|
||||
|
||||
| Metric | Target | Failure Threshold |
|
||||
|--------|--------|-------------------|
|
||||
| Persistent cache | <=10 GB unless split budget approved | >budget without report |
|
||||
| FDR + generated artifacts | <=64 GB per flight | >64 GB without rollover |
|
||||
| DB query p95 | <=50 ms for indexed tile lookup | >150 ms |
|
||||
|
||||
**Resource limits**: PostgreSQL/PostGIS stays within total system 8 GB memory budget.
|
||||
|
||||
## Security Tests
|
||||
|
||||
### ST-01: Signed Manifest Enforcement
|
||||
|
||||
**Summary**: Verify unsigned/tampered/stale manifests are rejected.
|
||||
|
||||
**Traces to**: AC-8.2, AC-NEW-6
|
||||
|
||||
**Attack vector**: Tampered sidecar, bad hash, unsigned manifest.
|
||||
|
||||
**Test procedure**: Load invalid cache variants and run validation.
|
||||
|
||||
**Expected behavior**: Invalid tiles are rejected and logged.
|
||||
|
||||
**Pass criteria**: 0 invalid cache entries become available to retrieval/anchor verification.
|
||||
|
||||
---
|
||||
|
||||
### ST-02: Raw Frame Persistence Check
|
||||
|
||||
**Summary**: Verify cache lifecycle persists tiles, not raw frames.
|
||||
|
||||
**Traces to**: AC-8.5
|
||||
|
||||
**Attack vector**: Raw frames accidentally stored as generated artifacts.
|
||||
|
||||
**Test procedure**: Run tile generation and inspect cache/FDR outputs.
|
||||
|
||||
**Expected behavior**: Only COG tiles, sidecars, manifests, and allowed failed-frame thumbnails exist.
|
||||
|
||||
**Pass criteria**: No raw full-resolution frames retained.
|
||||
|
||||
---
|
||||
|
||||
### ST-03: Cache Poisoning Gate
|
||||
|
||||
**Summary**: Verify misaligned generated tiles cannot become trusted basemap.
|
||||
|
||||
**Traces to**: AC-NEW-7
|
||||
|
||||
**Attack vector**: Over-confident pose writes misaligned generated tile.
|
||||
|
||||
**Test procedure**: Inject deflated covariance and wrong pose during tile write.
|
||||
|
||||
**Expected behavior**: Tile is rejected or marked candidate/soft; never promoted to trusted by onboard component.
|
||||
|
||||
**Pass criteria**: 0 direct trusted basemap promotions onboard.
|
||||
|
||||
## Acceptance Tests
|
||||
|
||||
### AT-01: Generated Tile Package For Satellite Service
|
||||
|
||||
**Summary**: Verify post-flight sync package contains valid generated tiles and metadata.
|
||||
|
||||
**Traces to**: AC-8.4, AC-NEW-7
|
||||
|
||||
| Step | Action | Expected Result |
|
||||
|------|--------|-----------------|
|
||||
| 1 | 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 |
|
||||
|
||||
## Test Data Management
|
||||
|
||||
| Data Set | Description | Source | Size |
|
||||
|----------|-------------|--------|------|
|
||||
| `cache_integrity_fixtures` | Valid/stale/unsigned/hash-mismatched manifests | Generated fixture | Small |
|
||||
| `mission_cache_fixture` | COGs, descriptors, PostGIS seed | Satellite Service stub | Mission-dependent |
|
||||
|
||||
**Setup procedure**: Restore isolated PostgreSQL/PostGIS schema and mount cache fixture read-only except generated-tile staging.
|
||||
|
||||
**Teardown procedure**: Drop schema and delete generated staging volume.
|
||||
|
||||
**Data isolation strategy**: Per-run mission ID, schema, and staging directory.
|
||||
Reference in New Issue
Block a user