mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 15:01:13 +00:00
[AZ-842] Batch 04 cycle 4: AZ-835 docs + cycle-4 redesign narrative
Closes AZ-835 Epic C6 (docs) and folds the cycle-4 replay-input redesign narrative (AZ-894 CSV adapter / AZ-895 auto-sync deprecation / AZ-896 format spec / AZ-897 UI follow-up) into the three authoritative documents. Modified: - _docs/02_document/contracts/replay/replay_protocol.md: extend Invariant 12 with sub-invariants 12.c (route-driven supersedes bbox; ~100x tile efficiency + did-fly-vs-might-fly honesty) and 12.d (fixture failure-handling: validation/terminal re-raise; transient -> C11 backoff x3). Add Invariant 14 with sub- invariants 14.a-14.d covering the single canonical clock model, the CSV-driven path, the tlog adapter's audit-only role, the auto-sync deprecation, and the AZ-897 UI follow-up pointer. - _docs/02_document/architecture.md: add the AZ-777 Phase 3+ superseded-by-Epic-AZ-835 supersession block + new "Replay input redesign (cycle 4)" sub-section with the cycle-4 ticket table. - tests/e2e/replay/README.md: top section restructured for two distinct entry points (AZ-265/AZ-404 vs. AZ-835/AZ-840); add full AZ-835 orchestrator-test section (env vars, skip gates, expected runtime, verdict report path); add Imagery (c) Google attribution + dev-only caveat; add Epic AZ-835 ticket map. Spec deviation: AC-1b says "new Invariant 13" but Invariant 13 is already taken (C4<->C5 pairing, AZ-776 / ADR-012), and is referenced by number in architecture.md, c4_pose description.md, and ADR-012 prose. Cycle-4 content shipped as Invariant 14 to preserve those cross-references; renumbering would have cascaded to 3 files outside AZ-842's ownership envelope. Documented in batch report. Out-of-scope hygiene gap (NOT fixed in this batch): BUILD_CSV_REPLAY_ADAPTER flag is not yet enumerated in _docs/02_document/module-layout.md's Build-Time Exclusion Map. Inherited from cycle-4 AZ-894. Suggested as a cycle-5+ hygiene PBI. AZ-835 epic file stays in todo/ until AZ-841 (backlog) is resolved. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -279,8 +279,25 @@ Two consequences for the architecture:
|
||||
|
||||
**Imagery source license attribution (cycle 3)**: the Jetson `satellite-provider` instance downloads from the **Google Maps satellite layer** (`lyrs=s`), governed by Google Maps Platform Terms of Service. Dev/research use only; production deployment requires either a Google Maps Platform licensing review or migration to a true CC-BY satellite source on the parent-suite side (parent-suite ticket TBD). Operator-side seed scripts (`tests/fixtures/derkachi_c6/seed_region.py`, `seed_route.py`) propagate the "Imagery © Google" attribution.
|
||||
|
||||
**AZ-777 Phase 3+ superseded by Epic AZ-835**: AZ-777 originally proposed five phases — wire e2e-runner (Phase 1), seed Derkachi bbox (Phase 2), rewrite `operator_pre_flight_setup` fixture (Phase 3), un-xfail AC-4 / AC-5 (Phase 4), docs (Phase 5). Phases 1+2 shipped under AZ-777 itself (batch 104, cycle 3). Phases 3 and 5 were **superseded** when the user redirected the work to a route-driven flow: Phase 3 → AZ-839 (real fixture wiring C1+C2+C11+C10), Phase 5 → AZ-842 (this docs ticket). Phase 4 (un-xfail) was deferred to backlog after the cycle-4 redesign (AZ-895) took the un-xfail target along a different path and is not on the active epic. The AZ-777 task spec at `_docs/02_tasks/done/AZ-777_derkachi_c6_reference_fixture.md` carries the supersedure banner; this architecture document is the authoritative high-level pointer for that decision.
|
||||
|
||||
No new ADR — this is execution of existing decisions (architectural principle #5 satellite-provider on-disk layout end-to-end; ADR-004 process-level isolation unchanged; ADR-011 replay is a configuration unchanged). The architectural surface gained the route-driven seeding path inside C11; nothing else moved.
|
||||
|
||||
### Replay input redesign (cycle 4 — single canonical clock + CSV-driven path)
|
||||
|
||||
Cycle 4 rebuilt the replay-mode operator-input surface around a single canonical clock to close the AZ-848 ESKF out-of-order regression and to retire the tlog auto-sync surface that produced the misalignment risk in the first place. Four tickets ship the change:
|
||||
|
||||
| Ticket | Role | Description |
|
||||
|--------|------|-------------|
|
||||
| **AZ-894** (CSV adapter) | New primary path | `csv_replay_input.CsvReplayInputAdapter` consumes a paired `(video, CSV)` where the CSV's `Time` column is the canonical clock for every IMU/GPS sample. Gated `BUILD_CSV_REPLAY_ADAPTER=ON` in airborne and research binaries; OFF in operator-orchestrator. |
|
||||
| **AZ-895** (auto-sync deprecation) | Removed legacy | `replay_input.auto_sync` (AZ-405) reduced to a no-op stub that raises on first call; `tlog_video_adapter.py` reduced to a deprecated stub whose `open()` raises immediately. The legacy `--time-offset-ms` / `--skip-auto-sync` / `--auto-trim` CLI flags accepted-with-warning, ignored. Hard removal tracked in AZ-908 (cycle 5+ backlog). |
|
||||
| **AZ-896** (CSV format spec) | Contract | `_docs/02_document/contracts/replay/csv_replay_format.md` documents the CSV row schema, the row-0-alignment-with-video-frame-0 invariant, and an example `data_imu.csv` shipped under the same path. |
|
||||
| **AZ-897** (operator UI) | Cycle-5+ follow-up | First operator-facing UI surface — a React + Tailwind single-page form that uploads a paired `(video, CSV)`, links to AZ-896's format docs + example CSV, and tails the verdict from the headless `gps-denied-replay` invocation. Not on cycle-4 critical path; flagged here so the CSV format stays UI-friendly. |
|
||||
|
||||
The architectural rationale is captured in **Invariant 14** of the replay protocol (`_docs/02_document/contracts/replay/replay_protocol.md`): the system runs as a single edge process on a single device; there must be exactly one wall/monotonic clock authoritative for timestamps that cross component boundaries. In live mode that clock is the C8 inbound `FcAdapter`'s FC-boot-relative timestamp; in replay mode (after cycle 4) it is the CSV row's `Time` column. The previous design's two-clock surface (Jetson monotonic at C1 VIO emission, FC-boot at C8 IMU window arrival) produced the AZ-848 regression and is retired with the auto-sync deprecation.
|
||||
|
||||
The legacy `TlogReplayFcAdapter` is retained for two audit-only paths — offline FDR analysis from `tools/` and a one-shot `gps-denied-tlog-to-csv` migration utility that exports legacy tlog inputs to the canonical CSV. Neither path runs from the airborne composition root after cycle 4.
|
||||
|
||||
### `satellite-provider` upload contract (per D-PROJ-2 carryforward)
|
||||
|
||||
The onboard side of D-PROJ-2 is fully specified in `_docs/_process_leftovers/2026-05-09_satellite-provider-design-tasks.md`. From this architecture's standpoint:
|
||||
|
||||
Reference in New Issue
Block a user