gps-denied-onboard/_docs/03_implementation/batch_108_cycle3_report.md

Batch 108 — Cycle 3 — AZ-839 operator_pre_flight_setup real fixture

Date: 2026-05-23 Tasks: AZ-839 (C3 — Epic AZ-835). Story points: 5. Jira status: AZ-839 → In Progress (transitioned at batch start); moves to In Testing at commit step.

What shipped

Third building block of Epic AZ-835. Replaces the placeholder operator_pre_flight_setup pytest fixture (the previous mkdir stub at tests/e2e/replay/conftest.py:293-310) with a real driver that wires C1+C2+C11+C10 end-to-end:

1. C1 RouteSpec — extracted from the Derkachi tlog via AZ-836's extract_route_from_tlog (the existing derkachi_replay_inputs session fixture supplies the tlog path; the new fixture chains off that contract).
2. C2 SatelliteProviderRouteClient — seed_route(spec) with the bounded transient-retry ladder documented in AZ-839 AC-5. Validation / terminal failures propagate unchanged (AC-4).
3. C11 HttpTileDownloader — download_tiles_for_area(request) over a bbox derived from the route waypoints (mirrors C2's internal _enumerate_route_tile_coords envelope without importing the private helper).
4. C10 DescriptorBatcher — populate_descriptors(corpus_filter) builds the FAISS HNSW index over the populated C6 cache. The AZ-306 sidecar triple-consistency is verified by re-loading the index through a caller-supplied descriptor_index_factory after the rebuild — any tampering surfaces as IndexUnavailableError (AC-6).
5. Cleanup-on-failure — partial sidecar files written by the driver are removed if any step raises, while pre-existing warm cache files are preserved (AC-7).

Algorithm (populate_c6_from_route) is exposed through pure dependency injection so the AC-8 unit tests run against stubs and the AC-9 integration test runs the same algorithm against real collaborators on the Jetson harness.

Files changed

Tests / fixtures (4):

• tests/e2e/replay/_operator_pre_flight.py (new, ~430 lines) — the AZ-839 driver: PopulatedC6Cache dataclass + populate_c6_from_route() + private helpers (_seed_route_with_retry, _route_bbox, _cleanup_partial_sidecars).
• tests/e2e/replay/conftest.py — replaces the placeholder fixture with the real operator_pre_flight_setup (session-scoped, skip-gated by RUN_REPLAY_E2E + SATELLITE_PROVIDER_URL + SATELLITE_PROVIDER_API_KEY + BUILD_FAISS_INDEX + GPS_DENIED_OPERATOR_CONFIG_PATH); adds three private helpers (_operator_pre_flight_skip_reason, _build_operator_pre_flight_cache, _build_replay_backbone_embedder, _resolve_replay_descriptor_dim, _default_tile_decoder).
• tests/e2e/replay/test_operator_pre_flight_driver.py (new, ~410 lines) — 11 unit tests exercising AC-3 / AC-4 / AC-5 / AC-6 / AC-7 against stubbed SatelliteProviderRouteClient / HttpTileDownloader / DescriptorBatcher / descriptor_index_factory.
• tests/e2e/replay/test_operator_pre_flight_integration.py (new, ~40 lines) — Tier-2 + RUN_REPLAY_E2E gated test that consumes the fixture and asserts the PopulatedC6Cache invariants (AC-9 pytest entry point).

Tracker docs (1):

• _docs/03_implementation/batch_108_cycle3_report.md (this file).

No production-code (src/gps_denied_onboard/**) modifications. The driver lives under tests/ because AZ-839's outcome is the fixture, not a new operator-binary surface; the wiring it does is the existing operator-side runtime factories (runtime_root.c10_factory, runtime_root.c11_factory, runtime_root.storage_factory, runtime_root.inference_factory) already shipped under prior epics.

AC coverage

AC	Test(s)	Status
AC-1 cold first invocation ≤ 5 min	exercised on Tier-2 via AC-9 integration test; PopulatedC6Cache.elapsed_seconds instruments the budget	DEFERRED (Tier-2 only)
AC-2 warm invocation ≤ 30 s	same gated test, re-invocation within session reuses the named-volume mount	DEFERRED (Tier-2 only)
AC-3 populated cache + sidecar triple	test_populate_c6_from_route_returns_populated_cache + test_populate_c6_from_route_passes_sector_class_to_downloader	PASS
AC-4 validation/terminal propagate	test_route_validation_error_propagates_unchanged + test_route_terminal_failure_propagates_unchanged	PASS
AC-5 transient retry ladder (3 attempts, backoff)	test_route_transient_error_retries_then_succeeds + test_route_transient_error_exhausted_propagates_last_attempt	PASS
AC-6 tamper detection → IndexUnavailableError	test_descriptor_index_factory_index_unavailable_propagates	PASS
AC-7 cleanup on failure (no half-built sidecars)	test_cleanup_removes_partial_sidecar_files_on_failure + test_cleanup_preserves_pre_existing_warm_cache + test_batcher_failure_propagates_and_cleans_up + test_downloader_failure_propagates_and_cleans_up	PASS
AC-8 unit tests with stubs (happy / transient / terminal / validation / tamper / cleanup)	11 tests in test_operator_pre_flight_driver.py	PASS
AC-9 integration on Jetson via fixture	test_operator_pre_flight_setup_produces_populated_cache (RUN_REPLAY_E2E + tier2 gated)	DEFERRED (Tier-2 only)

DEFERRED ACs (AC-1, AC-2, AC-9) execute on the Jetson e2e harness when RUN_REPLAY_E2E=1 + SATELLITE_PROVIDER_URL + SATELLITE_PROVIDER_API_KEY + BUILD_FAISS_INDEX=ON + GPS_DENIED_OPERATOR_CONFIG_PATH are set. The pytest entry point exists and skips explicitly per .cursor/skills/implement/SKILL.md Step 8 ("a skipped test counts as Covered").

Test run results

$ .venv/bin/pytest tests/e2e/replay/test_operator_pre_flight_driver.py -v --tb=short
============================== 11 passed in 0.33s ==============================

$ .venv/bin/pytest tests/e2e/replay/test_operator_pre_flight_integration.py -v --tb=short
============================== 1 skipped in 0.29s ==============================
(SKIPPED — Tier-2-only test; set GPS_DENIED_TIER=2 to run)

$ .venv/bin/pytest tests/e2e/replay/ -v --tb=short --timeout=60
====================== 28 passed, 8 skipped in 1.14s =======================

Suite-wide test run is deferred to Step 11 (Run Tests) per the iterative-skill exception in .cursor/rules/coderule.mdc — batch 108 is a batch, not the end of cycle-3 implementation.

Code review (self-review)

Per .cursor/rules/no-subagents.mdc, the structured /code-review skill is run inline. Verdict: PASS_WITH_WARNINGS.

Phase	Result
1. Context loading	AZ-839 task spec + dependencies (AZ-836 RouteSpec, AZ-838 SatelliteProviderRouteClient, AZ-322 DescriptorBatcher, AZ-316 HttpTileDownloader, AZ-306 FaissDescriptorIndex) all read prior to implementation. The FAISS triple-consistency check was verified against faiss_descriptor_index._load() source.
2. Spec compliance	AC-3 / AC-4 / AC-5 / AC-6 / AC-7 / AC-8 directly covered. AC-1 / AC-2 / AC-9 deferred to Tier-2 harness (gated tests exist). No Medium / High findings.
3. Code quality	Driver is one function with one responsibility (orchestrate the C1+C2+C11+C10 pipeline); SRP upheld. Each helper is named after its job (_seed_route_with_retry, _route_bbox, _cleanup_partial_sidecars). Functions ≤ ~80 lines. Explicit exception filtering (RouteValidationError, RouteTerminalFailureError, RouteTransientError) — no bare except. Tests follow Arrange/Act/Assert with comment markers per coderule.mdc.
4. Security quick-scan	JWT consumed via env-sourced kwargs, never logged. The cleanup path does not unlink files outside the cache_root/ tree (only the three sidecar paths the driver was handed).
5. Performance scan	O(n) over waypoints (n ≤ 10 by AZ-836's max_waypoints default). No new N+1. The retry ladder respects the AZ-838 _DEFAULT_BACKOFF_SCHEDULE_S cadence verbatim.
6. Cross-task consistency	Single-task batch — N/A.
7. Architecture compliance	_operator_pre_flight.py lives under tests/e2e/replay/ (test infrastructure). Imports only from C10 / C11 / C6 public surfaces and from replay_input.tlog_route.RouteSpec (Adapter layer per module-layout.md). The conftest fixture wires deps via the existing runtime_root factories — does not import concrete impl modules directly. No cross-component imports between C-prefixed components. No new cyclic dependencies. ADR check skipped (no ADRs directory).

Findings

F1 (Low) — _default_tile_decoder lives in conftest.py

_default_tile_decoder (JPEG → CHW float32 numpy) lives in the test conftest. The same primitive will be needed by the eventual replay-mode operator binary (Epic AZ-835 follow-up); promoting it into runtime_root is out of scope for AZ-839 (which is "wire C10 into a real fixture"), but it is on the path of AZ-840 / AZ-841. Recommendation: leave as-is for AZ-839; revisit during AZ-840.

F2 (Low) — _resolve_replay_descriptor_dim is NetVLAD-only

The NetVLAD descriptor dim resolver pinned at c2_vpr/config.py:67 matches the AZ-839 task spec's "Out of scope" §, but it skips the fixture if any other backbone is configured. Recommendation: when AZ-840 needs a non-NetVLAD backbone, extend the resolver table per strategy. Tracking via the AZ-840 spec is sufficient.

Deltas vs. spec

None. The task spec mentions download_for_bbox; the actual production method is download_tiles_for_area (a bbox-aware single-zoom request via DownloadRequest). The spec was informal on the method name; the production API (which has been stable since AZ-316) was honoured.

Notes for follow-up

• AZ-840 (e2e orchestrator test) consumes this fixture. The fixture already returns a typed PopulatedC6Cache so AZ-840 has a concrete contract to assert against.
• AZ-841 (un-xfail AZ-777 Tier-2 tests) builds on AZ-839 + AZ-840. The existing test_ac8_operator_workflow skip reason in test_derkachi_1min.py (D-PROJ-2 mock-suite-sat-service) is stale post-AZ-839 — AZ-841 will rewrite it to consume the new fixture.
• AZ-842 (docs — replay_protocol.md Invariant 12 + architecture + orchestrator README) describes the route-driven flow this batch ships.