mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 15:11:12 +00:00
[AZ-329] [AZ-330] [AZ-523] [AZ-524] Doc sweep: arch + glossary for Batch 44
Propagate Batch 44 SRP refactor (C11 internal flight-state gate moved to C12; PostLandingUploadOrchestrator gates on flight_footer.clean_shutdown; OperatorReLocService dispatches AC-3.4 hints via OperatorCommandTransport) into the suite-wide architecture documents that the per-component sweep in Phase F did not yet cover. Files updated: - architecture.md: C11/C12 component entries, principle #4 phrasing, Data Model table (FlightStateSignal annotation + new FlightFooterRecord / PostLandingUploadRequest / ReLocHint rows), post-landing + reloc data-flow summaries, ADR-004 "Why the gate moved to C12" rationale, deployment + security wording. - glossary.md: Tile Manager entry — gate-removal note. - data_model.md: FlightStateSignal row clarified; new rows for Batch 44 DTOs. - system-flows.md: F10 row, dependencies, full F10 prose + preconditions + mermaid + error table reworked around the footer-based gate. - epics.md: E-C11 scope/interface/AC/child-issue table (gate stripped, AZ-317 superseded); E-C12 scope/interface/AC/child- issue table expanded with PostLandingUploadOrchestrator, OperatorReLocService, FdrFooterReader, OperatorCommandTransport. - FINAL_report.md: component table rows 12 + 13. - components/10_c8_fc_adapter/description.md: removed stale claim that C11 TileUploader consumes FlightStateSignal. - contracts/c6_tile_cache/tile_metadata_store.md: minor C12 naming fix. Tests: 1543 passed / 80 skipped — doc-only sweep, no regressions. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -18,7 +18,7 @@
|
||||
| F7 | Spoofing-promotion via EKF source-set switch | FC reports GPS denial/spoof while companion estimate is healthy | C5, C8, [[ArduPilot Plane FC]] | High |
|
||||
| F8 | Companion reboot recovery | Companion process restart while FC remains armed | C8 (FC IMU pose ingest), C5, C10 (warm-cache verify), C13 | Medium |
|
||||
| F9 | GCS telemetry stream | Per-frame estimate available + GCS link healthy | C5, C8, [[QGroundControl]] | Medium |
|
||||
| F10 | Post-landing tile upload | Operator triggers C11 `TileUploader` with `flight_state == ON_GROUND` confirmed | C11 `TileUploader` (operator-side), C6 (read), [[`satellite-provider`]] (D-PROJ-2 endpoint, planned) | High |
|
||||
| F10 | Post-landing tile upload | Operator triggers C12 `PostLandingUploadOrchestrator`; orchestrator confirms `flight_footer.clean_shutdown == True` and invokes C11 `TileUploader` | C12 `PostLandingUploadOrchestrator` (operator-side; reads FDR footer), C11 `TileUploader` (operator-side), C6 (read), [[`satellite-provider`]] (D-PROJ-2 endpoint, planned) | High |
|
||||
|
||||
## Flow Dependencies
|
||||
|
||||
@@ -33,7 +33,7 @@
|
||||
| F7 | F3 (companion estimate health), F8 IMU prior | F3 (becomes primary FC source after switch) |
|
||||
| F8 | F1 + F2 (warm cache survives reboot via content-hash verify) | F3 (resumes once warm), F5 (degraded mode if recovery fails) |
|
||||
| F9 | F3 | n/a (read-only outbound) |
|
||||
| F10 | F4 (locally-saved tiles), F8 confirmed `flight_state == ON_GROUND`, parent-suite D-PROJ-2 endpoint availability | F1 of the next flight (uploaded tiles enter the basemap once promoted to `trusted`) |
|
||||
| F10 | F4 (locally-saved tiles), C13 `flight_footer` written on clean shutdown, parent-suite D-PROJ-2 endpoint availability | F1 of the next flight (uploaded tiles enter the basemap once promoted to `trusted`) |
|
||||
|
||||
**Cross-cutting**: F13 FDR-write is not a flow per se — every flow above has an FDR write side-effect. AC-NEW-3 requires every payload class (estimate, IMU, MAVLink, mid-flight tile, system health, failed-tile thumbnail) to be present; rollover is logged, never silent.
|
||||
|
||||
@@ -965,11 +965,11 @@ sequenceDiagram
|
||||
|
||||
### Description
|
||||
|
||||
After the UAV has landed and `flight_state == ON_GROUND` is confirmed, the operator triggers the C11 Tile Manager's `TileUploader` (a separate operator-side process / image — **not present in the airborne companion image**, ADR-004) which reads locally-saved mid-flight tiles from C6 and uploads them to `satellite-provider`'s ingest endpoint per the D-PROJ-2 contract sketch. Each tile carries quality metadata sufficient for the parent-suite voting layer to decide promotion `pending → trusted` (D-PROJ-2 design task #2; not yet implemented service-side). Until the real endpoint ships, integration tests target the e2e-test `mock-suite-sat-service` fixture under `tests/fixtures/`; production never reaches the fixture.
|
||||
After the UAV has landed, the operator triggers C12's `PostLandingUploadOrchestrator` (`operator-orchestrator upload-pending --flight-id ...`). The orchestrator reads the `flight_footer` FDR record for the given `flight_id` via `FdrFooterReader`; if the footer is present AND `clean_shutdown == True`, it invokes C11's `TileUploader` (via the `TileUploaderCut` Protocol) which reads locally-saved mid-flight tiles from C6 and uploads them to `satellite-provider`'s ingest endpoint per the D-PROJ-2 contract sketch. The C11 Tile Manager is a separate operator-side process / image — **not present in the airborne companion image**, ADR-004. Each tile carries quality metadata sufficient for the parent-suite voting layer to decide promotion `pending → trusted` (D-PROJ-2 design task #2; not yet implemented service-side). Until the real endpoint ships, integration tests target the e2e-test `mock-suite-sat-service` fixture under `tests/fixtures/`; production never reaches the fixture.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- `flight_state == ON_GROUND` confirmed by the FC's `MAV_STATE` (operator's workstation reads this off the FC or from the FDR).
|
||||
- C13 has written the `flight_footer` FDR record for the requested `flight_id` with `clean_shutdown == True`. This is the single safety invariant; the operator does not query FC `MAV_STATE` directly (Batch 44 SRP refactor — the footer is the authoritative "vehicle stopped cleanly" signal).
|
||||
- Operator workstation has network reach to `satellite-provider` (in tests, the e2e `mock-suite-sat-service` fixture stands in for the not-yet-shipped POST endpoint).
|
||||
- Local C6 tile store has mid-flight tiles with `voting_status=pending` and quality metadata.
|
||||
- Per-flight onboard signing key (generated at takeoff load, baked into tile metadata) is available to C11 `TileUploader` for payload signing.
|
||||
@@ -1001,9 +1001,10 @@ sequenceDiagram
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Operator triggers C11 TileUploader with flight_id]) --> StateCheck{flight_state == ON_GROUND confirmed?}
|
||||
StateCheck -->|no| Refuse[Refuse to upload; report to operator]
|
||||
StateCheck -->|yes| ReadTiles[Read mid-flight tiles voting_status=pending]
|
||||
Start([Operator triggers C12 PostLandingUploadOrchestrator with flight_id]) --> FooterRead[C12 FdrFooterReader reads flight_footer FDR record]
|
||||
FooterRead --> StateCheck{footer present AND clean_shutdown == True?}
|
||||
StateCheck -->|no — footer_missing / unclean_shutdown / flight_id_not_found / fdr_unreadable| Refuse[Raise FlightStateNotConfirmedError with sub-reason + operator-actionable remediation]
|
||||
StateCheck -->|yes| ReadTiles[C11 TileUploader reads mid-flight tiles voting_status=pending]
|
||||
ReadTiles --> Empty{Any tiles to upload?}
|
||||
Empty -->|no| Done([No-op; report])
|
||||
Empty -->|yes| Batch[Batch by configurable size]
|
||||
@@ -1038,7 +1039,7 @@ flowchart TD
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| `flight_state != ON_GROUND` | Step 1 | FC `MAV_STATE` query | Refuse upload; never proceed (architectural invariant) |
|
||||
| `flight_footer` missing OR `clean_shutdown == False` OR `flight_id` not found OR FDR unreadable | Step 1 (C12 `FdrFooterReader`) | Raises `FlightStateNotConfirmedError(reason=...)` with one of 4 sub-reasons (`footer_missing`, `unclean_shutdown`, `flight_id_not_found`, `fdr_unreadable: <repr>`) | Refuse upload; CLI exits with a distinct exit code per sub-reason; operator must fix the FDR or pick the right `flight_id` before retrying (architectural invariant — no auto-retry) |
|
||||
| `satellite-provider` ingest endpoint not yet implemented (D-PROJ-2 open) | Step 3 | 404 / 501 / connection refused | Keep batches queued locally; report to operator; retry on next operator trigger |
|
||||
| Network rate-limit (429) | Step 3 | HTTP 429 | Back off + retry |
|
||||
| Per-tile rejected by service | Step 4 | per-tile status `rejected` | Mark `voting_status=rejected_by_service`; FDR logs reason; do not retry that tile |
|
||||
|
||||
Reference in New Issue
Block a user