gps-denied-onboard/_docs/03_implementation/reviews/batch_46_review.md

Code Review — Batch 46 / AZ-338 (C2 NetVLAD Mandatory Simple-Baseline)

Date: 2026-05-13 Mode: Per-batch (all 7 phases) Task: AZ-338 — C2 NetVLAD Mandatory Simple-Baseline (3pt) Verdict: PASS_WITH_WARNINGS

Scope

Domain	Files
c2_vpr (production)	net_vlad.py (NEW), _net_vlad_architecture.py (NEW), _preprocessor_net_vlad.py (NEW), inference_runtime_cut.py (NEW — AZ-507 cut of C7 InferenceRuntime), config.py (added netvlad_descriptor_dim: int = 4096), __init__.py (re-exports InferenceRuntimeCut)
Shared helpers	helpers/descriptor_normaliser.py (added intra_cluster_normalise(descriptor, num_clusters) — backward-compatible v1.1.0)
FDR	fdr_client/records.py (registered vpr.embed_query, vpr.backbone_error, vpr.preprocess_error per the AZ-338 spec § Outcome)
Composition root	runtime_root/vpr_factory.py (added _register_strategy_architecture helper; calls C7 register_architecture for the strategy's MODEL_NAME + architecture_factory pair before delegating to create())
Tests	tests/unit/c2_vpr/test_net_vlad.py (NEW, 31 tests), tests/unit/test_az283_descriptor_normaliser.py (+8 tests for the new method), tests/unit/test_az272_fdr_record_schema.py (+3 fixture payloads)
Docs	_docs/02_document/contracts/shared_helpers/descriptor_normaliser.md (v1.0.0 → v1.1.0; documented intra_cluster_normalise row + changelog entry)

Phase 1 — Context Loading

Inputs reviewed:

• AZ-338 spec (_docs/02_tasks/todo/AZ-338_c2_net_vlad.md).
• vpr_strategy_protocol.md v1.0.0 — 7 invariants; INV-3 (L2-normalised embedding) is the central correctness contract.
• c2_vpr/_faiss_bridge.py (AZ-341, prior batch) — the strategy's one-line retrieve delegation target.
• c7_inference/pytorch_fp16_runtime.py (AZ-300) — the runtime that actually deserializes the registered NetVLAD architecture.
• c7_inference/architecture_registry.py — the registration target; rejects re-registration with a different factory under the same key (defensive against accidental collision).
• AZ-507 lint rule (tests/unit/test_az270_compose_root.py::test_ac6_only_compose_root_imports_concrete_strategies) — components MAY NOT import other components.
• _types/inference.py — BuildConfig, EngineCacheEntry, EngineHandle, PrecisionMode (L1 shared DTOs the strategy uses).

Phase 2 — Spec Compliance

All 11 ACs satisfied:

AC	Description	Covering test(s)
AC-1	Protocol conformance	test_ac1_protocol_conformance
AC-2	L2-norm == 1.0 ± 1e-3 FP16 (D,)	test_ac2_embed_query_returns_unit_norm_fp16_descriptor + 512-PCA variant
AC-3	intra_cluster_normalise BEFORE l2_normalise	test_ac3_intra_cluster_called_before_global_l2 + once-each
AC-4	Deterministic across 3 calls	test_ac4_embed_query_deterministic_for_same_frame
AC-5	retrieve_topk == k, label="net_vlad", sorted	test_ac5_retrieve_topk_returns_exactly_k_with_net_vlad_label
AC-6	descriptor_dim() stable	4096 + 512 instance variants
AC-7	Engine output shape mismatch → ConfigError	test_ac7_create_rejects_engine_output_shape_mismatch
AC-8	VprBackboneError on forward failure	RuntimeError + missing-key + wrong-shape variants
AC-9	VprPreprocessError on corrupt image	non-array + wrong-dtype + wrong-shape variants
AC-10	Composition-root wiring + c2.vpr.ready log	INFO log + model_name forcing
AC-11	BUILD_PYTORCH_RUNTIME=OFF → ConfigError fail-fast	tensorrt + onnx_trt_ep runtime label variants

Spec deviations:

• flask runtime.forward(engine_id, ...) → runtime.infer(handle, ...): the spec used placeholder names; the actual C7 InferenceRuntime Protocol API is infer(handle, inputs) + compile_engine + deserialize_engine. Aligned with the live Protocol shape (AZ-297). Flag: spec wording should be refreshed to match the c7 contract.
• Architecture registration moved from c2_vpr.net_vlad.create() to runtime_root/vpr_factory.py::_register_strategy_architecture: the spec implies the strategy's create(...) registers the architecture with C7. That violates AZ-507 (c2_vpr cannot import c7_inference). Resolved by exposing MODEL_NAME + architecture_factory(descriptor_dim) on the strategy module and having the composition root perform the c7 binding before calling create(...). The C7-side register_architecture call lives at L4 (runtime_root), not L3. This is a design improvement over the spec; the spec should be updated.
• NetVladStrategy.__init__ signature: differs from the spec's positional argument list (the spec lists runtime, tile_store, weights_path, preprocessor, normaliser, fdr_client, descriptor_dim). Implemented as keyword-only with engine_handle (returned from deserialize_engine) replacing weights_path (the strategy holds the resolved handle, not the source path — per the spec's own "holds the engine ID, NOT the engine itself" constraint, more consistent). The tile_store field also got renamed descriptor_index to match DescriptorIndexCut (AZ-507 cut).

Aligning the spec with the implementation is in the Findings below (see F2).

Phase 3 — Code Quality

• Every function ≤ ~50 LOC except make_net_vlad_vgg16 (~75 LOC of which 60 is inner nn.Module definitions — natural, indivisible).
• No bare except; every error chain uses raise ... from exc.
• No silently-swallowed errors; the strategy emits ERROR logs + an FDR record for both VprBackboneError and VprPreprocessError paths.
• Constructor validation is consistent: ValueError for range/shape violations, TypeError for type violations (matches the pattern of the prior batch's FaissBridge).
• The _iso_ts_from_clock helper is duplicated yet again — sixth module-local copy (see F1 below; carried-over from cumulative review 43-45).
• Class names (NetVladStrategy, NetVladBackbonePreprocessor) match the spec.
• No verbose default-on debug logging; logs are scoped to ERROR-on-error
  • one INFO c2.vpr.ready at composition time.
• Ruff clean on every new file (UP037 auto-fixes applied; one RUF002 ambiguous-glyph in _net_vlad_architecture.py docstring fixed in Phase F).

Phase 4 — Security Quick-Scan

• No SQL injection / command injection / eval / exec.
• No hardcoded secrets.
• FDR error-message payload is bounded to str(error)[:512] — prevents unbounded sensitive-data exfiltration via long exception messages.
• No PII; vpr.embed_query payload is (frame_id, backbone_label, descriptor_dim, latency_us) — all operational metadata.
• The intra_cluster_normalise helper rejects float64 input — denies upcasts that would silently break the FAISS metric.
• The c7_inference.register_architecture call lives in the composition root which runs at startup; not reachable from user-controlled input.

Phase 5 — Performance Scan

• embed_query p95 ≤ 80ms NFR — not verified by microbench in this batch (deferred to C2-IT-01 / FT-P-19, Step 9). Justification: microbench requires real PyTorch CUDA + real NetVLAD weights; the current Tier-1 host has neither.
• retrieve_topk p95 ≤ 4ms — the FaissBridge (AZ-341) already carries the p95 ≤ 500µs microbench; this strategy is a single-line delegation, no added overhead.
• The architecture's NetVLAD pooling layer uses torch.bmm for the K-cluster reduction instead of a Python loop — single optimised CUDA kernel call. The published reference impl from Pittsburgh has a Python for k in range(K) loop; this batched form is asymptotically equivalent (K ~ 64) and dramatically faster on GPU.
• The dual-stage normalisation is two FP32-on-FP16-input operations, ~ 4096-element working set — sub-µs on any host.

Phase 6 — Cross-Task Consistency

NetVLAD is the first concrete VprStrategy implementation. Cross-task consistency therefore concerns the patterns it establishes for AZ-337 (UltraVPR), AZ-339 (MegaLoc/MixVPR), AZ-340 (SelaVPR/EigenPlaces/SALAD):

• AZ-507 cut pattern: InferenceRuntimeCut joins DescriptorIndexCut (AZ-341), TileUploaderCut (AZ-329), TileDownloaderCut (AZ-328). Five Protocol cuts now exist cross-component; all named *Cut; all runtime_checkable=True; all one Protocol per file; all consumed via the consumer-side cut module path. Pattern is stable.
• Architecture-registration split: the strategy module exposes MODEL_NAME + architecture_factory(descriptor_dim); the composition root performs the c7 registration. Future C2 strategies using the PyTorch runtime (AZ-339 MegaLoc/MixVPR with VGG/ResNet backbones; AZ-340 SelaVPR/EigenPlaces/SALAD with various backbones) follow the same shape; the composition-root helper _register_strategy_architecture already has the dispatch slot for per-strategy descriptor_dim lookup.
• Dual-stage normalisation: NetVLAD's intra_cluster_normalise
  • l2_normalise chain is unique to NetVLAD (UltraVPR uses single-stage l2_normalise per the AZ-337 spec). The helper addition to DescriptorNormaliser is therefore NetVLAD-specific by invocation but architectural-pattern-neutral by API; future VLAD-aggregating strategies (SALAD has VLAD-like aggregation) can reuse the same helper.
• FDR record kinds: vpr.embed_query / vpr.backbone_error / vpr.preprocess_error are strategy-generic; every concrete C2 strategy emits the same three plus the AZ-341 vpr.retrieve_topk from the bridge.

Phase 7 — Architecture Compliance

1. Layer direction (rule 1): no upward imports. The strategy module imports _types, clock, config, fdr_client, helpers, logging, and its sibling c2_vpr modules — all at or below L3.
2. Public API respect / AZ-507 (rule 2): verified by the test_ac6_only_compose_root_imports_concrete_strategies lint: PASS. c2_vpr/net_vlad.py consumes InferenceRuntimeCut (defined in c2_vpr) instead of importing c7_inference.InferenceRuntime.
3. No new cyclic dependencies (rule 3): no new cycles.
4. Duplicate symbols (rule 4): _iso_ts_from_clock now in 6 modules (carry-over F1, AZ-508 covers consolidation). No new duplications introduced.
5. Cross-cutting concerns not locally re-implemented (rule 5): the composition root owns the c7 architecture registration; the c2_vpr factory does not.

Findings

#	Severity	Category	Files	Title
F1	Low	Maintainability	c2_vpr/net_vlad.py	_iso_ts_from_clock duplicated (6th module-local copy)
F2	Low	Spec-Hygiene	AZ-338 task spec	Spec § Outcome lists outdated C7 API names (runtime.forward vs infer; runtime.load_engine vs compile_engine + deserialize_engine) + architecture-registration location
F3	Low	Test-Coverage	tests/unit/c2_vpr/test_net_vlad.py	NFR-perf microbench (p95 ≤ 80ms) deferred (no Tier-1 PyTorch CUDA host); flagged in Phase 5
F4	Low	Architecture	_net_vlad_architecture.py	NetVLAD's PCA-projection layer parameters are part of the loaded .pth state dict; weights validation that the PCA centroids match the recorded sidecar is deferred to AZ-280 (engine sidecar) integration

Finding Details

F1: _iso_ts_from_clock duplicated (6th copy) (Low / Maintainability)

• Location: src/gps_denied_onboard/components/c2_vpr/net_vlad.py module-level function.
• Description: same 6-line helper as c2_vpr/_faiss_bridge.py, c12_operator_orchestrator/operator_reloc_service.py, c11_tile_manager/idempotent_retry.py, c11_tile_manager/signing_key.py, c6_tile_cache/postgres_filesystem_store.py, c6_tile_cache/freshness_gate.py — six modules now.
• Suggestion: AZ-508 (hygiene PBI for ISO-timestamp consolidation) is already in todo/ and scoped to absorb all six call-sites.

F2: AZ-338 spec uses outdated C7 API names + architecture-registration location (Low / Spec-Hygiene)

• Locations:
  • Spec § Outcome: intermediate = self._runtime.forward(self._engine_id, {"input": tensor}) → live API is self._runtime.infer(self._engine_handle, {"input": tensor}).
  • Spec § Outcome: inference_runtime.load_engine(weights_path) → live API is compile_engine(model_path, build_config) -> entry; deserialize_engine(entry) -> handle.
  • Spec § Outcome implies create(...) performs the C7 architecture registration; AZ-507 forbids this. Resolved by moving the registration to runtime_root/vpr_factory.py::_register_strategy_architecture.
• Description: the spec was written against an earlier C7 Protocol draft; the C7 Protocol stabilised at v1.0.0 in AZ-297. The implementation aligns with the v1.0.0 Protocol; the spec is now stale on this detail.
• Suggestion: surface to user as a small spec-hygiene follow-up. Same class of finding as cumulative review F3 (AZ-341 spec listed an unused normaliser parameter). Recommend a single hygiene PBI scoped to "refresh AZ-337..AZ-340 specs against the stabilised C7 v1.0.0 + AZ-507 patterns".

F3: NFR-perf microbench deferred (no Tier-1 PyTorch CUDA host) (Low / Test-Coverage)

• Location: tests/unit/c2_vpr/test_net_vlad.py (no microbench test class for AZ-338 NFR-perf).
• Description: the AZ-338 spec NFRs cite p95 ≤ 80ms for embed_query on Tier-1 Jetson Orin. Microbench requires real PyTorch CUDA + real NetVLAD weights; not runnable on this Tier-0 dev host (macOS, no CUDA). The fake InferenceRuntime returns a synthetic output and therefore cannot probe real-runtime latency.
• Suggestion: schedule under FT-P-19 / C2-IT-01 (Step 9 / E-BBT) on Tier-1 hardware. No action this batch.

F4: PCA-projection sidecar verification deferred (Low / Architecture)

• Location: src/gps_denied_onboard/components/c2_vpr/_net_vlad_architecture.py PCA nn.Linear(K*D, descriptor_dim).
• Description: the architecture loads its PCA-projection layer's weights from the same .pth state dict as the rest of the model via torch.load + load_state_dict(strict=True). There is no separate check that the PCA centroids + whitening matrix match the sha256 sidecar (AZ-280). For now the deserialize-time strict-mode check is the only safeguard.
• Suggestion: schedule under a future "C2 PCA-whitening sidecar validation" PBI if FT-P-19 / C2-IT-01 reveals real-world drift. No action this batch.

Verdict

PASS_WITH_WARNINGS — 4 Low-severity findings, all hygiene / deferred-validation. No Critical, no High, no Medium. AC coverage is complete; full unit suite is green (1608 passed / 80 env-skipped, +43 tests over batch 45).