[AZ-331] C1 VioStrategy: Protocol + DTOs + factory + C5 migration

Freezes the c1_vio Public API per
_docs/02_document/contracts/c1_vio/vio_strategy_protocol.md v1.0.0:

- VioStrategy Protocol (4 methods: process_frame, reset_to_warm_start,
  health_snapshot, current_strategy_label) in
  components/c1_vio/interface.py.
- DTOs (VioOutput, VioHealth, FeatureQuality, WarmStartPose) + VioState
  enum in _types/nav.py — L1 placement so C5 + C13 consume them without
  crossing the components.* boundary (AZ-270 AC-6). The new VioOutput
  shape (frame_id: str, relative_pose_T: gtsam.Pose3,
  pose_covariance_6x6, imu_bias, feature_quality, emitted_at_ns)
  replaces the AZ-263 scaffolding in _types/vio.py, which is now
  deleted.
- VioError family (VioInitializingError / VioDegradedError /
  VioFatalError) in components/c1_vio/errors.py. Documented
  rationale: the degraded-operation path returns a VioOutput with
  inflated covariance + VioHealth.state=DEGRADED rather than raising
  VioDegradedError — the error type exists only for the rare
  degraded->fatal transition.
- C1VioConfig per-component config block (strategy enum,
  lost_frame_threshold default 9, warm_start_max_frames default 5)
  with constructor-time validation rejecting unknown strategy labels.
- StrategyNotAvailableError added to runtime_root/errors.py;
  composition-time error distinct from the VioError family.
- Composition-root factory build_vio_strategy in
  runtime_root/vio_factory.py with three BUILD_* gates (BUILD_OKVIS2,
  BUILD_VINS_MONO, BUILD_KLT_RANSAC). Concrete strategy modules are
  imported lazily via __import__ AFTER the flag check — Tier-0
  workstation builds with the flag OFF MUST NOT load the strategy
  module (Risk-2 / I-5; verifiable via sys.modules).
- 36 conformance tests cover all 9 ACs + NFR-perf-factory
  (p99 build under 200 ms x 1000 calls) + NFR-reliability-error-family.
  AC-8 introspects the contract file's Shape table and asserts method
  parity against the runtime Protocol; AC-9 asserts the frame_id
  annotation is 'str' (PEP-563 stringified).

C5 migration (consumers of the new VioOutput shape):
- gtsam_isam2_estimator.py + eskf_baseline.py: replaced
  vio.timestamp -> vio.emitted_at_ns (drops _datetime_to_ns on the
  VIO path), vio.pose_se3 -> vio.relative_pose_T (gtsam.Pose3 direct;
  drops _pose_se3_to_gtsam / _pose_se3_to_array), vio.covariance_6x6
  -> vio.pose_covariance_6x6 (rename).
- key_for_frame signature widened to UUID | int | str to accept the
  new str frame_id.
- 4 C5 test files migrated to the new VioOutput shape with helper
  fixtures producing ImuBias + FeatureQuality + str frame_id.
- c5_state/interface.py TYPE_CHECKING import path updated.

Bootstrap healthcheck + test_types_importable updated to drop the
deleted _types/vio module and pick up _types/inference (AZ-297) in
the same sweep.

Full unit-test sweep: 884 passed, 2 pre-existing environment skips
(cmake, actionlint).

Co-authored-by: Cursor <cursoragent@cursor.com>

src/gps_denied_onboard/components/c1_vio/__init__.py

@@ -1,6 +1,52 @@
-"""C1 VIO component — Public API."""
+"""C1 VIO — Public API (AZ-331).
 
-from gps_denied_onboard._types.vio import VioOutput
+Per ``vio_strategy_protocol.md`` v1.0.0 the public surface consists
+of:
+
+- :class:`VioStrategy` Protocol (4 methods).
+- DTOs / enum re-exported from :mod:`gps_denied_onboard._types.nav`
+  (the L1 home for cross-component DTOs): :class:`VioOutput`,
+  :class:`VioHealth`, :class:`FeatureQuality`, :class:`WarmStartPose`,
+  :class:`VioState`.
+- Error family rooted at :class:`VioError`; three documented subtypes.
+- Config block :class:`C1VioConfig` (registered on import).
+
+Concrete strategies (``Okvis2Strategy``, ``VinsMonoStrategy``,
+``KltRansacStrategy``) live in sibling modules and are imported
+lazily by :mod:`gps_denied_onboard.runtime_root.vio_factory` —
+Risk-2 mitigation: this ``__init__.py`` MUST NOT import any concrete
+strategy module.
+"""
+
+from gps_denied_onboard._types.nav import (
+    FeatureQuality,
+    VioHealth,
+    VioOutput,
+    VioState,
+    WarmStartPose,
+)
+from gps_denied_onboard.components.c1_vio.config import C1VioConfig
+from gps_denied_onboard.components.c1_vio.errors import (
+    VioDegradedError,
+    VioError,
+    VioFatalError,
+    VioInitializingError,
+)
 from gps_denied_onboard.components.c1_vio.interface import VioStrategy
+from gps_denied_onboard.config.schema import register_component_block
 
-__all__ = ["VioOutput", "VioStrategy"]
+register_component_block("c1_vio", C1VioConfig)
+
+__all__ = [
+    "C1VioConfig",
+    "FeatureQuality",
+    "VioDegradedError",
+    "VioError",
+    "VioFatalError",
+    "VioHealth",
+    "VioInitializingError",
+    "VioOutput",
+    "VioState",
+    "VioStrategy",
+    "WarmStartPose",
+]

src/gps_denied_onboard/components/c1_vio/config.py

@@ -0,0 +1,63 @@
+"""C1 VIO strategy config block (AZ-331).
+
+Registered into ``config.components['c1_vio']`` by the package
+``__init__.py``. The composition-root factory
+:func:`gps_denied_onboard.runtime_root.vio_factory.build_vio_strategy`
+reads this block to select the strategy and configure the LOST→FATAL
+transition + warm-start convergence budget.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+from gps_denied_onboard.config.schema import ConfigError
+
+__all__ = [
+    "C1VioConfig",
+    "KNOWN_STRATEGIES",
+]
+
+KNOWN_STRATEGIES: Final[frozenset[str]] = frozenset(
+    {"okvis2", "vins_mono", "klt_ransac"}
+)
+
+
+@dataclass(frozen=True)
+class C1VioConfig:
+    """Per-component config for C1 VIO.
+
+    ``strategy`` selects exactly one of the three backends
+    (``okvis2`` / ``vins_mono`` / ``klt_ransac``); the
+    composition-root factory respects compile-time ``BUILD_*`` gating
+    on top of this label.
+
+    ``lost_frame_threshold`` is the number of consecutive ``LOST``
+    frames before the strategy raises :class:`VioFatalError`;
+    default 9 per ``vio_strategy_protocol.md`` v1.0.0.
+
+    ``warm_start_max_frames`` is the convergence budget after
+    :meth:`VioStrategy.reset_to_warm_start`; default 5.
+    """
+
+    strategy: str = "klt_ransac"
+    lost_frame_threshold: int = 9
+    warm_start_max_frames: int = 5
+
+    def __post_init__(self) -> None:
+        if self.strategy not in KNOWN_STRATEGIES:
+            raise ConfigError(
+                f"C1VioConfig.strategy={self.strategy!r} not in "
+                f"{sorted(KNOWN_STRATEGIES)}"
+            )
+        if self.lost_frame_threshold < 1:
+            raise ConfigError(
+                f"C1VioConfig.lost_frame_threshold must be >= 1; "
+                f"got {self.lost_frame_threshold}"
+            )
+        if self.warm_start_max_frames < 1:
+            raise ConfigError(
+                f"C1VioConfig.warm_start_max_frames must be >= 1; "
+                f"got {self.warm_start_max_frames}"
+            )

src/gps_denied_onboard/components/c1_vio/errors.py

@@ -0,0 +1,64 @@
+"""C1 VioStrategy error taxonomy (AZ-331).
+
+Every ``VioStrategy`` method raises only members of :class:`VioError`.
+Lower-level exceptions from OpenCV / OKVIS2 / VINS-Mono / GTSAM MUST
+be caught and rewrapped — the contract closes the error envelope so
+consumers can ``except VioError`` once and handle the family.
+
+:class:`VioDegradedError` is documented but is **not raised** during
+the normal degraded-operation path: degraded operation returns a
+``VioOutput`` with inflated covariance and ``VioHealth.state == DEGRADED``.
+The error type exists for the rare degraded→fatal transition.
+
+A separate composition-time error
+(:class:`gps_denied_onboard.runtime_root.errors.StrategyNotAvailableError`)
+lives outside this family — it is raised by the factory, not by a
+``VioStrategy`` method.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "VioDegradedError",
+    "VioError",
+    "VioFatalError",
+    "VioInitializingError",
+]
+
+
+class VioError(Exception):
+    """Base class for the C1 VIO error family.
+
+    All three documented subtypes are children. Consumers catch the
+    family with ``except c1_vio.errors.VioError as e``.
+    """
+
+
+class VioInitializingError(VioError):
+    """Raised while ``VioHealth.state == INIT`` and the strategy has no
+    pose to emit.
+
+    C5 fusion catches this and falls back to the FC IMU prior until
+    the strategy reports ``TRACKING``.
+    """
+
+
+class VioDegradedError(VioError):
+    """Raised on the rare degraded→fatal transition.
+
+    The normal degraded-operation path is NOT this exception — it is
+    a ``VioOutput`` with inflated covariance + ``VioHealth.state ==
+    DEGRADED``. This type exists only so consumer ``except VioError``
+    wrappers can name the family member explicitly.
+    """
+
+
+class VioFatalError(VioError):
+    """Raised once ``consecutive_lost`` exceeds the configured threshold
+    (default 9) or on irrecoverable backend init failure during
+    :meth:`VioStrategy.reset_to_warm_start`.
+
+    The AC-5.2 fallback path engages once this fires: the camera
+    ingest loop stops feeding the strategy and the watchdog flips
+    the composition root into FC-IMU-only mode.
+    """

src/gps_denied_onboard/components/c1_vio/interface.py

@@ -1,20 +1,94 @@
-"""C1 `VioStrategy` Protocol.
+"""C1 ``VioStrategy`` Protocol (AZ-331).
 
-Concrete strategies: OKVIS2 (default), VINS-Mono (research-only), KLT/RANSAC
-(mandatory simple baseline). See `_docs/02_document/components/01_c1_vio/`.
+PEP 544 ``typing.Protocol`` with ``runtime_checkable=True``; four
+methods that span the camera-ingest hot path
+(``process_frame``), F8 reboot recovery (``reset_to_warm_start``),
+diagnostics (``health_snapshot``), and self-identification
+(``current_strategy_label``).
+
+Concrete impls — :class:`Okvis2Strategy` (AZ-332),
+:class:`VinsMonoStrategy` (AZ-333), :class:`KltRansacStrategy`
+(AZ-334) — live in sibling modules and are imported lazily by
+:mod:`gps_denied_onboard.runtime_root.vio_factory`.
+
+The contract at
+``_docs/02_document/contracts/c1_vio/vio_strategy_protocol.md``
+v1.0.0 is the authoritative shape; this module mirrors it 1:1.
 """
 
 from __future__ import annotations
 
-from typing import Protocol
+from typing import TYPE_CHECKING, Literal, Protocol, runtime_checkable
 
-from gps_denied_onboard._types.nav import ImuWindow, NavCameraFrame
-from gps_denied_onboard._types.vio import VioOutput
+if TYPE_CHECKING:
+    from gps_denied_onboard._types.calibration import CameraCalibration
+    from gps_denied_onboard._types.nav import (
+        ImuWindow,
+        NavCameraFrame,
+        VioHealth,
+        VioOutput,
+        WarmStartPose,
+    )
+
+__all__ = ["VioStrategy"]
 
 
+@runtime_checkable
 class VioStrategy(Protocol):
-    """Visual-Inertial-Odometry strategy."""
+    """On-Jetson visual / visual-inertial odometry runtime.
 
-    def step(self, frame: NavCameraFrame, imu: ImuWindow) -> VioOutput:
-        """Process a single nav-camera frame + IMU window and return a VIO update."""
+    Implementations:
+    :class:`Okvis2Strategy` (production-default, OKVIS2 SLAM),
+    :class:`VinsMonoStrategy` (research-only),
+    :class:`KltRansacStrategy` (mandatory simple-baseline per ADR-002).
+    Selection is owned by the composition root.
+
+    Invariants (see ``vio_strategy_protocol.md`` v1.0.0):
+    - Single-threaded per instance (one camera-ingest writer thread).
+    - ``current_strategy_label()`` is constant per instance and
+      equals ``config.vio.strategy`` exactly.
+    - Error envelope is closed — only members of
+      :class:`VioError` escape ``process_frame``.
+    """
+
+    def process_frame(
+        self,
+        frame: "NavCameraFrame",
+        imu: "ImuWindow",
+        calibration: "CameraCalibration",
+    ) -> "VioOutput":
+        """Camera-ingest hot-path call (one per nav-camera frame).
+
+        ``VioOutput.frame_id`` MUST equal ``frame.frame_id`` (C5
+        alignment invariant). Raises :class:`VioInitializingError`
+        while booting (state == INIT; no output emitted) and
+        :class:`VioFatalError` once ``consecutive_lost`` exceeds the
+        configured threshold. During DEGRADED operation the method
+        returns normally with an inflated covariance — NOT raises
+        :class:`VioDegradedError`.
+        """
+        ...
+
+    def reset_to_warm_start(self, hint: "WarmStartPose") -> None:
+        """Destructive re-init from an F8-reboot warm-start hint.
+
+        Clears keyframe window, IMU integration state, feature
+        tracks. Subsequent ``process_frame`` calls re-initialise from
+        the hint. Raises :class:`VioFatalError` only on irrecoverable
+        backend init failure.
+        """
+        ...
+
+    def health_snapshot(self) -> "VioHealth":
+        """Most-recent health state — FDR-stamped per the AC-NEW-3 audit."""
+        ...
+
+    def current_strategy_label(
+        self,
+    ) -> Literal["okvis2", "vins_mono", "klt_ransac"]:
+        """Identify which concrete strategy is wired here.
+
+        Returned string equals ``config.vio.strategy`` exactly.
+        AC-NEW-3 FDR audit relies on this property.
+        """
         ...

src/gps_denied_onboard/components/c5_state/eskf_baseline.py

@@ -449,9 +449,9 @@ class EskfStateEstimator(StateEstimator):
         residual in the previous body frame.
         """
         self._close_cold_start_window()
-        ts_ns = _datetime_to_ns(vio.timestamp)
+        ts_ns = vio.emitted_at_ns
         self._guard_timestamp(ts_ns, source="vio")
-        curr_pose = _pose_se3_to_array(vio.pose_se3)
+        curr_pose = vio.relative_pose_T.matrix()
 
         if self._prev_vio_pose is None:
             self._prev_vio_pose = curr_pose
@@ -498,7 +498,7 @@ class EskfStateEstimator(StateEstimator):
         H = np.zeros((6, _N_STATE), dtype=np.float64)
         H[0:3, _IDX_POS] = np.eye(3)
         H[3:6, _IDX_ROT] = prev_R  # rotate body-frame perturbation back to world
-        R_meas = _measurement_noise(vio.covariance_6x6)
+        R_meas = _measurement_noise(vio.pose_covariance_6x6)
 
         try:
             self._kalman_update(H, residual, R_meas, source="vio")

src/gps_denied_onboard/components/c5_state/gtsam_isam2_estimator.py

@@ -6,7 +6,7 @@ real bodies. AZ-383 owns the three Protocol factor-add methods:
 
 * ``add_vio(vio: VioOutput)`` — ``BetweenFactorPose3`` between
   consecutive pose keys with a noise model derived from
-  ``vio.covariance_6x6``.
+  ``vio.pose_covariance_6x6``.
 * ``add_pose_anchor(pose: PoseEstimate)`` — mode-dispatched per
   ``pose.covariance_mode``: ``"marginals"`` → ``PriorFactorPose3`` +
   ``update``; ``"jacobian"`` → skip iSAM2 add (per the AZ-361 cross-task
@@ -403,7 +403,7 @@ class GtsamIsam2StateEstimator(StateEstimator):
         """Register a callback fired exactly once per fallback recovery."""
         return self._fallback.subscribe_recovered(callback)
 
-    def key_for_frame(self, frame_id: UUID | int) -> int:
+    def key_for_frame(self, frame_id: UUID | int | str) -> int:
         """Return the GTSAM ``Key`` for ``frame_id``, assigning on first use.
 
         AZ-383 calls this from ``add_vio`` and ``add_pose_anchor`` to
@@ -653,10 +653,10 @@ class GtsamIsam2StateEstimator(StateEstimator):
         """
         handle = self._require_handle()
         self._close_cold_start_window()
-        ts_ns = _datetime_to_ns(vio.timestamp)
+        ts_ns = vio.emitted_at_ns
         self._guard_timestamp(ts_ns, source="vio")
 
-        curr_pose = _pose_se3_to_gtsam(vio.pose_se3)
+        curr_pose = vio.relative_pose_T
         curr_key = self.key_for_frame(vio.frame_id)
 
         if self._prev_vio is None:
@@ -674,10 +674,10 @@ class GtsamIsam2StateEstimator(StateEstimator):
             )
             return
 
-        prev_pose = _pose_se3_to_gtsam(self._prev_vio.pose_se3)
+        prev_pose = self._prev_vio.relative_pose_T
         prev_key = self.key_for_frame(self._prev_vio.frame_id)
         relative_pose = prev_pose.between(curr_pose)
-        noise = _build_pose_noise(vio.covariance_6x6)
+        noise = _build_pose_noise(vio.pose_covariance_6x6)
         factor = gtsam.BetweenFactorPose3(prev_key, curr_key, relative_pose, noise)
 
         try:

src/gps_denied_onboard/components/c5_state/interface.py

@@ -26,7 +26,7 @@ if TYPE_CHECKING:
         EstimatorHealth,
         EstimatorOutput,
     )
-    from gps_denied_onboard._types.vio import VioOutput
+    from gps_denied_onboard._types.nav import VioOutput
 
 __all__ = ["StateEstimator"]