gps-denied-onboard/_docs/02_tasks/done/AZ-344_c3_matcher_protocol.md

C3 CrossDomainMatcher Protocol + Factory + Composition

Task: AZ-344_c3_matcher_protocol Name: C3 CrossDomainMatcher Protocol + Factory + Composition Description: Define the public CrossDomainMatcher Protocol (PEP 544 structural interface), the C3 DTOs (CandidateMatchSet, MatchResult, MatcherHealth), the error hierarchy (MatcherError family with MatcherBackboneError, InsufficientInliersError), and the composition-root factory build_matcher_strategy(config, lightglue_runtime, ransac_filter, inference_runtime) -> CrossDomainMatcher that selects the concrete matcher at startup based on config.matcher.strategy with lazy import + BUILD_MATCHER_<variant> flag gating per ADR-002. Includes the rolling-window MatcherHealth accumulator infrastructure (constructor-injected into every concrete matcher; updated inside match after each frame). The shared LightGlueRuntime (AZ-278) and RansacFilter (AZ-282) helpers are constructor-injected — neither owned by C3. This task delivers the foundational scaffolding every concrete matcher (AZ-345..AZ-347) depends on; no concrete backbone is implemented here. Complexity: 3 points Dependencies: AZ-263_initial_structure, AZ-269_config_loader, AZ-270_compose_root, AZ-278_lightglue_runtime, AZ-282_ransac_filter, AZ-297_c7_runtime_protocol (for InferenceRuntime interface), AZ-266_log_module Component: c3_matcher (epic AZ-257 / E-C3) Tracker: AZ-344 Epic: AZ-257 (E-C3)

Document Dependencies

• _docs/02_document/contracts/c3_matcher/cross_domain_matcher_protocol.md — the public contract this task implements (Protocol surface + DTOs + error hierarchy + factory signature + 9 invariants + test cases).
• _docs/02_document/components/04_c3_matcher/description.md — § 1 architectural pattern (Strategy); § 2 CrossDomainMatcher interface + DTOs; § 5 error handling (drop-and-continue + below-threshold + all-failed); § 7 caveats (shared helper serial access); § 9 logging.
• _docs/02_document/module-layout.md — c3_matcher Per-Component Mapping; BUILD_MATCHER_<variant> rows; § Layer 3.
• _docs/02_document/architecture.md — ADR-001, ADR-002, ADR-009.
• _docs/02_document/contracts/c2_5_rerank/rerank_strategy_protocol.md — RerankResult DTO consumed at the input boundary.
• _docs/02_document/contracts/shared_helpers/lightglue_runtime.md — helper handle.
• _docs/02_document/contracts/shared_helpers/ransac_filter.md — helper API consumed for inlier filtering.
• _docs/02_document/contracts/c7_inference/inference_runtime_protocol.md — InferenceRuntime interface consumed by every concrete backbone.

Problem

Without this task, every concrete matcher (AZ-345..AZ-347) and the downstream C3.5 ConditionalRefiner (AZ-258 component) would each invent their own ad-hoc interface, breaking ADR-001 (Strategy), ADR-002 (build-time exclusion), and ADR-009 (interface-first DI). The rolling MatcherHealth accumulator also needs ONE owner; without this task, every concrete matcher would re-implement the rolling window → drift between strategies → C5's spoof-promotion gate (AC-NEW-2 / AC-NEW-7) would behave inconsistently across matchers.

Outcome

• src/gps_denied_onboard/components/c3_matcher/interface.py defining the CrossDomainMatcher Protocol (@runtime_checkable) with match and health_snapshot. Docstring encodes all 9 invariants from the contract.
• src/gps_denied_onboard/components/c3_matcher/__init__.py re-exporting the Protocol + DTOs (CrossDomainMatcher, MatchResult, MatcherHealth).
• src/gps_denied_onboard/_types/matcher.py defining the three frozen + slotted dataclasses: CandidateMatchSet, MatchResult, MatcherHealth. Cross-component-consumed → lives in shared _types/.
• src/gps_denied_onboard/components/c3_matcher/errors.py defining MatcherError, MatcherBackboneError, InsufficientInliersError.
• src/gps_denied_onboard/components/c3_matcher/_health_window.py defining RollingHealthWindow — the 60 s rolling window with O(1) accumulators (consecutive_low_inlier, mean_inliers_60s, backbone_error_count_60s). Provided to every concrete matcher via constructor injection so they share semantics.
• src/gps_denied_onboard/runtime_root/matcher_factory.py exporting build_matcher_strategy(config, lightglue_runtime, ransac_filter, inference_runtime) -> CrossDomainMatcher. The factory:
  1. Reads config.matcher.strategy (one of: "disk_lightglue", "aliked_lightglue", "xfeat").
  2. Lazy-imports per the strategy resolution table.
  3. ImportError "No module named" → ConfigurationError(f"BUILD_MATCHER_{strategy.upper()} is OFF..."). Other ImportErrors re-raised.
  4. Constructs the strategy via its module-level create(config, lightglue_runtime, ransac_filter, inference_runtime, health_window) factory function.
  5. Returns the instance.
• Composition-root compose_root extension: invoke build_matcher_strategy AFTER LightGlueRuntime + RansacFilter are constructed; bind the result to the same C2.5 ingest thread. Identity-share the LightGlueRuntime instance with C2.5 (per AZ-342 AC-10).
• Config schema extension to AZ-269: config.matcher.strategy (enum), config.matcher.min_inliers_threshold (int, default 60), config.matcher.residual_warn_threshold_px (float, default 2.5).
• INFO log on every successful build_matcher_strategy: kind="c3.matcher.strategy_loaded" with strategy name + thresholds.
• ERROR log on ConfigurationError (specific missing flag).

Scope

Included

• The CrossDomainMatcher Protocol with both match and health_snapshot methods.
• The three DTOs in _types/matcher.py.
• The three-class error hierarchy in c3_matcher/errors.py.
• The RollingHealthWindow accumulator in _health_window.py (constructor-injected into every matcher).
• The composition-root factory with lazy-import + ConfigurationError mapping.
• Config schema extension for config.matcher.{strategy, min_inliers_threshold, residual_warn_threshold_px}.
• Strategy resolution table comment matching the contract verbatim.
• Composition-root wiring path that identity-shares LightGlueRuntime with C2.5.
• Unit tests covering: Protocol conformance (runtime_checkable), DTO immutability + slots, factory rejection on missing flag, factory acceptance for valid values, rolling window O(1) accumulator correctness, INFO log emission, error hierarchy catchability.
• INFO / ERROR log emission per description.md § 9.

Excluded

• Any concrete matcher implementation — owned by AZ-345 (DISK+LightGlue), AZ-346 (ALIKED+LightGlue), AZ-347 (XFeat).
• The LightGlueRuntime helper — already AZ-278.
• The RansacFilter helper — already AZ-282.
• The C7 InferenceRuntime — owned by AZ-297.
• The C2.5 RerankResult DTO — consumed; produced by AZ-342.
• Component-internal acceptance tests beyond Protocol-conformance + factory-validation: C3-IT-01..05 + C3-PT-01 deferred to Step 9 / E-BBT.

Acceptance Criteria

AC-1: Protocol conformance — runtime_checkable Given a FakeMatcher test double implementing both match and health_snapshot When isinstance(fake, CrossDomainMatcher) is evaluated Then result is True; an object missing either method returns False

AC-2: DTO immutability + slots All three DTOs use frozen=True, slots=True; mutation raises FrozenInstanceError; __slots__ non-empty.

AC-3: Factory rejects missing build flag Given config.matcher.strategy = "nonexistent_matcher" When build_matcher_strategy(...) is called Then ConfigurationError("BUILD_MATCHER_NONEXISTENT_MATCHER is OFF...") is raised; ONE ERROR log kind="c3.matcher.build_flag_off" is emitted.

AC-4: Factory rejects unknown strategy at config-load time Given config.matcher.strategy = "garbage" (not in the resolution table) When load_config(...) is called Then ConfigurationError raised at config-load time; the factory is never invoked.

AC-5: Successful factory load emits INFO log Given config.matcher.strategy = "disk_lightglue" AND a valid lazy-importable test double module When build_matcher_strategy(...) is called Then a CrossDomainMatcher instance is returned; ONE INFO log kind="c3.matcher.strategy_loaded" is emitted with {strategy, min_inliers_threshold, residual_warn_threshold_px}.

AC-6: Strategy resolution — every entry resolves to its module path Given each of three valid config.matcher.strategy values When build_matcher_strategy is called for each Then resolved module path matches the contract's table verbatim.

AC-7: Error hierarchy catchability Test instances of MatcherBackboneError + InsufficientInliersError caught by except MatcherError.

AC-8: Public API surface — __init__.py re-exports Given from gps_denied_onboard.components.c3_matcher import CrossDomainMatcher, MatchResult, MatcherHealth When the import is evaluated Then all three names resolve; internal names (RollingHealthWindow, _health_window) are NOT in __all__.

AC-9: Strategy bound to single ingest thread by composition root Single-thread binding enforced; second binding attempt raises RuntimeError.

AC-10: LightGlueRuntime is identity-shared between C3 and C2.5 Given a compose_root(config) invocation that wires both C2.5 and C3 When the resulting strategies are inspected Then c3_strategy._lightglue_runtime is c2_5_strategy._lightglue_runtime (identity); ONE INFO log confirming the shared binding is emitted (the SAME log line as AZ-342 AC-10 — emitted ONCE).

AC-11: RollingHealthWindow O(1) accumulator correctness Given a RollingHealthWindow (60 s) AND a sequence of (frame_id, inlier_count, had_backbone_error) events spanning 90 s When health_snapshot() is called at t=60s, t=70s, t=90s Then consecutive_low_inlier, mean_inliers_60s, backbone_error_count_60s match an independent sliding-window computation; each health_snapshot() call is O(1) (microbench p99 ≤ 50 µs).

AC-12: RollingHealthWindow.update() API Given the window has incremental update entry-points (called from inside concrete matchers' match after each frame) When update(timestamp_ns, best_inlier_count, had_backbone_error) is called Then accumulators are updated incrementally; mean_inliers_60s is the rolling mean; consecutive_low_inlier resets to 0 when a frame's inlier_count >= min_inliers_threshold.

Non-Functional Requirements

Performance

• build_matcher_strategy p99 ≤ 50 ms (factory itself; concrete-strategy construction cost owned by AZ-345..AZ-347).
• RollingHealthWindow.update p99 ≤ 5 µs; health_snapshot p99 ≤ 50 µs.

Compatibility

• Protocol method-signature changes are major version bumps (lockstep update).
• DTO field additions are minor; field removals are major.

Reliability

• Lazy-import via importlib.import_module; build-time-excluded matchers never load CUDA / TensorRT.
• Single-thread invariant enforced at composition-root binding time (AC-9).
• RollingHealthWindow is a non-thread-safe single-thread structure; matches the single-thread binding invariant.

Unit Tests

AC Ref	What to Test	Required Outcome
AC-1	Protocol conformance	Fake passes; partial fake fails
AC-2	DTO immutability + slots	FrozenInstanceError; non-empty __slots__
AC-3	Factory + missing flag	ConfigurationError; ERROR log
AC-4	Config load + unknown strategy	ConfigurationError at load time
AC-5	Factory + valid load	Strategy returned; INFO log with structured fields
AC-6	All 3 strategy values resolve	Module paths match resolution table
AC-7	Error catchability	All errors caught by except MatcherError
AC-8	Public API re-exports	Public names resolve; internals not in __all__
AC-9	Single-thread binding	Second binding raises RuntimeError
AC-10	Identity-share with C2.5	is identity preserved
AC-11	Rolling window correctness	Matches independent sliding-window computation
AC-12	update semantics	consecutive_low_inlier resets on a high-inlier frame; mean_inliers_60s is rolling
NFR-perf-window	RollingHealthWindow.update × 100k	p99 ≤ 5 µs

Constraints

• Lazy import is mandatory (ADR-002).
• @runtime_checkable MUST be used.
• DTOs MUST be frozen=True, slots=True.
• Concrete matcher modules export create(...) as their entry-point.
• config.matcher.strategy is an enum validated at config load.
• The factory does NOT instantiate LightGlueRuntime or RansacFilter — runtime root constructs ONCE and shares with C2.5 (AC-10).
• RollingHealthWindow is single-thread — no locks; matches single-thread binding invariant. Adding locks would mask binding bugs.

Risks & Mitigation

Risk 1: runtime_checkable Protocol checks have known performance cost

• Mitigation: isinstance only at composition-root binding (AC-9), not per-frame.

Risk 2: Lazy-import error message obscures real failure mode

• Mitigation: factory catches ImportError, inspects message; "No module named" → "BUILD flag OFF"; otherwise re-raises preserving native context.

Risk 3: RollingHealthWindow 60 s window data structure choice (deque vs ring buffer)

• Mitigation: implementation detail; AC-11 + AC-12 + NFR-perf-window are the contract. Any structure satisfying O(1) update + O(1) snapshot is acceptable.

Risk 4: compose_root thread-binding registry / shared-helper composition not yet implemented in AZ-270

• Mitigation: same as AZ-342 Risk 4. Keep AC-9 / AC-10; if AZ-270 lacks the registry, escalate via tracker dependency mechanism.

Runtime Completeness

• Named capability: CrossDomainMatcher Protocol + composition-root factory + RollingHealthWindow accumulator + ADR-002 build-time exclusion.
• Production code that must exist: real Protocol + real DTOs + real error hierarchy + real build_matcher_strategy factory + real RollingHealthWindow + real config schema extension + real composition-root wiring path that identity-shares LightGlueRuntime with C2.5.
• Allowed external stubs: FakeMatcher, FakeLightGlueRuntime, FakeRansacFilter, FakeInferenceRuntime for tests. Production wiring uses real concretes.
• Unacceptable substitutes: direct from .disk_lightglue import DiskLightGlueMatcher in the factory (defeats ADR-002); a Type[CrossDomainMatcher] registry that pre-imports all matchers (defeats lazy-import); making RollingHealthWindow thread-safe with locks (would mask single-thread binding bugs); skipping the identity-share with C2.5 (would double GPU memory).

Contract

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