[AZ-341] C2 FAISS HNSW retrieve wiring (FaissBridge + AZ-507 cut)

Shared retrieve_topk plumbing for every concrete C2 VprStrategy:
- FaissBridge centralises the c6 search_topk → VprResult pipeline,
  the defended-in-depth INV-4 check (exactly k, distance-ascending),
  the WARN-threshold check on distances[0], optional per-frame DEBUG
  log, and one `vpr.retrieve_topk` FDR record per call with latency
  measurement.
- DescriptorIndexCut Protocol — consumer-side structural cut of c6
  DescriptorIndex.search_topk (AZ-507); keeps c2_vpr c6-import-free.
- C2VprConfig gains warn_top1_threshold + debug_per_frame_distances
  knobs with validators.
- KNOWN_PAYLOAD_KEYS registers vpr.retrieve_topk for the FDR record
  schema with payload {frame_id, backbone_label, top10_distances,
  latency_us}; companion fixture added to the AZ-272 roundtrip suite.
- 22 unit tests cover AC-1..AC-11 + NFR-perf microbench (p95 ≤ 0.5 ms)
  + constructor and retrieve-argument validation.

Verdict: PASS_WITH_WARNINGS (2 Low findings — duplicated ISO-ts
helper across c2/c5/c11/c12, captured in AZ-508 hygiene PBI;
spec-listed but unused `normaliser` parameter dropped — INV-3 makes
the embedding L2-normalised at the strategy's `embed_query`).

Tests: 1565 passed / 80 skipped (was 1543; +22 new tests).
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-13 21:45:40 +03:00
parent 25836925c9
commit 88f6ae6dce
9 changed files with 1327 additions and 4 deletions
@@ -296,6 +296,24 @@ KNOWN_PAYLOAD_KEYS: Final[dict[str, frozenset[str]]] = {
"ts_monotonic_ns",
}
),
# AZ-341 / E-C2: emitted by the c2_vpr FaissBridge on every
# successful ``retrieve(...)`` call (post-flight retrieval
# provenance for forensic A/B against tile_match outcomes).
# ``frame_id`` echoes ``VprQuery.frame_id``; ``backbone_label`` is
# the strategy's lowercase ``BUILD_VPR_<variant>`` token (e.g.
# ``"ultra_vpr"`` / ``"net_vlad"``); ``top10_distances`` is the
# full ascending-sorted distance vector (≤10 floats — the bridge
# caps at top-K=10 today); ``latency_us`` is the bridge-internal
# ``Clock.monotonic_ns`` delta around the c6 search, in integer
# microseconds.
"vpr.retrieve_topk": frozenset(
{
"frame_id",
"backbone_label",
"top10_distances",
"latency_us",
}
),
}
KNOWN_KINDS: Final[frozenset[str]] = frozenset(KNOWN_PAYLOAD_KEYS.keys())