Implement the single production-default C4 PoseEstimator strategy.
AZ-358 — Marginals path: OpenCV solvePnPRansac (SOLVEPNP_IPPE) on
best-candidate inliers, PriorFactorPose3 with Jacobian-derived initial
covariance, flushed into C5's iSAM2 graph via the widened
ISam2GraphHandle.update(graph, values, None) (Option B). Posterior
covariance from compute_marginals().marginalCovariance(pose_key) with
SPD-defensive Cholesky check. Tile pixel -> ENU world conversion via
the shared WgsConverter + a configurable tile_size_px. Two spec
deviations now documented in the AZ-358 task file: PriorFactorPose3
over GenericProjectionFactorCal3DS2 (avoids unbounded landmark
variables; same Fisher information on the pose marginal) and explicit
(graph, values, timestamps) update args (aligns with C5's impl).
AZ-361 — Jacobian + thermal hybrid: per-frame dispatch on
thermal_state.thermal_throttle_active selects the cv2.projectPoints-
derived 6x6 information matrix (with ridge regularisation) as the
emitted covariance. Skips the iSAM2 factor add under throttle
(Invariant 12). Emits CovarianceDegradedWarning via warnings.warn
(never raised); paired WARN log + FDR record rate-limited per
covariance_degraded_warn_window_ns (default 60 s) via an injected
monotonic Clock. Supersedes the AZ-358 NotImplementedError stub.
Widens ISam2GraphHandle from get_pose_key only to all five C4-facing
methods (add_factor, update, compute_marginals, last_anchor_age_ms);
C5's existing ISam2GraphHandleImpl already satisfies the superset, so
no C5 source change this batch. Threads fdr_client + clock through
pose_factory composition.
Registers two new FDR payload kinds: pose.frame_done (per-call
telemetry; both success and PnpFailureError paths) and
pose.covariance_degraded (per-window throttle exposure).
Tests: 21 new (AZ-358 AC-1..11 + AZ-361 AC-1..10/12/13; AZ-361 AC-11
RMSE-ratio informational per spec, not asserted). Updates 2 existing
test files for Protocol widening and the FDR-schema round trip.
Code review verdict: PASS_WITH_WARNINGS (5 findings: Medium x2,
Low x3; none blocking). Full suite: 1958 passed, 1 unrelated
host-dependent perf failure (c12 CLI cold-start, pre-existing).
Co-authored-by: Cursor <cursoragent@cursor.com>
Freezes the c7_inference Public API per
_docs/02_document/contracts/c7_inference/inference_runtime_protocol.md
v1.0.0:
- InferenceRuntime Protocol (6 methods: compile_engine,
deserialize_engine, infer, release_engine, thermal_state,
current_runtime_label) in components/c7_inference/interface.py.
- DTOs (PrecisionMode enum, OptimizationProfile, BuildConfig,
EngineCacheEntry, EngineHandle opaque marker) in _types/inference.py
— placed at the L1 types layer so C10 can re-export EngineCacheEntry
without crossing the components.* boundary (AZ-270 AC-6).
- ThermalState DTO expanded in _types/thermal.py from the AZ-355
forward-declared stub to the AZ-297 contract shape (cpu/gpu temp,
thermal_throttle_active, measured_clock_mhz, measured_at_ns,
is_telemetry_available). Invariant I-6: when telemetry is
unavailable, throttle is False.
- Error family rooted at c7_inference.errors.RuntimeError (9 subtypes:
EngineBuildError, EngineDeserializeError, EngineHashMismatchError,
EngineSchemaMismatchError, EngineSidecarMissingError,
CalibrationCacheError, InferenceError, OutOfMemoryError,
TelemetryUnavailableError). RuntimeNotAvailableError stays in
runtime_root/errors.py — composition-time, outside the family.
- C7InferenceConfig per-component config block (runtime label,
thermal_poll_hz, engine_cache_dir) with constructor-time validation
rejecting unknown runtime labels.
- Composition-root factory build_inference_runtime in
runtime_root/inference_factory.py with three BUILD_* gates
(BUILD_TENSORRT_RUNTIME, BUILD_ONNX_TRT_EP_RUNTIME,
BUILD_PYTORCH_FP16_RUNTIME). Concrete strategy modules are imported
lazily via __import__ AFTER the flag check, so a Tier-0 build with
the flag OFF MUST NOT load the strategy module (AC-5 / I-5;
verifiable via sys.modules).
- 37 conformance tests cover all 8 ACs + NFR-perf-factory
(p99 build under 200 ms × 1000 calls) + NFR-reliability-error-family.
AC-8 introspects the contract file's Shape table and asserts method
parity against the runtime Protocol; also asserts all 9 error
subtypes are documented.
Retired the AZ-263 scaffolding EngineCacheEntry from _types/manifests.py
(replaced by the AZ-297 canonical shape in _types/inference.py); updated
the LightGlue-flavoured EngineHandle Protocol docstring in
_types/manifests.py to rationalize its intentional dual existence
with the C7 opaque EngineHandle (same name, different consumer-side
cut, mirroring the C4/C5 ISam2GraphHandle pattern).
Stale ThermalState.throttle docstring references in c4_pose/config.py,
c4_pose/interface.py, and _types/pose.py updated to
thermal_throttle_active.
Full unit-test sweep: 843 passed, 2 pre-existing environment skips
(cmake, actionlint).
Co-authored-by: Cursor <cursoragent@cursor.com>
Oleksandr Bezdieniezhnykh