[AZ-271] [AZ-276] [AZ-278] [AZ-282] Finish cross-cutting helpers + relax opencv pin

E-CC-HELPERS closes with the three remaining Layer-1 helpers and
E-CC-CONF closes with the env > YAML > defaults precedence test
gate. All four tickets ship with frozen public surfaces, hermetic
unit tests, and no upward (components.*) imports.

* AZ-271 — tests/unit/shared/config/test_precedence.py (5 ACs + smoke
  test + helper that names the layer in failure messages).
* AZ-282 — helpers/ransac_filter.py: static RansacFilter +
  RansacResult; cv2.setRNGSeed(0) for byte-equal determinism;
  median residual semantics pinned by contract.
* AZ-276 — helpers/imu_preintegrator.py + make_imu_preintegrator;
  GTSAM PreintegratedCombinedMeasurements; strict-monotonic ts_ns
  guard runs before any state mutation. Adjacent hygiene:
  _types/nav.py ImuSample/ImuWindow now use ts_ns:int and the
  spec-mandated ImuBias dataclass.
* AZ-278 — helpers/lightglue_runtime.py: structural R14 fix.
  LightGlueRuntime + non-blocking concurrent-access guard that
  raises rather than serialising. EngineHandle Protocol in
  _types/manifests.py + KeypointSet/CorrespondenceSet in
  _types/matching.py (Protocol surface adds approved by spec).

Dependency conflict (Finding 1, user-approved): gtsam 4.2 (PyPI) is
numpy-1.x-ABI only; opencv-python>=4.12 needs numpy>=2 at runtime.
Resolution: opencv-python pin relaxed to >=4.11.0.86,<4.12. The
D-CROSS-CVE-1 ratchet at ci/opencv_pin_gate.py is held at 4.11.0
with the original 4.12.0 floor restored once a numpy-2-compatible
gtsam wheel ships. Full replay procedure in
_docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md.

Tests: 294 passed, 2 skipped (cmake/actionlint env-skips,
pre-existing). 43 new tests added for batch 5. Ruff check + format
clean.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-11 03:23:33 +03:00
parent ba20c2d195
commit 33486588de
24 changed files with 2096 additions and 36 deletions
@@ -0,0 +1,105 @@
# Batch 05 — Cycle 1 Implementation Report
**Date**: 2026-05-11
**Batch shape**: finish cross-cutting (config precedence tests + 3 Layer-1 helpers)
**Tasks**: AZ-271, AZ-282, AZ-276, AZ-278 (10 complexity points)
**Verdict**: PASS_WITH_WARNINGS (see `reviews/batch_05_review.md`)
## What landed
### AZ-271 — Config precedence unit tests
- `tests/unit/shared/config/test_precedence.py` — 6 tests verifying
env > YAML > defaults precedence for ≥3 keys per layer plus
multi-file YAML merge order. The `_layer_msg` helper standardises
AC-5 assertion messages so failures name the offending layer.
### AZ-282 — RansacFilter helper
- `src/gps_denied_onboard/helpers/ransac_filter.py` — static-only
`RansacFilter`, frozen `RansacResult`, `RansacFilterError`.
Determinism enforced by `cv2.setRNGSeed(0)` immediately before every
`findHomography(..., RANSAC)` call.
- `tests/unit/test_az282_ransac_filter.py` — 16 tests (10 ACs +
parametrised distortion shape contract + frozen dataclass + SE3
alias).
### AZ-276 — ImuPreintegrator helper
- `src/gps_denied_onboard/helpers/imu_preintegrator.py`
`ImuPreintegrator` wraps GTSAM `PreintegratedCombinedMeasurements`;
factory `make_imu_preintegrator(calibration)` reads optional IMU
noise model from `CameraCalibration.metadata["imu_noise_model"]`,
defaulting to documented BMI088-class densities.
- `src/gps_denied_onboard/_types/nav.py` — adjacent hygiene:
`ImuSample(ts_ns: int, ...)` and `ImuWindow(ts_start_ns, ts_end_ns)`
brought into line with the contract; new `ImuBias` dataclass.
- `tests/unit/test_az276_imu_preintegrator.py` — 11 tests covering all
7 ACs plus `integrate_window`, post-rebias guard, factory return
type, and the GTSAM `CombinedImuFactor` re-export.
### AZ-278 — LightGlueRuntime helper (R14 structural fix)
- `src/gps_denied_onboard/helpers/lightglue_runtime.py`
`LightGlueRuntime(engine_handle)` with descriptor-dim validation +
non-blocking concurrent-access guard (`Lock(blocking=False)`
`LightGlueConcurrentAccessError` on contention).
- `src/gps_denied_onboard/_types/manifests.py` — adjacent hygiene
(spec-approved): new `EngineHandle` Protocol with `descriptor_dim`
property + `forward(features_a, features_b) -> CorrespondenceSet`.
- `src/gps_denied_onboard/_types/matching.py` — adjacent hygiene:
new `KeypointSet` and `CorrespondenceSet` dataclasses.
- `tests/unit/test_az278_lightglue_runtime.py` — 10 tests covering all
7 ACs plus negative paths (descriptor_dim < 1, mismatched batch
lengths, accessor parity).
### Dependency-pin change (Finding 1)
- `pyproject.toml``opencv-python` pin relaxed from
`>=4.12.0` to `>=4.11.0.86,<4.12` because gtsam-4.2 (PyPI) is only
numpy-1.x-ABI-compatible and `opencv-python>=4.12` requires
numpy-2 at runtime.
- `ci/opencv_pin_gate.py``MIN_VERSION` ratchet held at `(4, 11, 0)`.
- `tests/unit/test_ac10_ci_gates.py` — test message updated to
reference the leftover.
- `_docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md`
— full replay procedure + CVE exposure note + owner placeholder.
## Test results
- **Full suite**: 294 passed, 2 skipped (`cmake`, `actionlint` env-skip
— pre-existing).
- **New in batch 5**: 43 tests (6 + 16 + 11 + 10).
- `ruff check` + `ruff format` clean across all touched files.
## AC coverage
| Task | ACs | Tests | Status |
|------|-----|-------|--------|
| AZ-271 | 5 | 6 | All PASS |
| AZ-282 | 10 | 16 | All PASS |
| AZ-276 | 7 | 11 | All PASS |
| AZ-278 | 7 | 10 | All PASS |
## Schema / dependency changes
- `FdrConfig` — unchanged (batch 4).
- `CameraCalibration` — unchanged; the IMU noise model is read from
the existing `metadata` field with documented defaults so this is
additive.
- `_types/nav.py`**schema change** to `ImuSample` and `ImuWindow`
(datetime → `ts_ns: int`) plus new `ImuBias`. No production
consumers depend on the old fields; downstream C1/C5 spec work will
pick up the new shape via the contracts.
- `_types/manifests.py` — new `EngineHandle` Protocol (additive).
- `_types/matching.py` — new `KeypointSet`/`CorrespondenceSet`
dataclasses (additive).
- `pyproject.toml``opencv-python` pin relaxed (see Finding 1 in the
review). All other pins unchanged.
## Follow-ups
- **D-CROSS-CVE-1 replay** — pending a numpy-2-compatible gtsam wheel.
Tracked in `_docs/_process_leftovers/`.
- **NFR-perf budgets** — Tier-2 microbenches deferred to AZ-444
(Jetson harness). Functional gates are green in this batch.