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

Batch 50 — Implementation Report (Cycle 1)

Tasks: AZ-339 (C2 MegaLoc + MixVPR Secondary Backbones — Research-only) Date: 2026-05-13 Cycle: 1 Status: COMPLETE (review verdict: PASS_WITH_WARNINGS, one Medium + one Low finding)

What was done

Added two secondary VprStrategy implementations for IT-12 comparative-study: MegaLocStrategy (D=2048, 322×322 input) and MixVprStrategy (D=4096, 320×320 input). Both run via the C7 TensorRT runtime (or ONNX-Runtime fallback), apply ImageNet mean/std preprocessing + single-stage L2 normalisation, and delegate retrieval to FaissBridge. Both are gated OFF for airborne and operator-tooling per ADR-002 — BUILD_VPR_MEGALOC and BUILD_VPR_MIXVPR ON only for the research binary and replay-cli.

Files added (5)

File	Purpose
src/gps_denied_onboard/components/c2_vpr/mega_loc.py	MegaLocStrategy class + create() factory + _assert_engine_output_dim helper
src/gps_denied_onboard/components/c2_vpr/_preprocessor_mega_loc.py	MegaLocBackbonePreprocessor (centre-crop + 322×322 resize + ImageNet normalise + FP16 NCHW)
src/gps_denied_onboard/components/c2_vpr/mix_vpr.py	MixVprStrategy class + create() factory + _assert_engine_output_dim helper
src/gps_denied_onboard/components/c2_vpr/_preprocessor_mix_vpr.py	MixVprBackbonePreprocessor (centre-crop + 320×320 resize + ImageNet normalise + FP16 NCHW)
tests/unit/c2_vpr/test_az339_mega_loc_mix_vpr.py	36 parametrised AC tests across both strategies

Files changed

• None. The composition-root factory (runtime_root/vpr_factory.py) was already wired for mega_loc and mix_vpr strategy names at AZ-336 land time — _STRATEGY_TO_BUILD_FLAG and _STRATEGY_TO_MODULE tables already include the rows. The KNOWN_STRATEGIES frozenset in c2_vpr/config.py already includes both. The module-layout.md Component: c2_vpr § Internal list already names mega_loc.py and mix_vpr.py (pre-declared by AZ-336). No CMake change required — BUILD_VPR_* gating is environment-variable-based per _is_build_flag_on in vpr_factory.py.

AC coverage

All 11 ACs verified per strategy via the parametrised test suite. See _docs/03_implementation/reviews/batch_50_review.md § Phase 2 for the AC ↔ test mapping table.

AC	Status	Notes
AC-1..AC-9 + AC-11	PASS	Each AC parametrised over both strategies (36 test cases total)
AC-10	PASS with drift	Implementation raises StrategyNotAvailableError (env-flag OFF path) and ConfigError (runtime-label mismatch path); the spec literally names ConfigurationError. Mirrors the established AZ-337 / AZ-338 precedent. Logged as Low finding F2.

Test results

• tests/unit/c2_vpr/test_az339_mega_loc_mix_vpr.py — 36 / 36 PASS.
• tests/unit/c2_vpr/test_protocol_conformance.py — 25 / 25 PASS (auto-extends across all 7 strategies; the two new ones are picked up by the parametrised _STRATEGY_MODULES table without test changes).
• tests/unit/c2_vpr/ (full directory: faiss_bridge + net_vlad + ultra_vpr + new AZ-339 file) — 126 / 126 PASS.
• tests/unit/test_az508_iso_timestamps.py — 18 / 18 PASS (AZ-526 regression guard confirms no new _iso_ts_from_clock duplicates introduced by the AZ-339 strategies).
• tests/unit/test_az270_compose_root.py — 8 / 8 PASS.
• tests/unit/test_az272_fdr_record_schema.py — 33 / 33 PASS (unmodified; the new strategies emit FDR records that match the existing schema).
• Full unit suite: 1690 passed, 80 skipped (TRT/CUDA/actionlint), 1 pre-existing failure (test_cold_start_under_500ms_p99 — subprocess timeout on cold-start latency budget, unrelated; confirmed by stashing AZ-339 changes and re-running).
• ruff check on all 5 new files — clean.

Architectural decisions

1. Single parametrised test file test_az339_mega_loc_mix_vpr.py — rather than two near-identical files mirroring test_ultra_vpr.py / test_net_vlad.py. The two strategies share byte-identical behavioural contracts (same Protocol, same FDR record kinds, same log kinds, same error envelope) and differ only on three values (DESCRIPTOR_DIM, _BACKBONE_LABEL, preprocessor input_shape()). A parametrised approach keeps any future drift visible at the assertion level and reduces the test surface from ~1500 lines (two copies of test_ultra_vpr.py) to ~700 lines.
2. Preprocessor duplication preserved (mega_loc vs mix_vpr vs ultra_vpr) — per components/02_c2_vpr/description.md § 6 and the task spec § Constraints. Each preprocessor owns its own input-shape constants so a future code drop can change a backbone's preprocessing without coupling other strategies' weights-versions.
3. _assert_engine_output_dim duplicated, NOT extracted — see Spec Drift / Review Finding F1 below. The cleaner path is a dedicated AZ-527 hygiene PBI mirroring AZ-508 → AZ-526.
4. iso_ts_from_clock imported from the AZ-526 helper from day 1 — neither new strategy introduces a local _iso_ts_from_clock body. The AZ-526 regression guard test confirms this.
5. Runtime-label guard placed inside create() (not in __init__) — runtime selection is a composition-time concern; once the strategy is constructed it's expected to work. Matches the UltraVPR / NetVLAD precedent.

Spec drift noted (carried into review F2)

AZ-339 § AC-10 literally specifies ConfigurationError for the build-flag-OFF case. The existing AZ-336 composition-root factory raises StrategyNotAvailableError for this case (per its own contract and test coverage at test_protocol_conformance.py:268-274). The strategy module's own runtime-label guard raises ConfigError for the related "wrong C7 runtime" case. AZ-337 (UltraVPR) and AZ-338 (NetVLAD) followed this same pattern; AZ-339 mirrors them. AC-10 wording should be amended in a future spec pass; no code change required.

Cumulative review obligation

This batch is mid-window (batch 50, next cumulative review at batch 51 / batches 49-51). The new finding F1 (_assert_engine_output_dim 4-way duplication) will surface in that cumulative review, and AZ-527 (the planned hygiene PBI) will close it. The AZ-526 regression guard test confirmed that neither AZ-526's F1+F3 closure regressed in AZ-339.

Follow-on PBI

AZ-527 (Hygiene — consolidate _assert_engine_output_dim into a c2-internal helper). 2 points. Depends on AZ-339. To be created and prioritised as Batch 51 or 52.