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

Batch 45 — Cycle 1 Report

Date: 2026-05-13 Batch: 45 Tasks: AZ-341 (C2 FAISS HNSW Retrieve Wiring, 3pt) Status: complete; ticket transitioned to "In Testing".

Scope

AZ-341 delivers FaissBridge — the cross-strategy shared plumbing that connects every concrete C2 VprStrategy.retrieve_topk to C6's FAISS HNSW DescriptorIndex.search_topk surface. The bridge owns the defended-in-depth INV-4 check (exactly K results, distance-ascending), the WARN-threshold check on distances[0], the optional per-frame DEBUG top10_distances log, and the vpr.retrieve_topk FDR record emission with monotonic-ns latency measurement.

Companion deliverables in the same batch:

• DescriptorIndexCut Protocol — the AZ-507 consumer-side structural cut that keeps c2_vpr/*.py import-free of c6_tile_cache.*.
• C2VprConfig gains two operator-tunable knobs: warn_top1_threshold (default 0.30 — task-spec Risk 3 conservative placeholder pending FT-P-19 telemetry) and debug_per_frame_distances (default OFF — Risk 2 mitigation against journald flood).
• fdr_client.records registers vpr.retrieve_topk in KNOWN_PAYLOAD_KEYS and the AZ-272 roundtrip schema test gains a fixture for the new kind (mirroring the Batch-44 c12.reloc.requested pattern).

Unblocks each future C2 strategy (AZ-337 UltraVPR, AZ-338 NetVLAD, AZ-339 MegaLoc+MixVPR, AZ-340 SelaVPR+EigenPlaces+SALAD): every strategy's retrieve_topk shrinks to a one-line delegation return self._faiss_bridge.retrieve(query, k, backbone_label=...), eliminating the seven-way duplication risk the task spec called out.

Architectural Decisions

1. The bridge is stricter than the c6 contract — by design

C6's descriptor_index.md Invariant I-2 says search_topk "MAY return fewer than K results when the corpus has fewer than K vectors". The AZ-341 task spec asks the bridge to enforce == K and raise IndexUnavailableError on undersized returns. The two contracts are complementary, not contradictory:

• C6's I-2 is a structural invariant (the return-shape upper bound, not a guarantee of full results).
• AZ-341's INV-4 is an operational invariant (a corpus with fewer than K vectors is operationally degraded; the system can not function — downstream RANSAC matching needs the full top-K spread).

The bridge's module docstring documents this on-purpose strictness. The defended-in-depth posture is the task-spec's explicit Risk-1 mitigation against silent C6 regressions.

2. The bridge propagates the c6 IndexUnavailableError unchanged

AC-4 is explicit: "the bridge does not catch and re-raise". The bridge has no try/except IndexUnavailableError. When the c6 stale-handle / sidecar / dim-mismatch defence fires, the original c6 exception escapes directly to the strategy and onwards.

This conflicts with the c6_tile_cache.errors.IndexUnavailableError module docstring's expectation that "the C2 family is the closed envelope a C5/C2.5 consumer sees; the C6 family is the storage-layer error a concrete strategy is responsible for rewrapping". The implementation follows the task-spec letter; surfacing the gap as Finding F2 of the per-batch review for spec/code-comment alignment.

3. _iso_ts_from_clock is duplicated — accepted for this batch

The helper is six lines that appear inline in c2 / c5 / c11 / c12. Each component avoids importing the others' helpers (per AZ-507 shape). A future shared helper would live in shared/helpers/ (L1) but factoring is deferred to AZ-508 (the hygiene-only PBI already in todo/ covering ISO-timestamp consolidation across the suite). Captured as Finding F1.

4. The dropped normaliser constructor parameter

The task spec's Outcome § Constructor lists normaliser: DescriptorNormaliser but the documented retrieve body never calls it — the VprStrategy Protocol INV-3 already requires VprQuery.embedding to arrive L2-normalised. The bridge omits the parameter (no behaviour change vs the documented body). Captured as Finding F2 for spec hygiene.

Files Changed

Production source (new)

• src/gps_denied_onboard/components/c2_vpr/_faiss_bridge.py — FaissBridge class (~250 LOC), _verify_invariants / _log_invariant_violation / _emit_fdr_record / _iso_ts_from_clock helpers, module-level FDR / log kind constants.
• src/gps_denied_onboard/components/c2_vpr/descriptor_index_cut.py — DescriptorIndexCut Protocol + TileIdTuple alias (~50 LOC).

Production source (modified)

• src/gps_denied_onboard/components/c2_vpr/config.py — C2VprConfig gains warn_top1_threshold: float = 0.30 and debug_per_frame_distances: bool = False plus their validators.
• src/gps_denied_onboard/components/c2_vpr/__init__.py — re-exports DescriptorIndexCut and TileIdTuple for the composition root's c6 adapter.
• src/gps_denied_onboard/fdr_client/records.py — registers vpr.retrieve_topk in KNOWN_PAYLOAD_KEYS with payload field set {frame_id, backbone_label, top10_distances, latency_us}.

Tests (new)

• tests/unit/c2_vpr/test_faiss_bridge.py — 22 tests covering AC-1..AC-11, NFR-perf microbench (p95 ≤ 0.5 ms), constructor validation, retrieve-argument validation. Uses _FakeDescriptorIndex, _StubClock, and a real FdrClient with power-of-two capacity 8 to verify both the success enqueue pattern and the OVERRUN warn path.

Tests (modified)

• tests/unit/test_az272_fdr_record_schema.py — adds a vpr.retrieve_topk payload to the _make_fdr_payload fixture so the schema roundtrip + envelope tests cover the new kind.

Docs / process

• _docs/03_implementation/reviews/batch_45_review.md — per-batch code review (verdict PASS_WITH_WARNINGS, 2 Low findings).
• _docs/_autodev_state.md — sub_step bumped through the batch loop.

Test Results

1565 passed, 80 skipped in 69.9s

Versus pre-batch (Batch 44 final): 1543 passed, 80 skipped.

Delta: +22 new tests (all in tests/unit/c2_vpr/test_faiss_bridge.py), zero regressions, zero new skips.

Code Review

Verdict: PASS_WITH_WARNINGS — see _docs/03_implementation/reviews/batch_45_review.md.

Two Low-severity findings:

#	Severity	Category	Title
F1	Low	Maintainability	Duplicated _iso_ts_from_clock helper across c2/c5/c11/c12 — defer to AZ-508
F2	Low	Spec-Gap	Task spec lists unused normaliser parameter — surface to user / spec hygiene

No Critical, no High, no Medium. The Auto-Fix Gate accepts the verdict without intervention.

AC Coverage Summary

All 11 acceptance criteria + NFR-perf have at least one covering test. Detailed AC ↔ test mapping in _docs/03_implementation/reviews/batch_45_review.md § Phase 2.

Tracker

• AZ-341 transitioned To Do → In Progress at batch start.
• AZ-341 transitioned In Progress → In Testing after the commit landed.

Cumulative Review (batches 43-45)

Last cumulative review was for batches 40-42. With Batch 45 closed (43, 44, 45 since the last cumulative), the implement skill's Step 14.5 cumulative review fires next at K=3.

Next Batch

Several C-component slices are now unblocked:

• C1: AZ-333 (VINS-Mono strategy, research), AZ-334 (KLT/RANSAC mandatory baseline). Then AZ-335 (warm-start) once 333+334 land.
• C2: AZ-337 (UltraVPR primary, 5pt), AZ-338 (NetVLAD baseline, 3pt), AZ-339 (MegaLoc+MixVPR research), AZ-340 (SelaVPR+ EigenPlaces+SALAD research).
• C3: AZ-345 / AZ-346 / AZ-347 — pending the C2.5 ReRanker tasks.

A natural Batch-46 candidate would be a C1 mandatory simple-baseline (AZ-334) — single 5pt task, OpenCV-based, no model weights — but the next-batch selection will go through the implement skill's Step 3 (Compute Next Batch) afresh.