Update demo replay validation and testing documentation

- Modified the autodev state to reflect the current testing phase and details of the new `jetson-e2e` tests. - Enhanced the "How to Test" documentation to provide clearer instructions on the demo replay validation process, including video and tlog alignment steps. - Updated architectural documentation to include the new demo replay operator flow and its dependencies. - Documented the removal of deprecated auto-sync features and clarified the operator-facing UI for replay validation. - Added new entries in the dependencies table for upcoming tasks related to the demo replay flow. These changes improve clarity and usability for operators and developers working with the demo replay system.
2026-06-22 07:01:13 +00:00 · 2026-06-20 11:24:43 +03:00
parent 12d0008763
commit 1f634c2604
175 changed files with 20701 additions and 41 deletions
@@ -274,8 +274,8 @@ source repo

 Two consequences for the architecture:

-1. **C11 read contract adapted to the v1.0.0 inventory shape (AZ-777 Phase 1)** — `POST /api/satellite/tiles/inventory` + `GET /tiles/{z}/{x}/{y}` replace the historical `GET /api/satellite/tiles?bbox=…&zoom=…` shape. The bbox-driven `download_tiles_for_area` entry point and its DTOs are unchanged at the call-site level; the contract adaptation is internal to `HttpTileDownloader`. Auth is JWT Bearer (`SATELLITE_PROVIDER_API_KEY`) over TLS; `SATELLITE_PROVIDER_TLS_INSECURE=1` is a documented dev-only knob for self-signed certs.
-2. **Route-driven seeding (Epic AZ-835 — C11's third interface, `SatelliteProviderRouteClient`)** — the operator can now submit a tlog-derived `RouteSpec` (waypoints + region size; produced by `replay_input.tlog_route.extract_route_from_tlog` — AZ-836; canonical DTO at `_types/route.py` per AZ-845) via `POST /api/satellite/route` and have `satellite-provider` materialise just the corridor tiles, polling `GET /api/satellite/route/{id}` until `mapsReady=true`. This is ~100× more tile-efficient than the bbox path on long, narrow flights. Pre-emptive validation mirrors the AZ-809 `CreateRouteRequestValidator` bounds. The route-driven path is exercised today by the cycle-3 e2e fixture `operator_pre_flight_setup` (AZ-839) and the orchestrator test `test_az835_e2e_real_flight.py` (AZ-840); the C12 production CLI binding is a future-cycle integration.
+1. **C11 read contract adapted to the v1.0.0 inventory shape (AZ-777 Phase 1)** — `POST /api/satellite/tiles/inventory` + `GET /tiles/{z}/{x}/{y}` replace the historical `GET /api/satellite/tiles?bbox=…&zoom=…` shape. The bbox-driven `download_tiles_for_area` entry point and its DTOs are unchanged at the call-site level; the contract adaptation is internal to `HttpTileDownloader`. Auth is JWT Bearer (`SATELLITE_PROVIDER_API_KEY`) over TLS; `SATELLITE_PROVIDER_TLS_INSECURE=1` is a documented dev-only knob for self-signed certs. **Proposed successor (ADR-013 / AZ-976)**: gRPC `satellite.v1.RouteTileDelivery.DeliverRouteTiles` server-streaming with client tile catalog — see `tile_provision_grpc.md`; supersedes the never-shipped inventory REST endpoint.
+2. **Route-driven seeding (Epic AZ-835 / AZ-969)** — the operator submits a tlog-derived `RouteSpec` (produced by `replay_input.tlog_route.extract_route_from_tlog` — AZ-836) via C12 `seed-cache-from-tlog` (AZ-974) or the F11 `replay_api` demo job (AZ-973). E2E fixture `operator_pre_flight_setup` wraps the same production `operator_replay.cache_seed` module.

 **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.

@@ -292,11 +292,17 @@ Cycle 4 rebuilt the replay-mode operator-input surface around a single canonical
 | **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. |
+| **AZ-897** (operator UI) | Cycle 5 — Epic AZ-969 | Dual-timeline `(video, tlog)` alignment UI in `../ui`; uploads raw tlog, calls `replay_api` preview/align/demo endpoints; displays map + verdict. Spec: `../ui/_docs/02_tasks/todo/AZ-897_operator_replay_sync_ui.md`. |

 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.
+The legacy `TlogReplayFcAdapter` is retained for audit paths — offline FDR analysis and `gps-denied-tlog-to-csv` export (AZ-972). Runtime replay uses the CSV adapter after operator alignment (F11 / Epic AZ-969).
+
+### Demo replay operator flow (cycle 5 — Epic AZ-969)
+
+F11 in `system-flows.md` is the **primary product demo**, not an e2e-test concern. Raw operator inputs are `(video, tlog, calibration)`; alignment produces an AZ-896 CSV on a single canonical clock; route-driven cache seeding uses `extract_route_from_tlog` via C12 / `replay_api` production modules (AZ-974, AZ-973). Backend children: AZ-970 (preview API), AZ-971 (alignment refine), AZ-972 (CSV export), AZ-973 (orchestration), AZ-974 (C12 seed CLI), AZ-975 (docs). UI: AZ-897 in `../ui`.
+
+The cycle-4 `(video, CSV)` upload bypass (AZ-959) remains for operators who already have an aligned CSV; it is not the default demo entry.

 ### `satellite-provider` upload contract (per D-PROJ-2 carryforward)

@@ -781,4 +787,32 @@ When C5 ships a second strategy — `eskf` (ESKF baseline, AZ-588) — the subst
 - `_docs/02_document/contracts/replay/replay_protocol.md` gains a new "Open-loop ESKF composition profile" sub-section in **Composition root extension** plus a new **Invariant 13** ("C4↔C5 pairing matrix is enforced at compose time") that the AZ-776 unit tests own.
 - `_docs/02_document/components/06_c4_pose/description.md` gains an "Enabled flag" sub-section that points at this ADR; the rest of the component contract is unchanged.
 - The unit-test surface at `tests/unit/runtime_root/test_az776_open_loop_eskf_composition.py` owns the seven invariants AZ-776 introduces: `C4PoseConfig.enabled` default-true, AC-1 (open-loop ESKF composes without C4), AC-2 (default GTSAM profile still includes C4), AC-3a + AC-3b (the two forbidden pairings raise `CompositionError`), and the two `pre_constructed` behaviours (`c5_isam2_graph_handle` omitted when C4 disabled, present when C4 enabled). The full suite passes in ~4 s.
- The composition root's contract surface in `runtime_root/__init__.py` gains one public helper (`CompositionError` was already public; the new `skip_slugs` parameter to `_compose` is module-private). No public CLI flag is added — operators set `c4_pose.enabled = false` in YAML.
+- The composition root's contract surface in `runtime_root/__init__.py` gains one public helper (`CompositionError` was already public; the new `skip_slugs` parameter to `_compose` is module-private). No public CLI flag is added — operators set `c4_pose.enabled = false` in YAML.
+
+### ADR-013 — gRPC server-streaming tile provision for operator pre-flight (AZ-976)
+
+**Context**: Operator-side cache build (C11/C12 ↔ `satellite-provider`) is off the hot airborne path but dominates time-to-ready when a corridor has thousands of tiles. The current REST shape (`POST /route` + poll + planned `POST /inventory` + N× `GET /tiles/{z}/{x}/{y}`) multiplies round-trips and cannot overlap "tiles already on SP disk" with "tiles still downloading from Google Maps". The inventory POST was specified in AZ-777 but never shipped in satellite-provider; Jetson smoke tests 404 on it today. Both codebases are owned by the same team (.NET satellite-provider, Python gps-denied operator tooling), so a typed streaming contract is feasible without a browser client.
+
+**Decision**:
+
+1. **We will add `satellite.v1.RouteTileDelivery.DeliverRouteTiles`** — unary request (`RouteSpec` + `client_tiles`), server-streaming `RouteTileEvent` (manifest → batches → progress → complete | error) — as the primary operator-side pre-flight transport (Epic AZ-976). Proto: `tile_provision.proto`; human contract: `tile_provision_grpc.md`.
+2. **The request carries `RouteSpec.route_id` (idempotent UUID) plus `ClientTileRecord[]`.** satellite-provider omits tiles when the client catalog already has equal-or-better resolution and equal-or-newer `captured_at` (lower m/px = better).
+3. **First stream event is `RouteManifest`** (`total_candidates`, `skipped_by_client`, `to_deliver`); then `TileBatch` messages with inline JPEGs. Server sends on-disk hits before externally fetched tiles (wire-agnostic ordering; `TilePayload.route_priority` hints along-route order).
+4. **ADR-004 boundary is preserved**: only C11/C12 on the operator workstation import gRPC stubs.
+
+**Alternatives considered**:
+
+| Alternative | Rejected because |
+|-------------|------------------|
+| REST `POST /inventory` + parallel GET | Never implemented in satellite-provider; still N+1 HTTP; no overlap of cached vs in-flight fetch |
+| SSE over HTTPS | Weaker typing; both sides are service binaries, not browsers — gRPC + protobuf is the better fit |
+| ZeroMQ between products | Poor fit across WAN/NAT; better kept **inside** satellite-provider's fetch workers |
+| In-flight streaming to UAV | Violates RESTRICT-SAT-1 / ADR-004; wrong reliability model for the aircraft |
+
+**Consequences**:
+
+- Epic AZ-976 decomposes: AZ-977 (SP gRPC server), AZ-978 (C11 client + C12 wiring), AZ-979 (Jetson benchmark + flip default).
+- REST `route_client` + `HttpTileDownloader` remain as fallback until AZ-979 benchmark promotes gRPC.
+- Finished C6 is still staged onto the Jetson via USB/rsync before flight — this ADR optimizes operator wait time, not in-air link dependency.
+
+**Evidence**: `_docs/02_document/contracts/c11_tilemanager/tile_provision.proto`, `tile_provision_grpc.md`, `_docs/02_tasks/todo/AZ-976_grpc_tile_provision_epic.md`.
@@ -0,0 +1,95 @@
+syntax = "proto3";
+
+package satellite.v1;
+
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Satellite.V1";
+
+service RouteTileDelivery {
+  rpc DeliverRouteTiles(DeliverRouteTilesRequest) returns (stream RouteTileEvent);
+}
+
+message DeliverRouteTilesRequest {
+  RouteSpec route = 1;
+  repeated ClientTileRecord client_tiles = 2;
+}
+
+message RouteSpec {
+  string route_id = 1;
+  repeated Waypoint waypoints = 2;
+  double region_size_meters = 3;
+  int32 zoom = 4;
+  repeated GeofencePolygon geofences = 5;
+  bool include_geofence_tiles = 6;
+}
+
+message Waypoint {
+  double lat = 1;
+  double lon = 2;
+}
+
+message GeofencePolygon {
+  repeated Waypoint vertices = 1;
+}
+
+message ClientTileRecord {
+  int32 z = 1;
+  int32 x = 2;
+  int32 y = 3;
+  double resolution_m_per_px = 4;
+  google.protobuf.Timestamp captured_at = 5;
+  optional string source = 6;
+  bytes content_sha256 = 7;
+}
+
+message RouteTileEvent {
+  oneof payload {
+    RouteManifest manifest = 1;
+    TileBatch batch = 2;
+    ProgressUpdate progress = 3;
+    DeliveryComplete complete = 4;
+    DeliveryError error = 5;
+  }
+}
+
+message RouteManifest {
+  uint32 total_candidates = 1;
+  uint32 skipped_by_client = 2;
+  uint32 to_deliver = 3;
+}
+
+message TileBatch {
+  uint32 batch_seq = 1;
+  repeated TilePayload tiles = 2;
+}
+
+message TilePayload {
+  int32 z = 1;
+  int32 x = 2;
+  int32 y = 3;
+  double resolution_m_per_px = 4;
+  google.protobuf.Timestamp captured_at = 5;
+  string source = 6;
+  bytes jpeg = 7;
+  bytes content_sha256 = 8;
+  uint32 route_priority = 9;
+}
+
+message ProgressUpdate {
+  uint32 delivered = 1;
+  uint32 total = 2;
+  uint32 downloading = 3;
+}
+
+message DeliveryComplete {
+  uint32 delivered = 1;
+  uint32 skipped_client = 2;
+  uint32 skipped_server_filter = 3;
+}
+
+message DeliveryError {
+  string code = 1;
+  string message = 2;
+  bool retryable = 3;
+}
@@ -0,0 +1,143 @@
+# Contract: RouteTileDelivery (gRPC)
+
+**Component**: c11_tilemanager (consumer), satellite-provider (producer)
+**Epic**: AZ-976
+**ADR**: ADR-013 (architecture.md)
+**Proto**: `tile_provision.proto` — `package satellite.v1`
+**Version**: 0.3.0
+**Status**: proposed
+**Last Updated**: 2026-06-19
+
+## Purpose
+
+Operator-side **pre-flight cache provisioning**. Client sends route + onboard tile catalog once; server streams `RouteTileEvent` messages until `DeliveryComplete` or `DeliveryError`.
+
+satellite-provider does **not** receive `flight_id` — that is a C6 bookkeeping concern on the gps-denied side only (`route_id` is the wire correlation id).
+
+C11/C12 on the **operator workstation** only. ADR-004: airborne image must not import stubs or open this channel.
+
+## RPC
+
+```protobuf
+service RouteTileDelivery {
+  rpc DeliverRouteTiles(DeliverRouteTilesRequest) returns (stream RouteTileEvent);
+}
+```
+
+| Concern | Rule |
+|---------|------|
+| Auth | gRPC metadata `authorization: Bearer <JWT>` |
+| TLS | Required in production; `SATELLITE_PROVIDER_TLS_INSECURE=1` dev knob |
+| Idempotency | `RouteSpec.route_id` (UUID string) |
+| Resume | Client persists last acked `batch_seq` per `route_id` locally (not on wire) |
+
+## Request
+
+### `DeliverRouteTilesRequest`
+
+| Field | Description |
+|-------|-------------|
+| `route` | Corridor geometry + single zoom |
+| `client_tiles` | Onboard inventory snapshot (route intersection only) |
+
+### `RouteSpec`
+
+| Field | Maps from gps-denied |
+|-------|----------------------|
+| `route_id` | Client-generated UUID per provision job |
+| `waypoints` | `replay_input.tlog_route.RouteSpec.waypoints` |
+| `region_size_meters` | `RouteSpec.suggested_region_size_meters` |
+| `zoom` | Single slippy zoom level (confirmed sufficient) |
+| `geofences` | Optional inclusion polygons |
+| `include_geofence_tiles` | Union geofence tiles with corridor grid |
+
+### `ClientTileRecord`
+
+Canonical key: **`(z, x, y)`**. `source` is informational only — **not** used in skip logic.
+
+| Field | C6 mapping |
+|-------|------------|
+| `resolution_m_per_px` | RESTRICT-SAT-4 (lower = better) |
+| `captured_at` | `TileMetadata.capture_timestamp` |
+| `content_sha256` | `TileMetadata.content_sha256_hex` (raw 32 bytes) |
+
+## Server skip rule (client catalog)
+
+For each server candidate tile, **omit from stream** when `client_tiles` has matching `(z,x,y)` and **any** of:
+
+1. `client.content_sha256` is non-empty and **equals** server payload hash → skip (byte-identical)
+2. `client.resolution_m_per_px <= server.resolution_m_per_px` **and** `client.captured_at >= server.captured_at` → skip (metadata-sufficient)
+
+`source` is **not** compared.
+
+`RouteManifest.skipped_by_client` counts tiles removed by this rule.
+
+## Sector — not on this wire
+
+**Sector** (`active_conflict` vs `stable_rear`) controls **how stale a tile may be before C6 rejects it on write** (AC-NEW-6 freshness). It is an operator decision about the geographic area, not something satellite-provider needs to deliver tiles.
+
+| Layer | Who applies sector |
+|-------|-------------------|
+| satellite-provider | Does not need sector — streams tiles by route geometry |
+| C11 client write | Reads sector from **C11/C12 config** (same as today) when calling C6 freshness gate |
+
+No `SectorClass` field on the gRPC request.
+
+## Response stream: `RouteTileEvent`
+
+Typical sequence:
+
+1. **`RouteManifest`** — `total_candidates`, `skipped_by_client`, `to_deliver`
+2. **`TileBatch`** — monotonic `batch_seq`; on-disk hits first, then freshly fetched
+3. **`ProgressUpdate`** — optional
+4. **`DeliveryComplete`** or **`DeliveryError`**
+
+### `DeliveryComplete` counters
+
+| Field | Meaning |
+|-------|---------|
+| `delivered` | Tiles actually sent in `TileBatch` streams |
+| `skipped_client` | Same as manifest `skipped_by_client` (echo for client verify) |
+| `skipped_server_filter` | Tiles SP required but **did not send** after client dedup — see below |
+
+#### `skipped_server_filter` — what counts
+
+Tiles that entered the post-client-dedup work queue but never appeared in a batch:
+
+| Reason | Example |
+|--------|---------|
+| **Fetch failed** | External imagery provider 404/timeout after retries |
+| **Below SP min resolution** | SP refuses to store/serve below its configured floor |
+| **Geometry clip** | Tile dropped after server-side corridor/geofence validation |
+| **Operational cap** | Job hit max-tiles / rate limit (if SP enforces) |
+
+Tiles skipped by the **client catalog rule** are **not** included here (they are `skipped_client`).
+
+If SP has no server-side filters in v1, `skipped_server_filter` may be **0**; the field is reserved for observability.
+
+### `TilePayload`
+
+| Field | Notes |
+|-------|-------|
+| `content_sha256` | 32-byte SHA-256 of `jpeg`; matches C6 DB invariant |
+| `route_priority` | Lower = earlier along route |
+
+## Client write path (gps-denied)
+
+`RouteTileDeliveryClient` (C11):
+
+- Assigns C6 `flight_id` from operator context locally (not from SP)
+- Applies RESTRICT-SAT-4, **sector-based freshness**, AZ-308 budget, download journal
+- Resumes via persisted `route_id` + `batch_seq`
+
+## Migration
+
+REST `route_client` + `HttpTileDownloader` remain fallback until AZ-979 benchmark.
+
+## Change log
+
+| Version | Date | Change |
+|---------|------|--------|
+| 0.3.0 | 2026-06-19 | `ClientTileRecord.content_sha256`; sequential field nums on `TilePayload`; sector/flight_id off wire; skip rule + `skipped_server_filter` defined |
+| 0.2.0 | 2026-06-19 | `satellite.v1.RouteTileDelivery` + `RouteTileEvent` oneof |
+| 0.1.0 | 2026-06-19 | Initial draft (superseded) |
@@ -289,7 +289,9 @@ The two **invalid** cells (`true` + `eskf` and `false` + `gtsam_isam2`) raise `C

    **Sub-invariant 14.c (auto-sync deprecation — AZ-895)**: the `replay_input.auto_sync` module (AZ-405) is reduced to a deprecated no-op stub that raises `ReplayInputAdapterError("auto-sync removed; supply --imu CSV instead")` from every public entry point. The CLI flags `--time-offset-ms`, `--skip-auto-sync`, and `--auto-trim` are accepted with a deprecation warning and ignored. The justification: with a single canonical clock at the CSV row level (14.a), there is no second clock to align against — the operator authors the CSV with the correct row-0 alignment, and the fixture verifies row 0's `Time == 0`. Hard removal of the deprecated surface is tracked in AZ-908; this cycle ships only the stub + warnings to preserve source-compat for any downstream caller built against AZ-405's pre-deprecation shape.

-    **Sub-invariant 14.d (operator-facing UI — AZ-897, future cycle)**: the cycle-4 deliverable is the headless `gps-denied-replay --video X --imu Y` shape. An operator-facing web UI (single-page React + Tailwind form that uploads a paired `(video, CSV)` and tails the verdict) is tracked separately in AZ-897 and is NOT on the critical path of the CSV redesign; this sub-invariant exists only to record that the format spec (AZ-896) and the CSV adapter (AZ-894) MUST stay UI-friendly (CSV example, format docs link, clear error messages on row-0-misalignment) so AZ-897 lands without contract drift.
+    **Sub-invariant 14.d (operator-facing UI — AZ-897, superseded by Invariant 15)**: retained for historical cycle-4 CSV-only upload spec. Default demo entry is now F11 / AZ-969.
+
+15. **Operator demo replay path (cycle 5 — AZ-969 / F11)**: the default product demo accepts raw `(video, tlog, calibration)` from the suite UI. Alignment is operator-visible (dual timeline bars + explicit refine); the backend exports an AZ-896 CSV whose `Time` column is the single canonical replay clock (Invariant 14.a). Steps: preview timelines (AZ-970) → coarse align + refine (AZ-897, AZ-971) → export CSV (AZ-972) → seed corridor cache from tlog GPS (AZ-974) → run `gps-denied-replay` (AZ-973) → map + verdict. The `(video, pre-authored CSV)` bypass (AZ-959) is optional, not default. E2E tests MUST use the same orchestration modules as production — no parallel test-only graph. AZ-908 (hard removal of alignment stubs) is deferred until AZ-971 ships.

 ## Producer / Consumer Split

@@ -19,6 +19,7 @@
 | 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 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 |
+| F11 | Demo replay validation (operator) | Operator uploads `(video, tlog, calibration)` in suite UI; aligns timelines; runs full GPS-denied replay verdict | [[`suite/ui`]] (AZ-897), `replay_api` (AZ-973), `replay_input` (AZ-970–972), C12 `seed-cache-from-tlog` (AZ-974), C11 route seed, C10, airborne replay (`config.mode=replay`) | High |

 ## Flow Dependencies

@@ -34,6 +35,7 @@
 | 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), 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`) |
+| F11 | F1 route-driven variant (AZ-974) OR warm cache; E-DEMO-REPLAY (AZ-265) | F1 (corridor cache), replay JSONL + map artifacts consumed by suite UI |

 **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.

@@ -53,7 +55,7 @@ This flow is offline and not time-critical. **Only Phase 0 reaches `flights` RES

 #### Phase 1 variant — route-driven seeding (cycle 3 — Epic AZ-835 / AZ-836 + AZ-838 + AZ-839)

-A tlog-driven alternative to bbox download lets the operator (or the post-flight replay harness) pre-commit the cache to the precise corridor the drone actually flew. The path is exercised today by the e2e fixture `tests/e2e/replay/conftest.py::operator_pre_flight_setup` (AZ-839) and the orchestrator test `tests/e2e/replay/test_az835_e2e_real_flight.py` (AZ-840); the C12 production CLI binding for this variant is deferred to a future cycle.
+A tlog-driven alternative to bbox download lets the operator pre-commit the cache to the precise corridor the drone actually flew. **Production bindings** (Epic AZ-969): C12 `seed-cache-from-tlog` (AZ-974) and the `replay_api` demo job (AZ-973) call the same `operator_replay.cache_seed` module. The e2e fixture `operator_pre_flight_setup` (AZ-839) is a thin wrapper over that production path — not a parallel implementation.

 Phase-1 sub-steps in the route-driven variant (replaces the bbox download for that invocation):

@@ -1083,6 +1085,96 @@ flowchart TD

 ---

+## Flow F11: Demo replay validation (operator)
+
+### Description
+
+Post-flight **product demo** and **validation** flow. The operator uploads a nav-camera video and ArduPilot `.tlog` through the suite UI (AZ-897), visually aligns the two recordings on dual timeline bars, and runs the same airborne GPS-denied pipeline used in live flight — against a corridor cache seeded from the tlog GPS trace. Output: per-tick estimated positions (JSONL), accuracy map, and PASS/FAIL verdict against tlog ground truth (AZ-696 AC-3).
+
+This is **not** a test-harness shortcut. E2E tests (AZ-840) call the same `replay_api` orchestration (AZ-973) and `operator_replay.cache_seed` (AZ-974) as the UI.
+
+**Phases** (sequenced by `replay_api` demo job or manual CLI equivalents):
+
+1. **Preview** (AZ-970) — parse tlog IMU2 activity + video metadata for UI timelines.
+2. **Align** (AZ-897 + AZ-971) — operator coarse offset; backend refine via optical-flow + IMU cross-correlation.
+3. **Export** (AZ-972) — write AZ-896 canonical CSV with `Time=0` at aligned video frame 0 (single canonical clock for replay).
+4. **Seed cache** (AZ-974) — `extract_route_from_tlog` → `SatelliteProviderRouteClient.seed_route` → tile download → FAISS build (F1 route-driven variant).
+5. **Replay** — `gps-denied-replay --video … --imu aligned.csv` with `config.mode=replay`; C1–C5 identical to live.
+6. **Verdict** — horizontal-error distribution + map artifact returned to UI.
+
+Advanced bypass: operator may upload a pre-aligned `(video, CSV)` per AZ-959 without steps 1–3.
+
+### Preconditions
+
+- Operator workstation runs `replay_api` (docker-compose or native) with network to `satellite-provider`.
+- Camera calibration JSON for the flight's nav camera.
+- Tlog contains `SCALED_IMU2` (or `RAW_IMU`) and `GLOBAL_POSITION_INT` / `GPS_RAW_INT`.
+- Video covers the active flight segment after alignment.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Operator
+    participant UI as [[suite/ui]] AZ-897
+    participant API as replay_api AZ-973
+    participant Align as replay_input alignment AZ-971
+    participant Export as tlog_to_csv AZ-972
+    participant Seed as operator_replay cache_seed AZ-974
+    participant Sat as [[satellite-provider]]
+    participant Replay as gps-denied-replay
+    participant Pipeline as C1..C5 replay mode
+
+    Operator->>UI: upload video + tlog + calibration
+    UI->>API: POST /replay/preview
+    API-->>UI: video metadata + IMU2 activity timeline
+    Operator->>UI: drag video bar / refine
+    UI->>API: POST /replay/align/refine
+    API->>Align: refine_video_offset
+    Align-->>UI: refined_offset_ms + confidence
+    Operator->>UI: Run demo
+    UI->>API: POST /replay/demo
+    API->>Export: export_aligned_csv
+    API->>Seed: extract_route + seed_route + FAISS
+    Seed->>Sat: POST /api/satellite/route
+    Sat-->>Seed: mapsReady
+    API->>Replay: subprocess --video --imu
+    Replay->>Pipeline: per-frame loop
+    Pipeline-->>API: results.jsonl
+    API-->>UI: map URL + verdict report
+```
+
+### Data flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | UI | replay_api | video + tlog multipart | HTTP |
+| 2 | replay_api | UI | timeline preview JSON | JSON |
+| 3 | UI | replay_api | `video_offset_ms` | JSON |
+| 4 | replay_api | disk | aligned `data_imu.csv` | AZ-896 CSV |
+| 5 | replay_api | satellite-provider | `RouteSpec` waypoints | JSON POST |
+| 6 | replay_api | airborne binary | video + CSV + cache config | subprocess |
+| 7 | replay_api | UI | JSONL path, map URL, verdict md | JSON job result |
+
+### Error scenarios
+
+| Error | Detection | Recovery |
+|-------|-----------|----------|
+| Missing IMU in tlog | preview 422 | Operator message; cannot align |
+| Refine hard-fail (< 95 % frame match) | align/refine response | Operator adjusts bar or aborts |
+| Route seed terminal failure | `RouteTerminalFailureError` | Job failed; operator retries |
+| ESKF divergence (no cache) | replay exit ≠ 0 | Ensure step 4 completed; check AZ-963 |
+
+### Performance expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Preview latency | p95 < 5 s | tlog parse + video probe |
+| Full demo (Derkachi) | ≤ 15 min cold | matches AZ-835 AC-7 |
+| Warm cache reuse | ≤ 30 s seed skip | named volume / cache_root reuse |
+
+---
+
 ## Cross-cutting: FDR write side-effect

 Every flow above produces FDR records (per AC-NEW-3). The cross-cutting rules are: