[AZ-345] [AZ-346] [AZ-347] [AZ-349] C3 matchers + C3.5 AdHoP refiner

Implement the three concrete C3 CrossDomainMatcher strategies plus the
C3.5 production-default AdHoPRefiner.

C3 (AZ-345/346/347):
- DiskLightGlueMatcher + AlikedLightGlueMatcher share a single shared
  _pipeline.run_lightglue_pipeline orchestrator (decode -> query
  extract -> per-candidate loop -> RANSAC sort -> health update ->
  FDR emit) so the only per-backbone delta is the keypoint+descriptor
  extractor closure. ALIKED adds a create-time engine output-schema
  probe (AC-special-1).
- XFeatMatcher owns its own per-candidate loop (single forward fuses
  extraction + matching); it re-uses the shared FDR emission helpers
  to keep telemetry byte-identical across strategies. lightglue_runtime
  parameter accepted by factory but discarded (AC-special-1).
- All three consume the shared LightGlueRuntime / RansacFilter /
  RollingHealthWindow helpers; no helper forks. InferenceRuntimeCut
  consumer-side Protocol added per AZ-507.

C3.5 (AZ-349):
- AdHoPRefiner implements the <= conditional gate, runs the OrthoLoC
  AdHoP TRT engine over best-candidate correspondences, re-runs RANSAC
  on the perspective-preconditioned set, and emits an enriched
  MatchResult with refinement_label="adhop".
- Invariant 4 passthrough fall-through: any RefinerBackboneError (TRT
  failure, OOM, NaN, bad shape) is caught, logged ERROR, FDR-emitted
  with error: true, and converted to passthrough that still counts
  against the rolling invocation-rate window. MemoryError and other
  non-listed exceptions propagate by design (AC-5 closed-set
  semantics).
- Rolling 60-s invocation-rate window + rate-limited WARN log
  (configurable via ratelimited_warn_window_ns; default 60 s).

Shared changes:
- C3MatcherConfig + C3_5RefinerConfig extended with the new
  weights/threshold/window fields.
- matcher_factory + refiner_factory optionally forward clock +
  fdr_client to the strategy's create(); backward-compatible.
- fdr_client.records registers five new kinds: matcher.frame_done,
  matcher.backbone_error, matcher.insufficient_inliers,
  matcher.all_failed, refiner.frame_done.

Tests: 66 new (43 C3 parametrised + 23 AdHoP) covering 47/47 ACs;
focused suite green; full project test suite green except for one
pre-existing flaky CLI cold-start timing test unrelated to this batch.

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

src/gps_denied_onboard/fdr_client/records.py

@@ -376,6 +376,95 @@ KNOWN_PAYLOAD_KEYS: Final[dict[str, frozenset[str]]] = {
             "error_message",
         }
     ),
+    # AZ-345 / AZ-346 / AZ-347 / E-C3: emitted by each concrete
+    # ``CrossDomainMatcher`` on every ``match(...)`` call that produces
+    # a ``MatchResult`` (i.e. NOT the all-failed / below-threshold
+    # paths — those use ``matcher.all_failed`` / ``matcher.insufficient_inliers``).
+    # One record per frame regardless of ``candidates_dropped``.
+    # ``best_tile_id`` is the canonical
+    # ``[zoom_level, lat_deg, lon_deg]`` triple from
+    # :class:`MatchResult.per_candidate[best_candidate_idx].tile_id`.
+    "matcher.frame_done": frozenset(
+        {
+            "frame_id",
+            "matcher_label",
+            "candidates_input",
+            "candidates_dropped",
+            "best_inlier_count",
+            "best_residual_px",
+            "best_tile_id",
+        }
+    ),
+    # AZ-345 / AZ-346 / AZ-347 / E-C3: emitted per dropped candidate
+    # when a backbone forward (DISK / ALIKED / LightGlue / XFeat)
+    # fails inside the per-candidate loop (INV-4 drop-and-continue).
+    # ``phase`` is the backbone stage that raised — one of
+    # ``"query_extract"``, ``"tile_decode"``, ``"tile_extract"``,
+    # ``"lightglue_match"``, ``"xfeat_forward"``, ``"ransac"``.
+    "matcher.backbone_error": frozenset(
+        {
+            "frame_id",
+            "matcher_label",
+            "tile_id",
+            "phase",
+            "error_type",
+            "error_message",
+        }
+    ),
+    # AZ-345 / AZ-346 / AZ-347 / E-C3: emitted when the per-candidate
+    # loop completed with ≥1 survivor but the best survivor's
+    # inlier_count is below ``config.matcher.min_inliers_threshold``.
+    # ``max_inlier_count`` is the highest count observed across
+    # surviving candidates (0 if the survivors list is empty after
+    # the zero-inlier filter).
+    "matcher.insufficient_inliers": frozenset(
+        {
+            "frame_id",
+            "matcher_label",
+            "candidates_input",
+            "candidates_dropped",
+            "max_inlier_count",
+        }
+    ),
+    # AZ-345 / AZ-346 / AZ-347 / E-C3: emitted when every candidate
+    # in the rerank result failed (backbone error, zero correspondences,
+    # or empty rerank input).
+    "matcher.all_failed": frozenset(
+        {
+            "frame_id",
+            "matcher_label",
+            "candidates_input",
+            "candidates_dropped",
+        }
+    ),
+    # AZ-349 / E-C3.5: emitted by every ``refine_if_needed`` call
+    # regardless of gate decision (passthrough, AdHoP-success,
+    # AdHoP-fall-through). One record per frame.
+    # ``was_invoked`` distinguishes "AdHoP entered the refinement
+    # procedure" (True) from "gate decided passthrough" (False).
+    # ``refinement_label`` is ``"adhop"`` on success and
+    # ``"passthrough"`` on both gate-passthrough and AdHoP backbone
+    # fall-through; readers cross-check with ``was_invoked`` and the
+    # optional ``error`` flag to disambiguate.
+    # ``pre_residual_px`` / ``post_residual_px`` and
+    # ``inlier_count_before`` / ``inlier_count_after`` are populated
+    # only on the AdHoP-success path (the passthrough paths leave
+    # ``post_residual_px == pre_residual_px`` and the inlier counts
+    # equal). ``error`` is ``True`` only on the AdHoP fall-through
+    # path; default-absent otherwise.
+    "refiner.frame_done": frozenset(
+        {
+            "frame_id",
+            "was_invoked",
+            "refinement_label",
+            "refinement_added_latency_ms",
+            "pre_residual_px",
+            "post_residual_px",
+            "inlier_count_before",
+            "inlier_count_after",
+            "error",
+        }
+    ),
 }
 
 KNOWN_KINDS: Final[frozenset[str]] = frozenset(KNOWN_PAYLOAD_KEYS.keys())