gps-denied-onboard/_docs/02_tasks/done/AZ-278_lightglue_runtime.md

LightGlueRuntime Helper Module (R14 fix)

Task: AZ-278_lightglue_runtime Name: LightGlueRuntime Helper Description: Implement the shared LightGlueRuntime helper that owns the LightGlue inference engine handle for both C2.5 (single-pair inlier counting) and C3 (heavier matching pass). This is the structural fix for R14 (the original C2.5 ↔ C3 import cycle): the runtime sits at Layer 1 with no components.* imports, so the cycle becomes impossible to express. Single CUDA stream; concurrent access forbidden by contract; composition root binds to the single F3 hot-path thread. Complexity: 3 points Dependencies: AZ-263_initial_structure Component: shared.helpers.lightglue_runtime (cross-cutting; epic AZ-264 / E-CC-HELPERS) Tracker: AZ-278 Epic: AZ-264 (E-CC-HELPERS)

Document Dependencies

• _docs/02_document/contracts/shared_helpers/lightglue_runtime.md — frozen public interface this task produces.
• _docs/02_document/common-helpers/03_helper_lightglue_runtime.md — design rationale and R14 context.

Problem

C2.5 (Re-rank) and C3 (CrossDomainMatcher) both call LightGlue. In cycle 1 of _docs/02_document/epics.md, LightGlue ownership was ambiguous and produced R14: a circular import / runtime dependency between C2.5 and C3 (the "K=10 → N=3 funnel" both wanted to own the engine). Without a shared runtime:

• The engine is built / loaded twice, doubling GPU memory at takeoff (Tier-2 has only 8 GB).
• C2.5 and C3 drift on engine version pinning, producing inconsistent matches.
• Their import cycle is a recurring footgun: any future refactor will tempt one to import from the other.

Outcome

• A single LightGlueRuntime instance is constructed once at takeoff by the composition root from C7's deserialize_engine(LIGHTGLUE_ENGINE_CACHE_ENTRY) and is constructor-injected into BOTH C2.5 and C3.
• The C2.5 ↔ C3 import cycle is structurally impossible: the runtime lives at Layer 1 (helpers/) and imports zero components.* modules. Both consumers depend on the helper; neither depends on the other.
• Concurrent access is rejected at runtime by an explicit guard (LightGlueConcurrentAccessError), preserving the single-CUDA-stream invariant. The composition root binds the runtime to the single F3 hot-path thread; AC-4 of the contract is the canary that catches future composition-root mistakes.
• The helper exposes no set_* / update_* methods — once constructed, the runtime's behaviour is fixed.

Scope

Included

• LightGlueRuntime(engine_handle: EngineHandle) constructor.
• match(features_a: KeypointSet, features_b: KeypointSet) -> CorrespondenceSet — single-pair path used by C2.5.
• match_batch(features_a_list, features_b_list) -> list[CorrespondenceSet] — batch path used by C3.
• descriptor_dim() -> int accessor for shape validation upstream of match.
• Concurrent-access guard that raises LightGlueConcurrentAccessError on overlapping match / match_batch entries.
• LightGlueRuntimeError (construction / dim mismatch) and LightGlueConcurrentAccessError (concurrent entry) exception types.
• Public interface contract published at _docs/02_document/contracts/shared_helpers/lightglue_runtime.md.

Excluded

• Engine compilation / serialisation — C7.
• Engine filename schema — helpers.engine_filename_schema (separate task in this epic).
• Engine cache management / takeoff load — C10.
• Backbone-specific feature extraction (DISK / ALIKED / XFeat) — C3 / C7.
• Multi-GPU / multi-stream / mixed-backbone — out of scope for v1.0.0.
• The EngineHandle Protocol itself — owned by _types/manifests.py (AZ-263) so Layer 1 can reference it without depending on C7.

Acceptance Criteria

AC-1: Single-pair match (C2.5 path) Given a pair of KeypointSets with matching descriptor dim and a synthetic-overlap fixture When match(features_a, features_b) runs Then a CorrespondenceSet is returned with len > 0 and the inlier-count helper used by C2.5 finds the expected count

AC-2: Batch match (C3 path) Given three pairs of KeypointSets When match_batch([a1, a2, a3], [b1, b2, b3]) runs Then three CorrespondenceSets are returned in input order; per-pair invariants match the single-pair path

AC-3: Descriptor-dim mismatch rejected Given features whose descriptor_dim does not match the engine's expected dim When match runs Then LightGlueRuntimeError is raised with a message naming both the expected and actual dims

AC-4: Concurrent access rejected Given two threads call match simultaneously on the same LightGlueRuntime instance When the second call enters Then LightGlueConcurrentAccessError is raised in the second thread; the first thread completes normally

AC-5: Construction-time guard Given LightGlueRuntime(engine_handle=None) When construction runs Then LightGlueRuntimeError is raised mentioning engine_handle

AC-6: No upward imports — R14 structural fix Given the helper module When a static-import check runs across gps_denied_onboard.helpers.lightglue_runtime Then it imports ONLY from _types, numpy, and stdlib — NO imports from gps_denied_onboard.components.* (verified by importlinter or grep gate in CI)

AC-7: Determinism downstream of the engine Given the same (features_a, features_b) pair matched twice with the same engine_handle When match runs both times Then both CorrespondenceSet outputs are byte-equal (engine determinism is a C7 concern; this AC asserts the helper itself adds no non-determinism)

Non-Functional Requirements

Performance

• match p99 ≤ 30 ms on Tier-2 with the production DISK+LightGlue engine on a typical K=10 candidate pair (matches the per-frame budget for C2.5's K=10 → N=3 funnel).
• Helper-level overhead (excluding the engine call itself) ≤ 100 µs — verified via a benchmark that swaps in a stub engine handle.

Reliability

• LightGlueRuntimeError and LightGlueConcurrentAccessError are the ONLY exception types the public surface raises. Engine-internal exceptions MUST be wrapped.
• Pure-deterministic given a deterministic engine; the helper itself adds no random state.

Concurrency

• Single-thread by contract. The concurrent-access guard is the runtime invariant detector — any composition-root regression that wires the runtime into multiple threads is caught immediately rather than producing GPU memory corruption.

Unit Tests

AC Ref	What to Test	Required Outcome
AC-1	single-pair match on synthetic-overlap fixture	non-empty CorrespondenceSet
AC-2	batch of 3 pairs	three results in input order; per-pair invariants match AC-1
AC-3	dim-mismatched features	LightGlueRuntimeError; message names expected & actual dims
AC-4	two threads call match simultaneously	one succeeds; the second raises LightGlueConcurrentAccessError
AC-5	construct with engine_handle=None	LightGlueRuntimeError
AC-6	importlinter / grep gate over helpers/lightglue_runtime.py	no components.* imports
AC-7	same pair matched twice	byte-equal outputs (with deterministic stub engine)
NFR-perf	microbench match overhead with stub engine (10k iterations on Tier-2 fixture)	helper overhead ≤ 100 µs

Constraints

• Public surface frozen by _docs/02_document/contracts/shared_helpers/lightglue_runtime.md v1.0.0.
• Layer 1 Foundation only. NO upward imports — this is the load-bearing constraint for the R14 fix.
• The EngineHandle Protocol must be defined in _types/manifests.py (AZ-263 / E-BOOT) so this helper can reference it without importing C7. If _types/manifests.py does not yet define the Protocol surface (forward(...), descriptor_dim), this task adds it — that is the only _types edit allowed by this task.
• No new dependency beyond what AZ-263 / E-BOOT pinned.

Risks & Mitigation

Risk 1: Composition root accidentally creates two runtimes (one for C2.5, one for C3)

• Risk: Future composition-root refactor instantiates LightGlueRuntime twice; engine memory doubles, behaviour drifts.
• Mitigation: The composition-root contract test (E-CC-CONF / AZ-246, AZ-269/AZ-270 in scope) already verifies cardinality of cross-cutting helpers. This task's contract documents that EXACTLY ONE instance is expected; the composition-root validator is the enforcement point.

Risk 2: Concurrent-access guard introduces hot-path overhead

• Risk: A naive threading.Lock on every match call adds 100s of µs.
• Mitigation: The guard uses a non-blocking threading.local()-style check or a Lock(blocking=False).acquire() pattern that simply RAISES on contention rather than serialising callers — the contract is "concurrent calls are a bug", not "serialise concurrent callers". NFR-perf microbench validates the overhead budget.

Risk 3: A future backbone needs a different match shape

• Risk: A new feature backbone produces 5-tuple correspondences instead of the current 4-tuple (e.g., adds confidence per match).
• Mitigation: The contract version bump path is documented (Versioning Rules section). Adding a field is non-breaking IF consumers tolerate the extra field; otherwise it is a major-version contract change with a deprecation pass.

Runtime Completeness

• Named capability: shared LightGlue inference runtime with single-CUDA-stream guarantee + R14 structural cycle fix (architecture / E-CC-HELPERS / 03_helper_lightglue_runtime.md).
• Production code that must exist: real EngineHandle-backed match dispatch; real concurrent-access guard; real descriptor-dim validation.
• Allowed external stubs: a deterministic stub EngineHandle is allowed in tests (and recommended for AC-7 determinism) but production paths use C7's real engine.
• Unacceptable substitutes: bypassing the concurrent-access guard with threading.Lock (silently serialising callers); allowing each consumer to construct its own runtime; reintroducing a C2.5 → C3 (or C3 → C2.5) import to "share state". Any of those reintroduces R14.

Contract

This task produces the contract at _docs/02_document/contracts/shared_helpers/lightglue_runtime.md. Consumers MUST read that file — not this task spec — to discover the interface.