From 5c4d129f80a3c85720dfd324ffb70a81f430545c Mon Sep 17 00:00:00 2001 From: Oleksandr Bezdieniezhnykh Date: Tue, 19 May 2026 08:56:04 +0300 Subject: [PATCH] [AZ-622] Phase D: build_pre_constructed seeds c3 GPU runtimes build_pre_constructed now populates c3_lightglue_runtime (LightGlueRuntime) + c3_feature_extractor (FeatureExtractor) on top of AZ-619/620/621. Strategy-specific BUILD_MATCHER_* flag mismatch raises AirborneBootstrapError naming the missing flag and the c3_matcher consumer; the c7 InferenceRuntime built earlier in the bootstrap is reused as the engine source so no double-build at this layer. C3MatcherConfig gains optional lightglue_weights_path: Path | None for the operator's deployment config; production main() (AZ-624) populates it. Real LightGlue inference correctness is verified by AZ-624's Jetson AC-5 run per the AZ-622 Tier-2 Note. Phase tests for AZ-619/620/621 gain an autouse _stub_c3_matcher_builders fixture so additivity assertions remain valid as the bootstrap grows. Code review: PASS_WITH_WARNINGS (3 Low: signature drift from spec, _is_build_flag_on duplication across 3 runtime_root modules, and BuildConfig literal mirrored with per-strategy build configs). All deferred to future hygiene PBIs. Co-authored-by: Cursor --- ...622_pre_constructed_phase_d_c3_runtimes.md | 0 .../batch_93_cycle1_report.md | 80 +++++ .../reviews/batch_93_review.md | 162 ++++++++++ _docs/_autodev_state.md | 4 +- .../components/c3_matcher/config.py | 18 +- .../runtime_root/airborne_bootstrap.py | 255 ++++++++++++++- .../test_az619_pre_constructed_phase_a.py | 18 ++ .../test_az620_pre_constructed_phase_b.py | 21 ++ .../test_az621_pre_constructed_phase_c.py | 21 ++ .../test_az622_pre_constructed_phase_d.py | 296 ++++++++++++++++++ 10 files changed, 856 insertions(+), 19 deletions(-) rename _docs/02_tasks/{todo => done}/AZ-622_pre_constructed_phase_d_c3_runtimes.md (100%) create mode 100644 _docs/03_implementation/batch_93_cycle1_report.md create mode 100644 _docs/03_implementation/reviews/batch_93_review.md create mode 100644 tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py diff --git a/_docs/02_tasks/todo/AZ-622_pre_constructed_phase_d_c3_runtimes.md b/_docs/02_tasks/done/AZ-622_pre_constructed_phase_d_c3_runtimes.md similarity index 100% rename from _docs/02_tasks/todo/AZ-622_pre_constructed_phase_d_c3_runtimes.md rename to _docs/02_tasks/done/AZ-622_pre_constructed_phase_d_c3_runtimes.md diff --git a/_docs/03_implementation/batch_93_cycle1_report.md b/_docs/03_implementation/batch_93_cycle1_report.md new file mode 100644 index 0000000..d259fc6 --- /dev/null +++ b/_docs/03_implementation/batch_93_cycle1_report.md @@ -0,0 +1,80 @@ +# Batch Report + +**Batch**: 93 +**Tasks**: AZ-622 (Phase D: build_pre_constructed seeds c3_lightglue_runtime + c3_feature_extractor) +**Date**: 2026-05-19 +**Cycle**: 1 + +## Task Results + +| Task | Status | Files Modified | Tests | AC Coverage | Issues | +|------|--------|----------------|-------|-------------|--------| +| AZ-622_pre_constructed_phase_d_c3_runtimes | Done | 6 files | 17 passed | 3/3 ACs covered | 0 blocking | + +## Files Changed + +### Production +- `src/gps_denied_onboard/components/c3_matcher/config.py` — added optional `lightglue_weights_path: Path | None = None`; extended `__post_init__` Path/None validator; expanded module docstring with the AZ-622 / Phase D rationale. +- `src/gps_denied_onboard/runtime_root/airborne_bootstrap.py` — new public constant `C3_MATCHER_BUILD_FLAGS`; new internal helpers `_resolve_c3_matcher_strategy`, `_is_build_flag_on`, `_load_lightglue_engine_handle`, `_build_c3_lightglue_runtime`, `_build_c3_feature_extractor`; `build_pre_constructed` refactored to step-by-step build so the just-built `c7_inference` flows into the LightGlue loader without a double-build. + +### Tests +- `tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py` (NEW, 6 tests): + - `test_ac_622_1_adds_c3_lightglue_runtime_and_c3_feature_extractor` — AC-622.1. + - `test_ac_622_2_build_flag_off_with_configured_strategy_raises_named_error` — AC-622.2 (DISK). + - `test_ac_622_2_build_flag_off_with_aliked_strategy_names_aliked_flag` — AC-622.2 (ALIKED, per-strategy specificity). + - `test_ac_622_2_default_config_no_c3_matcher_block_still_raises` — AC-622.2 defence-in-depth. + - `test_ac_622_2_lightglue_engine_load_failure_wraps_runtime_error` — AC-622.2 cause-chain wrap. + - `test_lightglue_runtime_uses_c7_inference_from_pre_constructed` — additive identity-share invariant (no double-build of InferenceRuntime). +- `tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py` — added autouse `_stub_c3_matcher_builders`. +- `tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py` — added autouse `_stub_c3_matcher_builders`. +- `tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py` — added autouse `_stub_c3_matcher_builders`. + +## AC Test Coverage: 3 of 3 covered + +| AC | Test | Status | +|----|------|--------| +| AC-622.1 | `test_ac_622_1_adds_c3_lightglue_runtime_and_c3_feature_extractor` | Covered | +| AC-622.2 | `test_ac_622_2_build_flag_off_with_configured_strategy_raises_named_error` (+3 variants) | Covered | +| AC-622.3 | File `tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py` exists | Covered | + +## Code Review Verdict: PASS_WITH_WARNINGS + +Full report: `_docs/03_implementation/reviews/batch_93_review.md`. Three Low findings: + +1. **F1 (Low / Spec)** — `_build_c3_lightglue_runtime` signature is `(config, *, inference_runtime)` not the spec's literal `(config)` form. Justified by the additivity invariant + AZ-621's no-double-build rule; documented in docstrings. +2. **F2 (Low / Maintainability)** — `_is_build_flag_on` duplicated across `airborne_bootstrap`, `matcher_factory`, and `vpr_factory` (3 call sites now). Defer to a future hygiene PBI (~2pt). +3. **F3 (Low / Maintainability)** — `BuildConfig(FP16, 512MB, …)` literal duplicated with per-strategy `_build_*_build_config` helpers. Defer until FP16 becomes a config-driven knob. + +No Critical / High findings. Auto-fix not invoked. + +## Auto-Fix Attempts: 0 + +## Stuck Agents: None + +## Test Run Summary + +- Targeted test set (AZ-619/620/621/622): **17 passed** in 5.83s. +- Regression check (`tests/unit/runtime_root/` + `tests/unit/c3_matcher/`): **108 passed** in 3.89s. +- Adjacent regression check (`tests/unit/c3_5_adhop/test_az349_adhop_refiner.py`, the only other consumer of `C3MatcherConfig`): **23 passed** in 1.09s. + +## Tier-2 / Deferred Work + +Per the AZ-622 ## Tier-2 Note, real LightGlue inference correctness is verified by AZ-624's Jetson AC-5 run; this batch only exercises: + +- BUILD-flag matrix lookup (in-process, env-var driven). +- Error-message contract (operator-actionable strings naming flag + consuming component slug). +- The `_load_lightglue_engine_handle` heavy seam via monkeypatch sentinels. + +The production path of `_load_lightglue_engine_handle` (read `block.lightglue_weights_path`, compile via C7 `InferenceRuntime`, deserialise into `EngineHandle`) is implemented as real code (not a stub) and will be exercised end-to-end at AZ-624's Jetson tier-2 e2e gate. Operator's deployment config must populate `c3_matcher.lightglue_weights_path` for the airborne binary to start. + +## Spec / Code Naming Discrepancy (Informational, no finding) + +The AZ-622 task spec § AC-622.2 example uses the flag name `BUILD_C3_MATCHER_DISK_LIGHTGLUE`, but the actual production flag matrix in `matcher_factory._STRATEGY_TO_BUILD_FLAG` uses the older `BUILD_MATCHER_*` family (`BUILD_MATCHER_DISK_LIGHTGLUE`, `BUILD_MATCHER_ALIKED_LIGHTGLUE`, `BUILD_MATCHER_XFEAT`). The implementation reuses the actual existing flags (per the constraint "MUST reuse the existing per-strategy `BUILD_C3_MATCHER_*` matrix"); the spec's flag-name typo is captured in the `C3_MATCHER_BUILD_FLAGS` docstring so future readers don't get confused. No change to the spec required — the constraint's *intent* (reuse the existing matrix, no new flags) is honored. + +## Next Batch + +- **Batch 94**: AZ-623 (Phase E: build_pre_constructed seeds c282_ransac_filter + c5 helpers + c5_isam2_graph_handle) — 3pt. +- **Then**: AZ-624 (Phase F: wire main() + AC-1..AC-5 verification incl. Jetson tier-2) — 2pt. +- **Cumulative review window**: next due at batch 96 (K=3 from last cumulative review at 88-92). + +After AZ-624 lands, the AZ-618 umbrella's AC-1..AC-5 become exercisable end-to-end; the Jetson tier-2 gate that sent the flow back to Step 7 (per `_docs/LESSONS.md` 2026-05-18) becomes runnable again. diff --git a/_docs/03_implementation/reviews/batch_93_review.md b/_docs/03_implementation/reviews/batch_93_review.md new file mode 100644 index 0000000..30e28d2 --- /dev/null +++ b/_docs/03_implementation/reviews/batch_93_review.md @@ -0,0 +1,162 @@ +# Code Review Report — Batch 93 + +**Batch**: 93 +**Tasks**: AZ-622 (Phase D: build_pre_constructed seeds c3_lightglue_runtime + c3_feature_extractor) +**Date**: 2026-05-19 +**Verdict**: PASS_WITH_WARNINGS +**Reviewer**: autodev / implement skill Step 9 +**Cycle**: 1 + +## Scope + +Files changed (per `git status`): + +- `src/gps_denied_onboard/components/c3_matcher/config.py` — added optional `lightglue_weights_path: Path | None = None` field; extended `__post_init__` Path/None validator; expanded module docstring. +- `src/gps_denied_onboard/runtime_root/airborne_bootstrap.py` — new public constant `C3_MATCHER_BUILD_FLAGS`; new internal helpers `_resolve_c3_matcher_strategy`, `_is_build_flag_on`, `_load_lightglue_engine_handle`, `_build_c3_lightglue_runtime`, `_build_c3_feature_extractor`; refactored `build_pre_constructed` to step-by-step build so the just-built `c7_inference` flows into the LightGlue loader. +- `tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py` — added autouse `_stub_c3_matcher_builders`. +- `tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py` — added autouse `_stub_c3_matcher_builders`. +- `tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py` — added autouse `_stub_c3_matcher_builders`. +- `tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py` — new file: 6 tests covering AC-622.1, AC-622.2 (4 variants), and an identity-share invariant. + +## Phase 1 — Context Loading + +Read AZ-622 task spec (3pt; deps AZ-619/620/621/278 all in `done/`); umbrella spec AZ-618; matcher_factory's `_STRATEGY_TO_BUILD_FLAG`; LightGlueRuntime helper contract; OpenCvOrbExtractor helper docstring; existing AZ-619/620/621 test patterns. Confirmed: + +- AC-622.1 = adds 2 keys on top of AZ-619..AZ-621; tests stub the heavy seam. +- AC-622.2 = BUILD-flag mismatch surfaces clear `AirborneBootstrapError` naming the flag + consumer. +- AC-622.3 = test file exists at the documented path. +- Tier-2 Note = real LightGlue inference is verified at AZ-624 Jetson AC-5. + +## Phase 2 — Spec Compliance + +| AC | Test | Status | +|----|------|--------| +| AC-622.1 | `test_ac_622_1_adds_c3_lightglue_runtime_and_c3_feature_extractor` | Covered | +| AC-622.2 | `test_ac_622_2_build_flag_off_with_configured_strategy_raises_named_error` (+ ALIKED variant + defence-in-depth + cause-chain wrap) | Covered | +| AC-622.3 | File `tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py` exists | Covered | + +Constraints check: + +- **MUST NOT introduce new `BUILD_*` env flags** — PASS. The new `C3_MATCHER_BUILD_FLAGS` constant is a *consumer-side mirror* of the existing `matcher_factory._STRATEGY_TO_BUILD_FLAG` (`BUILD_MATCHER_DISK_LIGHTGLUE` / `BUILD_MATCHER_ALIKED_LIGHTGLUE` / `BUILD_MATCHER_XFEAT`). No new env var introduced. +- **MUST reuse the existing per-strategy `BUILD_C3_MATCHER_*` matrix** — PASS in spirit. The actual production matrix is named `BUILD_MATCHER_*`, not `BUILD_C3_MATCHER_*` (the spec author's typo); the docstring of `C3_MATCHER_BUILD_FLAGS` calls this out so future readers don't get confused. See Finding F1 below. +- **MUST be additive on top of AZ-619..AZ-621** — PASS. `build_pre_constructed`'s step-by-step build preserves every prior phase's key; the additivity test in `test_az619_*.py::test_phase_a_keys_remain_present_under_az620_additivity` continues to pass with the new builders in scope. +- **The cross-component identity-share assertion (one instance shared across C3 + C2.5 in the actual graph) is verified at AZ-624** — Honored. The AZ-622 unit tests verify the LightGlueRuntime instance is constructed once per `build_pre_constructed` call; the wrapper-layer identity-share is left to AZ-624 per the task's Excluded section. + +Spec drift surfaced as findings: + +- **F1 (Low / Spec)** — see Findings section. + +## Phase 3 — Code Quality + +- **SOLID**: each new function has a single responsibility (resolve strategy, check flag, load engine, build runtime, build extractor, top-level assemble). No god-method introduced. +- **Error handling**: every failure path produces an `AirborneBootstrapError` with three operator-actionable pieces (missing key, gating flag, consuming component) plus a remediation hint, matching the AZ-618 NFR contract. `RuntimeNotAvailableError` is preserved via `raise … from exc` so the upstream stack is recoverable. +- **Naming**: `_resolve_c3_matcher_strategy`, `_load_lightglue_engine_handle`, `_build_c3_lightglue_runtime`, `_build_c3_feature_extractor` — all kebab-pattern consistent with prior phases (`_build_c6_descriptor_index`, `_build_c7_inference`). +- **Complexity**: longest new function is `_build_c3_lightglue_runtime` at ~40 lines including docstring; cyclomatic complexity ≤ 4 per function. +- **DRY**: `_is_build_flag_on` is a 2-line duplicate of `matcher_factory._is_build_flag_on`. See Finding F2. +- **Test quality**: every test follows the Arrange/Act/Assert convention with comment markers; assertions check identity (`is`), type (`isinstance`), key membership, exception type, exception message content, and cause-chain — NOT just "no error thrown". +- **Dead code**: no unused imports, no unreachable branches. The `del config` in `_build_c3_feature_extractor` is intentional (keeps the signature consistent with sibling builders). + +## Phase 4 — Security Quick-Scan + +- No SQL / command injection (no string-built queries, no `subprocess`, no `eval`/`exec`). +- No hardcoded secrets, API keys, or paths to credential stores. +- Input validation: `_load_lightglue_engine_handle` validates `weights_path is None` before calling `compile_engine`; the caller wraps any heavy-load failure into a structured error. +- No sensitive data in error messages (path is referenced by name, not value). +- No insecure deserialization — `deserialize_engine` is the existing C7 path that ships its own engine-gate validation (per AZ-301). + +No security findings. + +## Phase 5 — Performance Scan + +- `build_pre_constructed` is a one-shot bootstrap call at process start; no hot-path concerns. +- `_load_lightglue_engine_handle` is intentionally heavy (engine compile + deserialise) but is invoked once per process. The c7 `InferenceRuntime` is built once and reused for the LightGlue load — no double-build at this layer. +- No O(n²) algorithms; no unbounded data fetching; no blocking I/O in async contexts (the bootstrap is synchronous by design). + +No performance findings. + +## Phase 6 — Cross-Task Consistency + +- The new keys integrate with the existing `_c3_matcher_wrapper` (line 257 of `airborne_bootstrap.py`) which already extracts `c3_lightglue_runtime` from `constructed`. No signature collision. +- The `_c2_5_rerank_wrapper` (line 232) extracts both `c3_lightglue_runtime` and `c3_feature_extractor` — both keys are now populated, matching the wrapper's expectation. +- Prior-phase tests (AZ-619/620/621) now stub the new C3 builders via the same autouse pattern they already use for C6/C7. The pattern is uniform across all four phase test files. + +## Phase 7 — Architecture Compliance + +- **Layer direction**: `runtime_root.airborne_bootstrap` imports from `helpers/lightglue_runtime` (L1) and `helpers/feature_extractor` (L1). Allowed per `module-layout.md` rule 6 (composition root may import any L1 helper). PASS. +- **Public API respect**: `LightGlueRuntime` is exported from `helpers/lightglue_runtime.py` `__all__`; `OpenCvOrbExtractor` is exported from `helpers/feature_extractor.py` `__all__`. Both imports go through documented Public API. PASS. +- **No new cyclic module dependencies**: dependency chain `runtime_root.airborne_bootstrap → helpers/lightglue_runtime → _types/manifests + _types/matching` and `runtime_root.airborne_bootstrap → helpers/feature_extractor → _types/matching`. No reverse import. PASS. +- **Duplicate symbols across components**: `_is_build_flag_on` exists in both `airborne_bootstrap.py` and `matcher_factory.py`. Both are *private* (underscore-prefixed) and live in the same `runtime_root/` subpackage — not a cross-component duplication. Severity Low; see Finding F2. +- **Cross-cutting concerns not locally re-implemented**: the `BuildConfig(precision=PrecisionMode.FP16, workspace_mb=512, …)` constant in `_load_lightglue_engine_handle` mirrors the per-strategy `_build_disk_build_config` / `_build_aliked_build_config` shape in C3 strategy modules. Severity Low; see Finding F3. + +No Critical or High Architecture findings. + +## Findings + +| # | Severity | Category | File:Line | Title | +|---|----------|----------|-----------|-------| +| 1 | Low | Spec | `airborne_bootstrap.py:545` | `_build_c3_lightglue_runtime` signature differs from spec's single-arg form | +| 2 | Low | Maintainability | `airborne_bootstrap.py` + `matcher_factory.py` | `_is_build_flag_on` duplicated across two runtime_root modules | +| 3 | Low | Maintainability | `airborne_bootstrap.py:_load_lightglue_engine_handle` | `BuildConfig(precision=FP16, workspace_mb=512, …)` mirrors per-strategy `_build_*_build_config` constants | + +### F1 — `_build_c3_lightglue_runtime` signature differs from spec's single-arg form (Low / Spec) + +- **Location**: `src/gps_denied_onboard/runtime_root/airborne_bootstrap.py` (`_build_c3_lightglue_runtime(config: Config, *, inference_runtime: InferenceRuntime) -> LightGlueRuntime`). +- **Description**: AZ-622 task spec § Scope.Included calls out internal builders as `_build_c3_lightglue_runtime(config)` and `_build_c3_feature_extractor(config)` — single-arg. The implementation adds an `inference_runtime` keyword-only argument so the just-built `pre_constructed['c7_inference']` can flow through without a double-build. +- **Why this is the right interpretation**: AZ-622 also constrains "MUST be additive on top of AZ-619..AZ-621" and AZ-621's NFR guarantees one inference-runtime build per process. Re-calling `build_inference_runtime` from inside `_build_c3_lightglue_runtime` to satisfy the literal single-arg form would violate the additivity-and-no-double-build invariant. The kwarg keeps the surface honest about the dependency. +- **Mitigation**: the divergence is documented inline in `_build_c3_lightglue_runtime`'s docstring and in `build_pre_constructed`'s docstring (line referencing "the C7 InferenceRuntime built for the c7_inference slot is reused as the engine source for the LightGlue matcher load"). +- **Suggestion**: none — the implementation is the more correct shape. If a future spec author updates the AZ-622 task file post-batch, fold the kwarg into the spec; otherwise leave as-is. +- **Task reference**: AZ-622. + +### F2 — `_is_build_flag_on` duplicated across `airborne_bootstrap.py` + `matcher_factory.py` (Low / Maintainability) + +- **Location**: `src/gps_denied_onboard/runtime_root/airborne_bootstrap.py` + `src/gps_denied_onboard/runtime_root/matcher_factory.py` (both define the same 2-line predicate). +- **Description**: Both `airborne_bootstrap` and `matcher_factory` now ship the same `_is_build_flag_on(flag_name: str) -> bool` predicate. The bootstrap intentionally avoids depending on `matcher_factory`'s private symbol so a future reorganisation of the matcher factory cannot break the bootstrap silently. +- **Severity rationale**: the duplication is short (2 lines + docstring), private to a single subpackage, and prevents private-symbol coupling. Lifting it into a `runtime_root/_build_flags.py` (or `helpers/build_flags.py`) helper would be a hygiene improvement but not a correctness issue. Same pattern exists in `vpr_factory.py` (`vpr_factory._is_build_flag_on`) — at least 3 callers now duplicate the predicate. +- **Suggestion**: add a follow-up hygiene PBI (sized 2 points) to extract `is_build_flag_on(flag_name: str) -> bool` into a shared helper module under `runtime_root/` (or `helpers/`). Defer to a future cumulative-review window. +- **Task reference**: AZ-622, but the duplication predates this batch. + +### F3 — `BuildConfig` literal duplicated with per-strategy build-config helpers (Low / Maintainability) + +- **Location**: `src/gps_denied_onboard/runtime_root/airborne_bootstrap.py::_load_lightglue_engine_handle`. +- **Description**: `_load_lightglue_engine_handle` constructs `BuildConfig(precision=PrecisionMode.FP16, workspace_mb=512, calibration_dataset=None, optimization_profiles=())` inline. The same shape exists in `c3_matcher/disk_lightglue.py::_build_disk_build_config()` and `c3_matcher/aliked_lightglue.py::_build_aliked_build_config()`. If FP16 ever needs to be a config-driven knob (Tier-2 work), three places will drift. +- **Severity rationale**: only matters when the build config becomes config-driven; today both per-strategy constants are literal-equal and the LightGlue engine is loaded with the same FP16 precision as DISK / ALIKED. Lifting into a shared helper would couple the bootstrap's internals to component-internal symbols — exactly the AZ-507 pattern we're trying to keep out of `runtime_root/`. +- **Suggestion**: leave as-is for AZ-622. When the BuildConfig matrix becomes config-driven (likely a 2027 Tier-2 task), introduce a cross-cutting `helpers/build_config_for_engine.py` and migrate all three call sites at once. +- **Task reference**: AZ-622, but the duplication predates this batch. + +## Verdict Logic + +- 0 Critical findings → not FAIL. +- 0 High findings → not FAIL. +- 3 Low findings → **PASS_WITH_WARNINGS**. + +## Auto-Fix Eligibility + +| Finding | Severity | Category | Auto-fix eligible? | +|---------|----------|----------|--------------------| +| F1 | Low | Spec | No — divergence is the more correct shape; spec needs updating | +| F2 | Low | Maintainability | Defer — hygiene PBI for future cumulative-review window | +| F3 | Low | Maintainability | Defer — wait for FP16-as-config knob requirement | + +No findings escalate. Proceed to commit (Step 11). + +## Test Verification + +``` +pytest tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py \ + tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py \ + tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py \ + tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py -v +=> 17 passed in 5.83s +``` + +Broader regression check (runtime_root + c3_matcher + c3_5_adhop): + +``` +pytest tests/unit/runtime_root/ tests/unit/c3_matcher/ -x --timeout=60 +=> 108 passed in 3.89s + +pytest tests/unit/c3_5_adhop/test_az349_adhop_refiner.py +=> 23 passed in 1.09s +``` + +No regression introduced by the C3MatcherConfig schema extension. diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index 89ec432..c8aa5bd 100644 --- a/_docs/_autodev_state.md +++ b/_docs/_autodev_state.md @@ -8,8 +8,8 @@ status: in_progress sub_step: phase: 16 name: batch-loop - detail: "cumulative review 88-92 PASS_WITH_WARNINGS. Next: batch 93 = AZ-622 (Phase D, 3cp)." + detail: "batch 93 done; next: batch 94 = AZ-623 (Phase E, 3cp)" retry_count: 0 cycle: 1 tracker: jira -last_completed_batch: 92 +last_completed_batch: 93 diff --git a/src/gps_denied_onboard/components/c3_matcher/config.py b/src/gps_denied_onboard/components/c3_matcher/config.py index b70b709..8066005 100644 --- a/src/gps_denied_onboard/components/c3_matcher/config.py +++ b/src/gps_denied_onboard/components/c3_matcher/config.py @@ -37,6 +37,16 @@ by C3.5; it lives in :class:`C3_5RefinerConfig` (sibling block) — not duplicated here. ``None`` is allowed as a placeholder for ``BUILD_MATCHER_=OFF`` binaries; the factory rejects ``None`` only for the SELECTED strategy at composition time. + +``lightglue_weights_path`` (AZ-622 / Phase D) points at the LightGlue +*matcher* engine — distinct from the per-strategy DISK / ALIKED +*feature-extractor* engine. The airborne bootstrap +(``runtime_root.airborne_bootstrap.build_pre_constructed``) reads +this field to construct the single shared +:class:`gps_denied_onboard.helpers.lightglue_runtime.LightGlueRuntime` +that C3 + C2.5 both consume (R14 fix; one instance avoids double GPU +memory). ``None`` is allowed; production main() (AZ-624) populates +the path before calling ``build_pre_constructed``. """ from __future__ import annotations @@ -69,6 +79,7 @@ class C3MatcherConfig: disk_weights_path: Path | None = None aliked_weights_path: Path | None = None xfeat_weights_path: Path | None = None + lightglue_weights_path: Path | None = None def __post_init__(self) -> None: if self.strategy not in KNOWN_STRATEGIES: @@ -91,7 +102,12 @@ class C3MatcherConfig: "C3MatcherConfig.ransac_threshold_px must be > 0; " f"got {self.ransac_threshold_px}" ) - for name in ("disk_weights_path", "aliked_weights_path", "xfeat_weights_path"): + for name in ( + "disk_weights_path", + "aliked_weights_path", + "xfeat_weights_path", + "lightglue_weights_path", + ): value = getattr(self, name) if value is not None and not isinstance(value, Path): raise ConfigError( diff --git a/src/gps_denied_onboard/runtime_root/airborne_bootstrap.py b/src/gps_denied_onboard/runtime_root/airborne_bootstrap.py index af6c661..7b423b4 100644 --- a/src/gps_denied_onboard/runtime_root/airborne_bootstrap.py +++ b/src/gps_denied_onboard/runtime_root/airborne_bootstrap.py @@ -55,6 +55,8 @@ from typing import TYPE_CHECKING, Any, Final from gps_denied_onboard.clock.wall_clock import WallClock from gps_denied_onboard.fdr_client.client import make_fdr_client +from gps_denied_onboard.helpers.feature_extractor import OpenCvOrbExtractor +from gps_denied_onboard.helpers.lightglue_runtime import LightGlueRuntime from gps_denied_onboard.runtime_root import register_strategy from gps_denied_onboard.runtime_root.errors import RuntimeNotAvailableError from gps_denied_onboard.runtime_root.inference_factory import build_inference_runtime @@ -71,11 +73,15 @@ from gps_denied_onboard.runtime_root.vio_factory import build_vio_strategy from gps_denied_onboard.runtime_root.vpr_factory import build_vpr_strategy if TYPE_CHECKING: + from gps_denied_onboard._types.manifests import EngineHandle + from gps_denied_onboard.components.c7_inference import InferenceRuntime from gps_denied_onboard.config import Config + from gps_denied_onboard.helpers.feature_extractor import FeatureExtractor __all__ = [ "AIRBORNE_MAIN_PRODUCER_ID", "AIRBORNE_REQUIRED_PRE_CONSTRUCTED_KEYS", + "C3_MATCHER_BUILD_FLAGS", "C7_AIRBORNE_BUILD_FLAGS", "FAISS_BUILD_FLAG", "AirborneBootstrapError", @@ -114,6 +120,33 @@ flag would unblock the bootstrap with a different runtime selection. """ +C3_MATCHER_BUILD_FLAGS: Final[Mapping[str, str]] = { + "disk_lightglue": "BUILD_MATCHER_DISK_LIGHTGLUE", + "aliked_lightglue": "BUILD_MATCHER_ALIKED_LIGHTGLUE", + "xfeat": "BUILD_MATCHER_XFEAT", +} +"""Per-strategy ``BUILD_MATCHER_*`` flag matrix consumed by the airborne +LightGlue-runtime builder (AZ-622 / Phase D). + +Mirrors :data:`gps_denied_onboard.runtime_root.matcher_factory.\ +_STRATEGY_TO_BUILD_FLAG` verbatim — both this constant and the matcher +factory's table read the same compile-time flags. ANY mutation of this +matrix MUST be mirrored in ``matcher_factory._STRATEGY_TO_BUILD_FLAG`` +(and vice versa). + +Surfaced here so :func:`_build_c3_lightglue_runtime` can name the +gating flag in an :class:`AirborneBootstrapError` (AC-622.2) when the +configured C3 matcher strategy's flag is OFF in this binary. + +Note on flag naming: AZ-622's task spec uses the name +``BUILD_C3_MATCHER_DISK_LIGHTGLUE`` informally, but the actual +production flag matrix is the older ``BUILD_MATCHER_*`` family +(``matcher_factory._STRATEGY_TO_BUILD_FLAG``). Reusing those flags is +the spirit of the AZ-622 ``MUST reuse the existing per-strategy +BUILD_C3_MATCHER_* matrix`` constraint. +""" + + AIRBORNE_MAIN_PRODUCER_ID: Final[str] = "airborne_main" """Producer ID for the per-binary shared FdrClient placed under ``pre_constructed['c13_fdr']``. @@ -542,25 +575,208 @@ def _build_c7_inference(config: Config) -> Any: ) from exc +def _resolve_c3_matcher_strategy(config: Config) -> str: + """Return the configured C3 matcher strategy, defaulting to disk_lightglue. + + Reuses :class:`gps_denied_onboard.components.c3_matcher.C3MatcherConfig`'s + own default ``"disk_lightglue"`` when ``config.components`` carries no + ``c3_matcher`` block (early-bootstrap tests with bare ``Config()``). + """ + block = config.components.get("c3_matcher") + if block is None: + return "disk_lightglue" + return getattr(block, "strategy", "disk_lightglue") + + +def _is_build_flag_on(flag_name: str) -> bool: + """Read a compile-time ``BUILD_*`` flag from the environment. + + Mirrors the same predicate used by + :func:`gps_denied_onboard.runtime_root.matcher_factory.\ +_is_build_flag_on` — ``ON`` / ``1`` / ``true`` / ``yes`` (case-insensitive) + is ON; everything else (including unset) is OFF. Defined locally so the + bootstrap does not depend on the matcher-factory's private helper. + """ + raw = os.environ.get(flag_name, "") + return raw.strip().lower() in {"on", "1", "true", "yes"} + + +def _load_lightglue_engine_handle( + config: Config, inference_runtime: InferenceRuntime +) -> EngineHandle: + """Production loader for the shared LightGlue matcher engine. + + Reads ``config.components['c3_matcher'].lightglue_weights_path``, + compiles the engine via the C7 + :class:`InferenceRuntime.compile_engine` (TensorRT or PyTorch-FP16 + per AZ-621), then deserialises it into an opaque + :class:`EngineHandle`. The handle's lifecycle is owned by the + :class:`LightGlueRuntime` instance returned by + :func:`_build_c3_lightglue_runtime`. + + AZ-622 unit tests monkey-patch this function with a sentinel + :class:`EngineHandle`-shaped mock so they can exercise the + LightGlueRuntime wiring without standing up a real GPU + TensorRT + toolchain (per AZ-622 ``Tier-2 Note``: real LightGlue inference + correctness is verified by AZ-624's Jetson AC-5 run). + + Raises: + AirborneBootstrapError: if ``c3_matcher.lightglue_weights_path`` + is ``None`` (the operator-actionable message points at the + production main() wiring task — AZ-624). + RuntimeNotAvailableError: if the underlying + :func:`InferenceRuntime.compile_engine` / + :func:`deserialize_engine` paths fail (caller wraps this + into an :class:`AirborneBootstrapError`). + """ + block = config.components.get("c3_matcher") + weights_path = ( + getattr(block, "lightglue_weights_path", None) if block is not None else None + ) + if weights_path is None: + raise AirborneBootstrapError( + "airborne_bootstrap: cannot construct " + "pre_constructed['c3_lightglue_runtime'] because " + "config.components['c3_matcher'].lightglue_weights_path " + "is None. Production main() (AZ-624) must populate the " + "path to the compiled LightGlue engine before calling " + "build_pre_constructed; tests stub _load_lightglue_engine_handle " + "via monkeypatch." + ) + from gps_denied_onboard._types.inference import BuildConfig, PrecisionMode + + build_config: BuildConfig = BuildConfig( + precision=PrecisionMode.FP16, + workspace_mb=512, + calibration_dataset=None, + optimization_profiles=(), + ) + cache_entry = inference_runtime.compile_engine(weights_path, build_config) + return inference_runtime.deserialize_engine(cache_entry) + + +def _build_c3_lightglue_runtime( + config: Config, *, inference_runtime: InferenceRuntime +) -> LightGlueRuntime: + """Build ``pre_constructed['c3_lightglue_runtime']`` for the airborne binary. + + 1. Resolve the configured C3 matcher strategy (default + ``disk_lightglue``). + 2. Look up the gating flag in :data:`C3_MATCHER_BUILD_FLAGS`. + An unknown strategy or an OFF flag is an + :class:`AirborneBootstrapError` naming the missing flag and + the consuming component slug ``c3_matcher`` (AC-622.2). + 3. Load the LightGlue engine handle via + :func:`_load_lightglue_engine_handle` (the heavy seam unit + tests monkeypatch — see AZ-622 ``Tier-2 Note``). + 4. Wrap the handle in :class:`LightGlueRuntime` and return. + + The returned runtime is the SAME instance that the wrappers for + ``c3_matcher`` and ``c2_5_rerank`` extract from + ``pre_constructed['c3_lightglue_runtime']`` — identity-share is + the structural R14 fix (avoids double GPU memory; AZ-344 AC-10). + The cross-component identity-share assertion is verified at + AZ-624's integration AC, not here. + + Raises: + AirborneBootstrapError: when the configured strategy's + ``BUILD_MATCHER_*`` flag is OFF, when the strategy is + unknown to :data:`C3_MATCHER_BUILD_FLAGS`, or when the + heavy seam fails (the upstream + :class:`RuntimeNotAvailableError` is preserved as + ``__cause__``). + """ + strategy = _resolve_c3_matcher_strategy(config) + flag = C3_MATCHER_BUILD_FLAGS.get(strategy) + if flag is None: + raise AirborneBootstrapError( + f"airborne_bootstrap: cannot construct " + f"pre_constructed['c3_lightglue_runtime'] because " + f"config.components['c3_matcher'].strategy={strategy!r} is " + f"not in the airborne BUILD-flag matrix " + f"{sorted(C3_MATCHER_BUILD_FLAGS.keys())!r}. Consuming " + f"component: c3_matcher. Reconfigure the C3 matcher to " + f"select one of the supported strategies." + ) + if not _is_build_flag_on(flag): + raise AirborneBootstrapError( + f"airborne_bootstrap: cannot construct " + f"pre_constructed['c3_lightglue_runtime'] because the " + f"gating flag {flag}=ON is required for the configured " + f"strategy={strategy!r}, but {flag} is OFF in this binary. " + f"Consuming component: c3_matcher. Set {flag}=ON, or " + f"reconfigure config.components['c3_matcher'].strategy to a " + f"strategy whose BUILD_MATCHER_* flag is ON." + ) + try: + engine_handle = _load_lightglue_engine_handle(config, inference_runtime) + except RuntimeNotAvailableError as exc: + raise AirborneBootstrapError( + f"airborne_bootstrap: cannot construct " + f"pre_constructed['c3_lightglue_runtime'] because the " + f"LightGlue engine load failed for strategy={strategy!r} " + f"(gating flag {flag} is ON). Consuming component: " + f"c3_matcher. Upstream error: {exc}" + ) from exc + return LightGlueRuntime(engine_handle) + + +def _build_c3_feature_extractor(config: Config) -> FeatureExtractor: + """Build ``pre_constructed['c3_feature_extractor']`` for the airborne binary. + + Returns the shared :class:`FeatureExtractor` that C2.5's + :class:`InlierCountReRanker` consumes for both per-frame nav-camera + images and per-candidate tile pixels (per + :class:`AIRBORNE_REQUIRED_PRE_CONSTRUCTED_KEYS`'s ``c2_5_rerank`` + row). The L1 helper module + :mod:`gps_denied_onboard.helpers.feature_extractor` documents + :class:`OpenCvOrbExtractor` as the production-ready airborne + placeholder until the C7 ``InferenceRuntime``-backed DISK / ALIKED + feature extractor lands; AZ-622 wires that placeholder in. + + No ``BUILD_*`` flag check applies here: the C3 matcher's per-strategy + flag matrix gates the *matcher* engine (handled by + :func:`_build_c3_lightglue_runtime`); the *feature extractor* is + consumed by C2.5 (not C3) and is a pure-CPU OpenCV path that has no + compile-time gate of its own. + + The ``config`` argument is accepted for symmetry with the other + bootstrap builders and to keep the door open for a future + config-driven feature-extractor selection (DISK / ALIKED swap-in) + without changing the call site in :func:`build_pre_constructed`. + """ + del config # currently no config knobs; placeholder for future selection + return OpenCvOrbExtractor() + + def build_pre_constructed(config: Config) -> dict[str, Any]: """Build the airborne ``pre_constructed`` dict for :func:`compose_root`. AZ-619 (Phase A) seeded ``c13_fdr`` and ``clock``. AZ-620 (Phase B) added the two C6 storage entries (``c6_descriptor_index`` + - ``c6_tile_store``). AZ-621 (Phase C) adds ``c7_inference`` + ``c6_tile_store``). AZ-621 (Phase C) added ``c7_inference`` (PyTorch FP16 vs. TensorRT, gated by - :data:`C7_AIRBORNE_BUILD_FLAGS`). Phases D..F (AZ-622..AZ-624) will - extend this function to populate the remaining keys in + :data:`C7_AIRBORNE_BUILD_FLAGS`). AZ-622 (Phase D) adds + ``c3_lightglue_runtime`` (single shared + :class:`gps_denied_onboard.helpers.lightglue_runtime.LightGlueRuntime` + instance, gated by :data:`C3_MATCHER_BUILD_FLAGS` per the + configured strategy) + ``c3_feature_extractor`` (the shared + :class:`gps_denied_onboard.helpers.feature_extractor.FeatureExtractor` + used by C2.5). Phases E..F (AZ-623..AZ-624) will extend this + function to populate the remaining keys in :data:`AIRBORNE_REQUIRED_PRE_CONSTRUCTED_KEYS`. Returns a fresh dict on each call. The ``c13_fdr`` instance is cached inside :func:`make_fdr_client` (per-producer cache) so two calls within the same process return dicts where ``pre_constructed['c13_fdr']`` is the SAME object — AC-619.2. ``clock`` is a fresh :class:`WallClock` - each call (stateless; the cache would be a no-op). The C6 + C7 - entries are constructed via the existing :mod:`storage_factory` and - :mod:`inference_factory` builders without additional caching at this - layer. + each call (stateless; the cache would be a no-op). The C6, C7, and C3 + entries are constructed via the existing :mod:`storage_factory`, + :mod:`inference_factory`, and helper modules without additional + caching at this layer; the C7 :class:`InferenceRuntime` built for the + ``c7_inference`` slot is reused as the engine source for the LightGlue + matcher load (AZ-622) so the bootstrap does not double-build the + inference runtime. Replay-mode override: :func:`compose_root` merges ``replay_components`` over ``pre_constructed`` so the :class:`WallClock` here is replaced by @@ -575,16 +791,23 @@ def build_pre_constructed(config: Config) -> dict[str, Any]: runtime is buildable (both ``BUILD_TENSORRT_RUNTIME`` and ``BUILD_PYTORCH_FP16_RUNTIME`` OFF, or the configured runtime's matching flag is OFF) and any configured consumer - requires ``c7_inference``. The message names the consuming - component slug(s) and the relevant gating flag(s). + requires ``c7_inference``; OR if the configured C3 matcher + strategy's :data:`C3_MATCHER_BUILD_FLAGS` flag is OFF (or + the strategy is unknown), or if the LightGlue engine load + fails. The message names the consuming component slug(s) + and the relevant gating flag(s). """ - return { - "c13_fdr": make_fdr_client(AIRBORNE_MAIN_PRODUCER_ID, config), - "clock": WallClock(), - "c6_descriptor_index": _build_c6_descriptor_index(config), - "c6_tile_store": _build_c6_tile_store(config), - "c7_inference": _build_c7_inference(config), - } + constructed: dict[str, Any] = {} + constructed["c13_fdr"] = make_fdr_client(AIRBORNE_MAIN_PRODUCER_ID, config) + constructed["clock"] = WallClock() + constructed["c6_descriptor_index"] = _build_c6_descriptor_index(config) + constructed["c6_tile_store"] = _build_c6_tile_store(config) + constructed["c7_inference"] = _build_c7_inference(config) + constructed["c3_lightglue_runtime"] = _build_c3_lightglue_runtime( + config, inference_runtime=constructed["c7_inference"] + ) + constructed["c3_feature_extractor"] = _build_c3_feature_extractor(config) + return constructed def register_airborne_strategies() -> None: diff --git a/tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py b/tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py index 75d2503..14e30dc 100644 --- a/tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py +++ b/tests/unit/runtime_root/test_az619_pre_constructed_phase_a.py @@ -80,6 +80,24 @@ def _stub_c7_inference_builder(monkeypatch: pytest.MonkeyPatch) -> None: ) +@pytest.fixture(autouse=True) +def _stub_c3_matcher_builders(monkeypatch: pytest.MonkeyPatch) -> None: + # Arrange: stub the AZ-622 Phase D C3 matcher builders so the AZ-619 + # tests stay focused on Phase A. Without this the bare Config() below + # would hit the BUILD_MATCHER_DISK_LIGHTGLUE flag check (typically + # unset in the test env) and raise AirborneBootstrapError before the + # AC-619 keys could be asserted. Sentinels are opaque on purpose — + # AZ-619 assertions never inspect them. + monkeypatch.setattr( + airborne_bootstrap, + "_build_c3_lightglue_runtime", + lambda _config, *, inference_runtime: object(), + ) + monkeypatch.setattr( + airborne_bootstrap, "_build_c3_feature_extractor", lambda _config: object() + ) + + def test_ac_619_1_default_config_seeds_c13_fdr_and_clock() -> None: # Arrange config = Config() diff --git a/tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py b/tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py index 8aa9d7c..b918dc1 100644 --- a/tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py +++ b/tests/unit/runtime_root/test_az620_pre_constructed_phase_b.py @@ -74,6 +74,27 @@ def _stub_c7_inference_builder(monkeypatch: pytest.MonkeyPatch) -> None: ) +@pytest.fixture(autouse=True) +def _stub_c3_matcher_builders(monkeypatch: pytest.MonkeyPatch) -> None: + # Arrange: stub the AZ-622 Phase D C3 matcher builders so AZ-620 + # tests stay focused on the Phase B contract. Without this the + # configs used below would hit the BUILD_MATCHER_DISK_LIGHTGLUE flag + # check (typically unset in the test env) and raise + # AirborneBootstrapError before the AC-620 keys could be asserted. + # Sentinels are opaque on purpose — AZ-620 assertions never inspect + # them. + monkeypatch.setattr( + airborne_bootstrap, + "_build_c3_lightglue_runtime", + lambda _config, *, inference_runtime: MagicMock(name="LightGlueRuntime"), + ) + monkeypatch.setattr( + airborne_bootstrap, + "_build_c3_feature_extractor", + lambda _config: MagicMock(name="FeatureExtractor"), + ) + + def test_ac_620_1_adds_c6_descriptor_index_and_c6_tile_store( monkeypatch: pytest.MonkeyPatch, ) -> None: diff --git a/tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py b/tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py index a88a44a..2aae8ec 100644 --- a/tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py +++ b/tests/unit/runtime_root/test_az621_pre_constructed_phase_c.py @@ -77,6 +77,27 @@ def _stub_c6_builders(monkeypatch: pytest.MonkeyPatch) -> None: ) +@pytest.fixture(autouse=True) +def _stub_c3_matcher_builders(monkeypatch: pytest.MonkeyPatch) -> None: + # Arrange: stub the AZ-622 Phase D C3 matcher builders so AZ-621 + # tests stay focused on the Phase C contract. Without this the + # configs used below would hit the BUILD_MATCHER_DISK_LIGHTGLUE flag + # check (typically unset in the test env) and raise + # AirborneBootstrapError before the AC-621 keys could be asserted. + # Sentinels are opaque on purpose — AZ-621 assertions never inspect + # them. + monkeypatch.setattr( + airborne_bootstrap, + "_build_c3_lightglue_runtime", + lambda _config, *, inference_runtime: MagicMock(name="LightGlueRuntime"), + ) + monkeypatch.setattr( + airborne_bootstrap, + "_build_c3_feature_extractor", + lambda _config: MagicMock(name="FeatureExtractor"), + ) + + def test_ac_621_1_adds_c7_inference(monkeypatch: pytest.MonkeyPatch) -> None: # Arrange: stub build_inference_runtime to a sentinel so we can # assert wiring without standing up real GPU/TensorRT/PyTorch. diff --git a/tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py b/tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py new file mode 100644 index 0000000..a5de7c5 --- /dev/null +++ b/tests/unit/runtime_root/test_az622_pre_constructed_phase_d.py @@ -0,0 +1,296 @@ +"""AZ-622 — Phase D of AZ-618: ``build_pre_constructed`` seeds c3_lightglue_runtime + c3_feature_extractor. + +Verifies the contract at +``_docs/02_tasks/todo/AZ-622_pre_constructed_phase_d_c3_runtimes.md``: + +* AC-622.1: with a default airborne ``Config`` (and the + ``BUILD_MATCHER_DISK_LIGHTGLUE`` flag ON in spirit — here stubbed at + the airborne_bootstrap module boundary), ``build_pre_constructed(config)`` + additionally contains ``c3_lightglue_runtime`` (a + :class:`LightGlueRuntime` instance) AND ``c3_feature_extractor`` (a + :class:`FeatureExtractor` instance) on top of AZ-619 + AZ-620 + AZ-621. +* AC-622.2: when ``BUILD_MATCHER_DISK_LIGHTGLUE=OFF`` AND a config + selects ``c3_matcher.strategy="disk_lightglue"``, ``build_pre_constructed`` + raises :class:`AirborneBootstrapError` whose message names + ``c3_lightglue_runtime`` (the missing key), ``BUILD_MATCHER_DISK_LIGHTGLUE`` + (the gating flag), and ``c3_matcher`` (the consuming component slug). + +AC-622.3 (this file exists with the above tests) is satisfied by the +existence of this module. + +The tests stub the heavy ``_load_lightglue_engine_handle`` seam (AZ-622) +plus the upstream ``_build_c6_*`` (AZ-620) and ``_build_c7_inference`` +(AZ-621) factories at the airborne_bootstrap module boundary — exactly +mirroring the prior phase pattern (see +:mod:`tests.unit.runtime_root.test_az621_pre_constructed_phase_c`). Real +LightGlue inference correctness is verified by AZ-624's Jetson AC-5 run +per the AZ-622 ``Tier-2 Note``. +""" + +from __future__ import annotations + +from collections.abc import Iterator +from dataclasses import dataclass +from pathlib import Path +from unittest.mock import MagicMock + +import pytest + +from gps_denied_onboard.config import Config +from gps_denied_onboard.fdr_client import client as fdr_client_module +from gps_denied_onboard.helpers.feature_extractor import ( + FeatureExtractor, + OpenCvOrbExtractor, +) +from gps_denied_onboard.helpers.lightglue_runtime import LightGlueRuntime +from gps_denied_onboard.runtime_root import airborne_bootstrap +from gps_denied_onboard.runtime_root.airborne_bootstrap import ( + C3_MATCHER_BUILD_FLAGS, + AirborneBootstrapError, + build_pre_constructed, +) + + +@dataclass(frozen=True) +class _C3MatcherBlock: + """Minimal c3_matcher config block — only the fields the tests need.""" + + strategy: str = "disk_lightglue" + lightglue_weights_path: Path | None = None + + +def _make_engine_handle_mock(*, descriptor_dim: int = 128) -> MagicMock: + """Build a mock that satisfies the LightGlueRuntime engine_handle contract. + + The runtime checks ``engine_handle.descriptor_dim`` (must be ``int`` + and ``>= 1``) and stores the handle for later ``forward`` calls. + AZ-622 only exercises construction; tests do not invoke ``forward``. + """ + handle = MagicMock(name="LightGlueEngineHandle") + handle.descriptor_dim = descriptor_dim + return handle + + +@pytest.fixture(autouse=True) +def _isolated_fdr_cache() -> Iterator[None]: + # Arrange: every test starts with an empty FdrClient cache so the + # bootstrap's make_fdr_client call doesn't accidentally pick up a + # stale instance from a prior test in the same process. + fdr_client_module._reset_for_tests() + yield + fdr_client_module._reset_for_tests() + + +@pytest.fixture(autouse=True) +def _stub_c6_and_c7_builders(monkeypatch: pytest.MonkeyPatch) -> None: + # Arrange: stub the AZ-620 (Phase B) C6 builders and the AZ-621 + # (Phase C) C7 inference builder so AZ-622 stays focused on the + # Phase D contract. Sentinels are opaque on purpose — AZ-622 + # assertions never inspect them. + monkeypatch.setattr( + airborne_bootstrap, + "_build_c6_descriptor_index", + lambda _config: MagicMock(name="DescriptorIndex"), + ) + monkeypatch.setattr( + airborne_bootstrap, + "_build_c6_tile_store", + lambda _config: MagicMock(name="TileStore"), + ) + monkeypatch.setattr( + airborne_bootstrap, + "_build_c7_inference", + lambda _config: MagicMock(name="InferenceRuntime"), + ) + + +def test_ac_622_1_adds_c3_lightglue_runtime_and_c3_feature_extractor( + monkeypatch: pytest.MonkeyPatch, +) -> None: + # Arrange: make BUILD_MATCHER_DISK_LIGHTGLUE ON and stub the heavy + # LightGlue engine load with a sentinel handle. Default Config() + # carries no c3_matcher block, so the bootstrap defaults to + # "disk_lightglue" (per _resolve_c3_matcher_strategy). + monkeypatch.setenv("BUILD_MATCHER_DISK_LIGHTGLUE", "ON") + engine_handle = _make_engine_handle_mock(descriptor_dim=128) + monkeypatch.setattr( + airborne_bootstrap, + "_load_lightglue_engine_handle", + lambda _config, _inference_runtime: engine_handle, + ) + config = Config() + + # Act + pre_constructed = build_pre_constructed(config) + + # Assert: AZ-622 keys are present and correctly typed; the + # LightGlueRuntime wraps the stubbed engine handle (identity + # check); the feature extractor satisfies the FeatureExtractor + # Protocol. Prior phase keys are still present (additivity contract). + assert "c3_lightglue_runtime" in pre_constructed + assert "c3_feature_extractor" in pre_constructed + assert isinstance(pre_constructed["c3_lightglue_runtime"], LightGlueRuntime) + assert ( + pre_constructed["c3_lightglue_runtime"].descriptor_dim() + == engine_handle.descriptor_dim + ) + assert isinstance(pre_constructed["c3_feature_extractor"], FeatureExtractor) + assert isinstance(pre_constructed["c3_feature_extractor"], OpenCvOrbExtractor) + assert { + "c13_fdr", + "clock", + "c6_descriptor_index", + "c6_tile_store", + "c7_inference", + }.issubset(pre_constructed.keys()) + + +def test_ac_622_2_build_flag_off_with_configured_strategy_raises_named_error( + monkeypatch: pytest.MonkeyPatch, +) -> None: + # Arrange: BUILD_MATCHER_DISK_LIGHTGLUE OFF (delete to defend against + # a leftover ON from a different test in the same session) AND a + # config that selects strategy="disk_lightglue". The flag check must + # fire BEFORE _load_lightglue_engine_handle is consulted, so we don't + # need to stub the loader for this branch. + monkeypatch.delenv("BUILD_MATCHER_DISK_LIGHTGLUE", raising=False) + config = Config.with_blocks( + c3_matcher=_C3MatcherBlock(strategy="disk_lightglue") + ) + + # Act + Assert + with pytest.raises(AirborneBootstrapError) as excinfo: + build_pre_constructed(config) + + message = str(excinfo.value) + # The missing key, the gating flag, and the consuming component + # slug must ALL appear in the operator-facing message (AZ-622 + # AC-622.2 + AZ-618 NFR "operator-facing error contract"). + assert "c3_lightglue_runtime" in message + expected_flag = C3_MATCHER_BUILD_FLAGS["disk_lightglue"] + assert expected_flag in message, ( + f"{expected_flag!r} missing from error: {message!r}" + ) + assert "c3_matcher" in message + # The flag-OFF branch raises directly — there is no upstream cause to + # preserve (cause-chain preservation is exercised in + # test_ac_622_2_lightglue_engine_load_failure_wraps_runtime_error). + assert excinfo.value.__cause__ is None + + +def test_ac_622_2_build_flag_off_with_aliked_strategy_names_aliked_flag( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Per-strategy flag specificity: aliked_lightglue surfaces ALIKED's flag.""" + # Arrange: ALIKED strategy with its own gating flag OFF. + monkeypatch.delenv("BUILD_MATCHER_ALIKED_LIGHTGLUE", raising=False) + config = Config.with_blocks( + c3_matcher=_C3MatcherBlock(strategy="aliked_lightglue") + ) + + # Act + Assert + with pytest.raises(AirborneBootstrapError) as excinfo: + build_pre_constructed(config) + + message = str(excinfo.value) + assert "c3_lightglue_runtime" in message + assert C3_MATCHER_BUILD_FLAGS["aliked_lightglue"] in message + assert "c3_matcher" in message + # The DISK flag must NOT appear — the message is strategy-specific. + assert C3_MATCHER_BUILD_FLAGS["disk_lightglue"] not in message + + +def test_ac_622_2_default_config_no_c3_matcher_block_still_raises( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Defence-in-depth: even with no c3_matcher block configured, AZ-622 + still fails loudly when the default-strategy flag is OFF. + + Mirrors the AZ-620 / AZ-621 defence-in-depth tests. Silently returning + a dict without ``c3_lightglue_runtime`` would let a downstream caller + misread the state. + """ + # Arrange + monkeypatch.delenv("BUILD_MATCHER_DISK_LIGHTGLUE", raising=False) + config = Config() # empty components, default strategy resolves to disk_lightglue + + # Act + Assert + with pytest.raises(AirborneBootstrapError) as excinfo: + build_pre_constructed(config) + + message = str(excinfo.value) + assert "c3_lightglue_runtime" in message + assert C3_MATCHER_BUILD_FLAGS["disk_lightglue"] in message + assert "c3_matcher" in message + + +def test_ac_622_2_lightglue_engine_load_failure_wraps_runtime_error( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """When the BUILD flag is ON but the engine load itself fails, + ``RuntimeNotAvailableError`` is wrapped into ``AirborneBootstrapError`` + with the cause chain preserved (mirrors AZ-621's wrapping pattern).""" + # Arrange + from gps_denied_onboard.runtime_root.errors import RuntimeNotAvailableError + + monkeypatch.setenv("BUILD_MATCHER_DISK_LIGHTGLUE", "ON") + + def _raise_engine_load_failure(_config: Config, _inference_runtime: object) -> None: + raise RuntimeNotAvailableError( + "InferenceRuntime.deserialize_engine: simulated GPU bind failure" + ) + + monkeypatch.setattr( + airborne_bootstrap, + "_load_lightglue_engine_handle", + _raise_engine_load_failure, + ) + config = Config.with_blocks( + c3_matcher=_C3MatcherBlock(strategy="disk_lightglue") + ) + + # Act + Assert + with pytest.raises(AirborneBootstrapError) as excinfo: + build_pre_constructed(config) + + message = str(excinfo.value) + assert "c3_lightglue_runtime" in message + assert "disk_lightglue" in message + assert "c3_matcher" in message + assert isinstance(excinfo.value.__cause__, RuntimeNotAvailableError) + + +def test_lightglue_runtime_uses_c7_inference_from_pre_constructed( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """The c7 InferenceRuntime built earlier in build_pre_constructed + must be the SAME instance passed into ``_load_lightglue_engine_handle`` + — no double-build of the inference runtime at this layer.""" + # Arrange + monkeypatch.setenv("BUILD_MATCHER_DISK_LIGHTGLUE", "ON") + inference_runtime_sentinel = MagicMock(name="InferenceRuntime") + monkeypatch.setattr( + airborne_bootstrap, + "_build_c7_inference", + lambda _config: inference_runtime_sentinel, + ) + captured: dict[str, object] = {} + + def _capture_loader(config: Config, inference_runtime: object) -> object: + captured["config"] = config + captured["inference_runtime"] = inference_runtime + return _make_engine_handle_mock(descriptor_dim=128) + + monkeypatch.setattr( + airborne_bootstrap, "_load_lightglue_engine_handle", _capture_loader + ) + config = Config() + + # Act + pre_constructed = build_pre_constructed(config) + + # Assert: the loader received the EXACT same InferenceRuntime instance + # placed under pre_constructed['c7_inference'] (identity-share — the + # same single-build-per-bootstrap discipline AZ-621 established). + assert captured["inference_runtime"] is inference_runtime_sentinel + assert pre_constructed["c7_inference"] is inference_runtime_sentinel