azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-22 16:21:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-329] [AZ-330] [AZ-523] [AZ-524] Doc sweep: arch + glossary for Batch 44

Browse Source 
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:
Oleksandr Bezdieniezhnykh
2026-05-13 21:28:59 +03:00
parent 9116e304fd
commit a92e5ee482
8 changed files with 72 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_document/epics.md
+39 -20
View File
@@ -857,9 +857,9 @@ Sole operator-side network I/O against `satellite-provider`, both directions. St
### Scope
**In scope**: `TileDownloader.fetch` (download → freshness gate → write to C6), `TileUploader.upload_pending` (read C6 pending → sign → POST → mark uploaded), per-flight ephemeral signing key, idempotent retry on partial-success batches, `flight_state == ON_GROUND` gate (defense-in-depth atop ADR-004).
**In scope**: `TileDownloader.fetch` (download → freshness gate → write to C6), `TileUploader.upload_pending` (read C6 pending → sign → POST → mark uploaded), per-flight ephemeral signing key, idempotent retry on partial-success batches.
**Out of scope**: any airborne code; cache artifact build (E-C10); orchestration (E-C12).
**Out of scope**: any airborne code; cache artifact build (E-C10); orchestration (E-C12 — including the post-landing safety gate, which moved to C12 in Batch 44).
### Architecture notes
@@ -874,8 +874,10 @@ class TileDownloader:
def fetch(req: FetchRequest) -> DownloadBatchReport: ...
class TileUploader:
def upload_pending(flight_state: FlightStateSignal) -> UploadBatchReport: ...
# raises UploadGateBlockedError if flight_state != ON_GROUND
def upload_pending(req: UploadRequest) -> UploadBatchReport: ...
# contract v2.0.0 (frozen) — C11 no longer gates on flight state;
# the post-landing safety check lives in C12's PostLandingUploadOrchestrator
# (reads flight_footer.clean_shutdown from FDR) per Batch 44 SRP refactor.
```
### Data flow
@@ -903,7 +905,7 @@ sequenceDiagram
- C11-IT-01: TileDownloader fetch + freshness gate + C6 write byte-identical layout.
- C11-IT-02: stale-rejection counts surface in `DownloadBatchReport`.
- C11-IT-03: TileUploader posts pending, signs payloads, marks uploaded on 202.
- C11-IT-04: `UploadGateBlockedError` when not ON_GROUND.
- C11-IT-04: post-landing safety gate is now a C12 concern — see `_docs/02_document/components/13_c12_operator_orchestrator/tests.md` C12-IT-03 (Batch 44 SRP refactor; AZ-317 superseded).
- C11-IT-05: idempotent retry — already-acked tiles not re-sent.
- C11-ST-01: airborne process cannot import `c11_tilemanager` (R02 enforcement).
- C11-ST-02: NFT-SEC-02 network-egress test passes.
@@ -931,7 +933,7 @@ T-shirt M; 13–21 points.
| 1 | TileDownloader: GET + freshness gate + C6 write | 5 |
| 2 | TileUploader: read pending + sign + POST + mark uploaded | 5 |
| 3 | Idempotent retry on partial-success batch | 3 |
| 4 | `flight_state == ON_GROUND` gate (defense-in-depth) | 2 |
| 4 | ~~`flight_state == ON_GROUND` gate~~ — moved to C12 `PostLandingUploadOrchestrator` (Batch 44 SRP refactor; AZ-317 superseded) | n/a |
| 5 | Per-flight ephemeral signing key + zeroisation | 3 |
| 6 | Component-internal tests C11-IT-01..05 + C11-PT-01..02 + C11-ST-01..03 + C11-AT-01 | 5 |
@@ -1069,9 +1071,9 @@ Operator-facing CLI that sequences pre-flight (C11 download → C10 build) and p
### Scope
**In scope**: CLI subcommands (`download`, `build-cache`, `upload-pending`, `reloc-confirm`), `CacheBuildReport` aggregation, post-landing `flight_state == ON_GROUND` confirmation from FDR, sector-classification UI hook, FDR retrieval helpers.
**In scope**: CLI subcommands (`download`, `build-cache`, `upload-pending`, `reloc-confirm`), `CacheBuildReport` aggregation, `PostLandingUploadOrchestrator` (post-landing safety gate reading `flight_footer.clean_shutdown` from FDR via `FdrFooterReader` — Batch 44 SRP refactor; supersedes the former C11-internal gate), `OperatorReLocService` (AC-3.4 visual-loss hint dispatched via `OperatorCommandTransport` Protocol — E-C8 ships the concrete pymavlink-backed impl), sector-classification UI hook, FDR retrieval helpers.
**Out of scope**: actual download/upload (E-C11); engine compile (E-C10); FDR write side (E-C13).
**Out of scope**: actual download/upload (E-C11; C11 no longer gates internally); engine compile (E-C10); FDR write side (E-C13); concrete `OperatorCommandTransport` (E-C8).
### Architecture notes
@@ -1081,10 +1083,26 @@ Operator-facing CLI that sequences pre-flight (C11 download → C10 build) and p
### Interface specification
```python
class OperatorTool:
def build_cache(area: Area, sector_classification: SectorMap) -> CacheBuildReport: ...
def trigger_post_landing_upload(fdr_root: Path) -> UploadBatchReport: ...
def confirm_relocation(candidate: ReLocCandidate) -> None: ...
class BuildCacheOrchestrator:
def build_cache(request: BuildCacheRequest) -> CacheBuildReport: ...
class PostLandingUploadOrchestrator:
def trigger_post_landing_upload(request: PostLandingUploadRequest) -> UploadBatchReportCut: ...
# raises FlightStateNotConfirmedError(reason) for {footer_missing,
# unclean_shutdown, flight_id_not_found, fdr_unreadable: <repr>}
# or SatelliteProviderError on C11 transport failures.
class OperatorReLocService:
def request_reloc(reloc_hint: ReLocHint) -> None: ...
# raises GcsLinkError with "C12 reloc-confirm: " prefix on link failure.
class FdrFooterReader(Protocol):
def read_flight_footer(flight_id: FlightId) -> FlightFooterRecord | None: ...
class OperatorCommandTransport(Protocol):
def send_reloc_hint(hint: ReLocHint) -> None: ...
# concrete impl owned by E-C8 (pymavlink-backed); pattern matches
# AZ-322 BackboneEmbedder (C10 owns Protocol; C2 implements later).
```
### Data flow
@@ -1109,9 +1127,9 @@ sequenceDiagram
### Acceptance criteria
- C12-IT-01: operator re-loc workflow returns SUT to `satellite_anchored` ≤ 30 s (AC-3.4).
- C12-IT-01: operator re-loc workflow (`OperatorReLocService.request_reloc`) returns SUT to `satellite_anchored` ≤ 30 s (AC-3.4); on `GcsLinkError`, CLI exits with `EXIT_GCS_LINK_ERROR` and operator-actionable remediation text.
- C12-IT-02: `build_cache` orchestrates C11 then C10; download failure aborts before C10.
- C12-IT-03: `trigger_post_landing_upload` requires ≥ 30 s confirmed ON_GROUND in FDR.
- C12-IT-03: `trigger_post_landing_upload` reads `flight_footer.clean_shutdown` from FDR via `FdrFooterReader` (Batch 44 footer-based gate; replaces the prior 30-s ON_GROUND heuristic). Refusal modes: `footer_missing`, `unclean_shutdown`, `flight_id_not_found`, `fdr_unreadable: <repr>` — each maps to a distinct CLI exit code.
- C12-IT-04: actionable failure messages + non-zero exit on stale-tile rate > 30% or manifest signature failure.
- C12-ST-01: no CLI command path imports into airborne package boundary.
@@ -1131,12 +1149,13 @@ T-shirt M; 13–21 points.
| # | Title | Pts |
|---|-------|-----|
| 1 | CLI scaffolding + subcommand routing | 3 |
| 2 | `build_cache` orchestration (C11 then C10) | 3 |
| 3 | `trigger_post_landing_upload` with FDR-state confirmation | 3 |
| 4 | AC-3.4 re-localization workflow | 3 |
| 5 | Actionable failure surfacing in CacheBuildReport | 2 |
| 6 | Component-internal tests C12-IT-01..04 + C12-PT-01 + C12-ST-01 + C12-AT-01 | 5 |
| 1 | CLI scaffolding + subcommand routing (AZ-326) | 3 |
| 2 | `BuildCacheOrchestrator` — C11 then C10 sequenced flow + lockfile (AZ-328) | 5 |
| 3 | `PostLandingUploadOrchestrator` + `FdrFooterReader` — Batch 44 footer-based gate (AZ-329) | 3 |
| 4 | `OperatorReLocService` + `OperatorCommandTransport` Protocol — AC-3.4 (AZ-330) | 3 |
| 5 | Companion bringup (SSH-based pre-flight verification) (AZ-327) | 3 |
| 6 | `FlightsApiClient` — operator-origin path (AZ-489) | 3 |
| 7 | Component-internal tests C12-IT-01..04 + C12-PT-01 + C12-ST-01 + C12-AT-01 | 5 |
### Key constraints