[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 <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-19 08:56:04 +03:00
parent eaf2f47f69
commit 5c4d129f80
10 changed files with 856 additions and 19 deletions
@@ -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.
@@ -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.
+2 -2
View File
@@ -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
@@ -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_<variant>=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(
@@ -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:
@@ -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()
@@ -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:
@@ -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.
@@ -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