[AZ-336] C2 VprStrategy: Protocol + DTOs + factory + composition

Foundational scaffolding for every concrete C2 backbone (UltraVPR,
NetVLAD, MegaLoc, MixVPR, SelaVPR, EigenPlaces, SALAD — AZ-337..AZ-340)
and the C2.5 ReRanker consumer side. No backbone is implemented here.

* VprStrategy Protocol (embed_query / retrieve_topk / descriptor_dim)
  + BackbonePreprocessor C2-internal Protocol (NOT in Public API per
  description.md § 6).
* DTOs in L1 _types/vpr.py — VprQuery, VprCandidate, VprResult; all
  frozen + slots; tuple-not-list for VprResult.candidates so the
  immutability invariant truly holds.
* Error family: VprError + VprBackboneError + VprPreprocessError +
  IndexUnavailableError; same-named but namespace-distinct from
  c6_tile_cache.IndexUnavailableError (the c2 family is the closed
  envelope C5 / C2.5 consume; concrete strategies rewrap the C6 form).
* C2VprConfig (strategy enum + backbone_weights_path + faiss_index_path)
  with strict validation at load; registered into Config.components on
  c2_vpr import.
* build_vpr_strategy factory with 7-strategy resolution table, lazy
  import, BUILD_VPR_<variant> gating, ImportError→
  StrategyNotAvailableError mapping, and pre-flight descriptor_dim
  match against DescriptorIndex.descriptor_dim() — mismatch fires
  ConfigError at startup, NOT at first frame.

Contract change vs the v1.0.0 draft: factory takes descriptor_index:
DescriptorIndex (not tile_store: TileStore) because descriptor_dim()
lives on DescriptorIndex per C6's Public API. The contract markdown
is updated to match.

Architecture: VprCandidate.tile_id is a plain (zoom, lat, lon) tuple,
keeping _types/ (L1) free of any c6_tile_cache (L3) import per
module-layout.md. Consumers reconstruct TileId at the C6 boundary.

Excluded per task spec:
* Concrete backbones (AZ-337..AZ-340).
* FAISS HNSW retrieve wiring (AZ-341).
* DescriptorNormaliser helper (AZ-283, already shipped).
* AC-9 single-thread binding — deferred per task spec Risk 4 until the
  generic compose_root thread-binding registry is in place (today
  each factory owns its own, e.g. fc_factory).

Tests: 45 ACs + NFRs in tests/unit/c2_vpr/test_protocol_conformance.py
covering AC-1..AC-8, the error family, the config validation, the
factory NFR (p99 ≤ 50 ms). The legacy smoke test is removed. Full
sweep 973 passed, 2 skipped (CI-only cmake / actionlint).

Co-authored-by: Cursor <cursoragent@cursor.com>

src/gps_denied_onboard/components/c2_vpr/interface.py

@@ -1,17 +1,113 @@
-"""C2 `VprStrategy` Protocol.
+"""C2 ``VprStrategy`` Protocol (AZ-336).
 
-Concrete strategies: UltraVPR (primary), MegaLoc, MixVPR, SelaVPR, EigenPlaces,
-NetVLAD, SALAD. See `_docs/02_document/components/02_c2_vpr/`.
+PEP 544 ``typing.Protocol`` with ``runtime_checkable=True``; three
+methods spanning the camera-ingest hot path
+(:meth:`embed_query` + :meth:`retrieve_topk`) and the composition-time
+pre-flight check (:meth:`descriptor_dim`).
+
+Concrete impls — :class:`UltraVprStrategy` (AZ-337),
+:class:`NetVladStrategy` (AZ-338), :class:`MegaLocStrategy` /
+:class:`MixVprStrategy` (AZ-339), :class:`SelaVprStrategy` /
+:class:`EigenPlacesStrategy` / :class:`SaladStrategy` (AZ-340) — live
+in sibling modules and are imported lazily by
+:mod:`gps_denied_onboard.runtime_root.vpr_factory`.
+
+The contract at
+``_docs/02_document/contracts/c2_vpr/vpr_strategy_protocol.md`` v1.0.0
+is the authoritative shape; this module mirrors it 1:1.
 """
 
 from __future__ import annotations
 
-from typing import Protocol
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
-from gps_denied_onboard._types.vpr import VprQuery, VprResult
+if TYPE_CHECKING:
+    from gps_denied_onboard._types.calibration import CameraCalibration
+    from gps_denied_onboard._types.nav import NavCameraFrame
+    from gps_denied_onboard._types.vpr import VprQuery, VprResult
+
+__all__ = ["VprStrategy"]
 
 
+@runtime_checkable
 class VprStrategy(Protocol):
-    """Visual Place Recognition strategy: encode → retrieve top-K candidates."""
+    """Single-camera visual place recognition strategy.
 
-    def retrieve(self, query: VprQuery, top_k: int = 10) -> VprResult: ...
+    Stateless per-frame; the only persistent state is the loaded
+    backbone weights and the C6-owned FAISS index handle (passed in
+    via constructor by the strategy's ``create(...)`` factory).
+
+    Invariants (see ``vpr_strategy_protocol.md`` v1.0.0):
+
+    - **INV-1 single-threaded** — each instance is bound to one
+      ingest thread; the composition root enforces. Concurrent
+      :meth:`embed_query` calls on a single instance race the GPU
+      stream.
+    - **INV-2 stateless per-frame** — no implicit dependency on
+      prior frames; reordering :meth:`embed_query` calls yields
+      identical embeddings.
+    - **INV-3 L2-normalised** — :attr:`VprQuery.embedding` is
+      L2-normalised before return (cosine ≡ Euclidean on the
+      FAISS HNSW lookup).
+    - **INV-4 top-K size + order** — :meth:`retrieve_topk` returns
+      exactly ``k`` candidates, ascending by
+      :attr:`VprCandidate.descriptor_distance`.
+    - **INV-5 backbone_label non-empty** — every
+      :attr:`VprResult.backbone_label` matches the strategy's
+      ``BUILD_VPR_<variant>`` lowercase form.
+    - **INV-6 deterministic** — same frame + calibration + corpus
+      → identical embedding + identical top-K (bit-exact for
+      float32; ULP-tolerant for float16).
+    - **INV-7 descriptor_dim stable** — :meth:`descriptor_dim`
+      never changes after construction; reflects the loaded
+      weights' output dim, NOT a config knob.
+
+    Error envelope: only members of
+    :class:`gps_denied_onboard.components.c2_vpr.errors.VprError`
+    escape the three methods. Lower-level exceptions (CUDA, TRT,
+    FAISS) MUST be rewrapped by the concrete strategy.
+    """
+
+    def embed_query(
+        self,
+        frame: "NavCameraFrame",
+        calibration: "CameraCalibration",
+    ) -> "VprQuery":
+        """Run the backbone forward pass; return a ``VprQuery``.
+
+        Calibration is consumed by the strategy's internal
+        :class:`BackbonePreprocessor` for resize / crop / normalise.
+
+        Raises :class:`VprBackboneError` on backbone failure
+        (CUDA OOM, TRT deserialize mismatch, etc.) and
+        :class:`VprPreprocessError` on preprocessor contract
+        violation.
+        """
+        ...
+
+    def retrieve_topk(self, query: "VprQuery", k: int) -> "VprResult":
+        """Run the FAISS HNSW top-K lookup against the corpus index.
+
+        The strategy holds the FAISS index handle
+        (constructor-injected from C6's ``DescriptorIndex``).
+        Top-K candidates are returned ascending by
+        :attr:`VprCandidate.descriptor_distance`.
+
+        Raises :class:`IndexUnavailableError` when the FAISS index
+        handle is invalid (post-F8 reboot before warm-up;
+        out-of-band file replacement caught by mmap defence;
+        fewer than ``k`` indexed vectors).
+        """
+        ...
+
+    def descriptor_dim(self) -> int:
+        """Backbone embedding dimensionality.
+
+        Examples: 512 for UltraVPR; 4096 for NetVLAD-VGG16.
+        Stable for the strategy's lifetime. Consumed by the
+        composition root at startup to pre-validate index
+        compatibility against the C6 ``DescriptorIndex`` sidecar
+        (mismatch → :class:`ConfigError` at startup, NOT at first
+        frame).
+        """
+        ...