mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 21:31:13 +00:00
[AZ-223] [AZ-224] [AZ-225] [AZ-227] Add runtime gateways
Implement the first runtime component boundaries around the shared contracts so downstream batches can consume typed frame, MAVLink, tile, and FDR behavior with focused tests and batch evidence. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -1,89 +0,0 @@
|
||||
# Camera Ingest Calibration And Frame Quality
|
||||
|
||||
**Task**: AZ-223_camera_ingest_calibration
|
||||
**Name**: Camera Ingest Calibration And Frame Quality
|
||||
**Description**: Ingest navigation frames, attach calibration/timestamp metadata, classify quality, detect occlusion, and provide north-up normalization hints.
|
||||
**Complexity**: 5 points
|
||||
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry
|
||||
**Component**: Camera Ingest And Calibration
|
||||
**Tracker**: AZ-223
|
||||
**Epic**: AZ-209
|
||||
|
||||
## Problem
|
||||
|
||||
Downstream VIO, retrieval, anchor verification, Tile Manager, and FDR need trustworthy frame metadata and quality decisions before using image data.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Replay and live-source frames are exposed with timestamps, calibration ID, quality, occlusion, and normalization hints.
|
||||
- Total occlusion/blackout frames are marked unusable for VIO and anchor paths.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Frame source abstraction for replay/live camera boundary.
|
||||
- Calibration metadata loading and validation.
|
||||
- Quality and occlusion reports.
|
||||
- North-up/orthorectification hints as metadata, not unconditional frame mutation.
|
||||
|
||||
### Excluded
|
||||
- Tile writing and generated COG persistence.
|
||||
- BASALT processing.
|
||||
|
||||
## 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: Usable frame packet emitted**
|
||||
Given a valid replay frame and calibration
|
||||
When the frame is ingested
|
||||
Then a frame packet includes timestamp, calibration ID, quality report, occlusion report, and normalization hint.
|
||||
|
||||
**AC-2: Blackout bypass signal emitted**
|
||||
Given an unreadable, covered, or total-occlusion frame
|
||||
When quality classification runs
|
||||
Then the frame is marked unusable for VIO and anchor matching.
|
||||
|
||||
**AC-3: Raw frames are not retained**
|
||||
Given normal runtime operation
|
||||
When a frame is processed
|
||||
Then only allowed metadata/references are retained outside explicit fixture/test paths.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
**Performance**
|
||||
- Frame preprocessing must fit within the system p95 latency budget.
|
||||
|
||||
**Reliability**
|
||||
- Missing calibration blocks production readiness.
|
||||
|
||||
## Unit Tests
|
||||
|
||||
| AC Ref | What to Test | Required Outcome |
|
||||
|--------|--------------|------------------|
|
||||
| AC-1 | Valid frame with calibration | Frame packet contains required metadata |
|
||||
| AC-2 | Total occlusion input | `usable_for_vio=false` and `usable_for_anchor=false` |
|
||||
| AC-3 | Processed frame cleanup | No raw-frame persistence |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|
||||
|--------|-------------------------|--------------|-------------------|----------------|
|
||||
| AC-1 | Derkachi replay fixture | Frame/telemetry alignment | Accepted frame packets are timestamped | Performance |
|
||||
| AC-2 | Blackout fixture | Occlusion handling | Visual path degrades safely | Reliability |
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not rotate every frame in ingest; emit normalization hints for downstream use.
|
||||
- ADTi hardware assumptions remain blocked until exact specs are verified.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
**Risk 1: False-negative occlusion**
|
||||
- *Risk*: Bad frames enter VIO or matching.
|
||||
- *Mitigation*: Conservative occlusion gate and explicit quality flags.
|
||||
@@ -1,84 +0,0 @@
|
||||
# MAVLink GCS Gateway
|
||||
|
||||
**Task**: AZ-224_mavlink_gcs_gateway
|
||||
**Name**: MAVLink GCS Gateway
|
||||
**Description**: Subscribe to FC telemetry, emit `GPS_INPUT`, and publish QGC-visible status/failsafe messages.
|
||||
**Complexity**: 3 points
|
||||
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry
|
||||
**Component**: MAVLink And GCS Integration
|
||||
**Tracker**: AZ-224
|
||||
**Epic**: AZ-210
|
||||
|
||||
## Problem
|
||||
|
||||
The runtime needs a strict protocol boundary for ArduPilot Plane telemetry in and GPS-denied estimates/status out.
|
||||
|
||||
## Outcome
|
||||
|
||||
- FC telemetry is normalized into shared samples.
|
||||
- `GPS_INPUT` is emitted only from validated position estimates.
|
||||
- QGC status is rate-limited and safety-relevant.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Telemetry subscription behavior.
|
||||
- `GPS_INPUT` field validation and emission result.
|
||||
- QGC status/failsafe message emission.
|
||||
|
||||
### Excluded
|
||||
- Safety policy and covariance calculation.
|
||||
- SITL test runner implementation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Document Dependencies
|
||||
- `_docs/02_document/contracts/shared/runtime_contracts.md`
|
||||
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
**AC-1: Telemetry sample emitted**
|
||||
Given a valid FC telemetry stream
|
||||
When the gateway subscribes
|
||||
Then normalized telemetry samples are available to consumers.
|
||||
|
||||
**AC-2: Invalid GPS_INPUT is rejected**
|
||||
Given a malformed or unsafe position estimate
|
||||
When emission is requested
|
||||
Then no invalid `GPS_INPUT` packet is emitted.
|
||||
|
||||
**AC-3: Operator status is rate-limited**
|
||||
Given repeated mode changes or warnings
|
||||
When status is emitted
|
||||
Then QGC-visible messages stay within the configured rate.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
**Reliability**
|
||||
- Connection loss is surfaced to wrapper/FDR.
|
||||
|
||||
## Unit Tests
|
||||
|
||||
| AC Ref | What to Test | Required Outcome |
|
||||
|--------|--------------|------------------|
|
||||
| AC-1 | Telemetry normalization | Shared sample emitted |
|
||||
| AC-2 | Invalid fix type/accuracy | Emission rejected |
|
||||
| AC-3 | Status burst | Rate limit enforced |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|
||||
|--------|-------------------------|--------------|-------------------|----------------|
|
||||
| AC-2 | Plane SITL | `GPS_INPUT` output | Fields match ArduPilot expectations | Reliability |
|
||||
|
||||
## Constraints
|
||||
|
||||
- v1 emits `GPS_INPUT` only.
|
||||
- Do not hide MAVLink disconnects or invalid output errors.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
**Risk 1: ArduPilot parameter mismatch**
|
||||
- *Risk*: Plane ignores or mishandles emitted estimates.
|
||||
- *Mitigation*: SITL validation remains a release gate.
|
||||
@@ -1,89 +0,0 @@
|
||||
# Tile Manager Cache Manifest
|
||||
|
||||
**Task**: AZ-225_tile_manager_cache_manifest
|
||||
**Name**: Tile Manager Cache Manifest
|
||||
**Description**: Validate local cache manifests, signed sidecars, tile freshness, and spatial/descriptor metadata access.
|
||||
**Complexity**: 5 points
|
||||
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry
|
||||
**Component**: Tile Manager
|
||||
**Tracker**: AZ-225
|
||||
**Epic**: AZ-211
|
||||
|
||||
## Problem
|
||||
|
||||
The runtime must trust only preloaded offline cache tiles with valid signatures, hashes, freshness, resolution, and spatial metadata.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Mission cache validation blocks invalid cache usage.
|
||||
- Tile windows and descriptor metadata are queryable through local PostGIS-backed metadata.
|
||||
- Stale or tampered tiles cannot become trusted anchor inputs.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Cache package validation.
|
||||
- Signed sidecar/hash/freshness checks.
|
||||
- Tile window and descriptor metadata lookup.
|
||||
- Cache validation report events.
|
||||
|
||||
### Excluded
|
||||
- Satellite Service package transfer.
|
||||
- Generated tile orthorectification/write-back.
|
||||
|
||||
## 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: Valid cache activates**
|
||||
Given a cache package with valid manifests, sidecars, hashes, freshness, and spatial coverage
|
||||
When cache validation runs
|
||||
Then the cache becomes available to retrieval and anchor paths.
|
||||
|
||||
**AC-2: Invalid cache is rejected**
|
||||
Given a stale, unsigned, or hash-mismatched tile
|
||||
When validation runs
|
||||
Then the tile is rejected and an auditable reason is recorded.
|
||||
|
||||
**AC-3: Tile metadata is queryable**
|
||||
Given a candidate footprint or chunk ID
|
||||
When a consumer requests tile metadata
|
||||
Then the Tile Manager returns a valid local record or explicit rejection.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
**Performance**
|
||||
- Indexed tile lookups meet relocalization-path latency needs.
|
||||
|
||||
**Reliability**
|
||||
- Local PostgreSQL/PostGIS unavailability blocks mission cache activation.
|
||||
|
||||
## Unit Tests
|
||||
|
||||
| AC Ref | What to Test | Required Outcome |
|
||||
|--------|--------------|------------------|
|
||||
| AC-1 | Valid fixture | Cache available |
|
||||
| AC-2 | Tampered sidecar | Tile rejected |
|
||||
| AC-3 | Chunk metadata lookup | Correct record or explicit error |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|
||||
|--------|-------------------------|--------------|-------------------|----------------|
|
||||
| AC-2 | Stale/unsigned fixtures | Cache security gate | No invalid tile reaches retrieval | Reliability |
|
||||
|
||||
## Constraints
|
||||
|
||||
- Runtime never fetches satellite data mid-flight.
|
||||
- Large imagery/descriptors stay as files, not DB blobs.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
**Risk 1: Cache poisoning**
|
||||
- *Risk*: Bad cache entries influence anchor decisions.
|
||||
- *Mitigation*: Signature, hash, freshness, and provenance gates are mandatory.
|
||||
@@ -1,88 +0,0 @@
|
||||
# FDR Event Recorder And Export Surface
|
||||
|
||||
**Task**: AZ-227_fdr_event_recorder
|
||||
**Name**: FDR Event Recorder And Export Surface
|
||||
**Description**: Record bounded replayable mission evidence and expose exportable post-flight summaries.
|
||||
**Complexity**: 5 points
|
||||
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry
|
||||
**Component**: FDR And Observability
|
||||
**Tracker**: AZ-227
|
||||
**Epic**: AZ-212
|
||||
|
||||
## Problem
|
||||
|
||||
The system needs compact, bounded, queryable evidence for estimates, inputs, health, anchors, tile writes, and safety transitions.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Runtime components can append structured FDR events.
|
||||
- Storage rollover and health behavior are explicit.
|
||||
- Post-flight exports are available for analysis and release evidence.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Append event behavior.
|
||||
- PostgreSQL event index and CBOR segment payload contract.
|
||||
- Rollover and storage-full handling.
|
||||
- Export request/result behavior.
|
||||
|
||||
### Excluded
|
||||
- Component-specific event payload generation.
|
||||
- E2E report collation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Document Dependencies
|
||||
- `_docs/02_document/contracts/shared/runtime_contracts.md`
|
||||
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
**AC-1: Events are appendable**
|
||||
Given a valid FDR event
|
||||
When a component appends it
|
||||
Then metadata is indexed and payload is stored within bounds.
|
||||
|
||||
**AC-2: Storage pressure is handled**
|
||||
Given segment or storage limits are reached
|
||||
When append continues
|
||||
Then rollover or critical status behavior is explicit.
|
||||
|
||||
**AC-3: Export produces evidence**
|
||||
Given a completed run
|
||||
When export is requested
|
||||
Then queryable evidence and optional analytics artifacts are produced.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
**Performance**
|
||||
- FDR appends must not block hot-path localization.
|
||||
|
||||
**Reliability**
|
||||
- Append failures are surfaced to callers and health state.
|
||||
|
||||
## Unit Tests
|
||||
|
||||
| AC Ref | What to Test | Required Outcome |
|
||||
|--------|--------------|------------------|
|
||||
| AC-1 | Valid event append | Indexed metadata and payload reference |
|
||||
| AC-2 | Rollover threshold | Rollover event recorded |
|
||||
| AC-3 | Export request | Evidence artifact produced |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|
||||
|--------|-------------------------|--------------|-------------------|----------------|
|
||||
| AC-2 | 8-hour synthetic load | FDR cap and rollover | <=64 GB or explicit rollover evidence | Performance |
|
||||
|
||||
## Constraints
|
||||
|
||||
- Raw frames are not retained by default.
|
||||
- Secrets are not logged in FDR payloads.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
**Risk 1: FDR affects latency**
|
||||
- *Risk*: Append pressure slows localization.
|
||||
- *Mitigation*: Bounded segments and async-friendly append semantics.
|
||||
Reference in New Issue
Block a user