gps-denied-onboard/_docs/02_tasks/todo/AZ-381_c5_state_protocol.md

C5 StateEstimator Protocol + Factory + DTOs + Composition + Concrete ISam2GraphHandle

Task: AZ-381_c5_state_protocol Name: C5 StateEstimator Protocol + Factory + DTOs + Composition + concrete ISam2GraphHandle Description: Define the public StateEstimator Protocol (PEP 544 @runtime_checkable), the C5 DTOs (EstimatorOutput, EstimatorHealth, IsamState enum), the error hierarchy (StateEstimatorError, EstimatorDegradedError, EstimatorFatalError, StateEstimatorConfigError), the composition-root factory build_state_estimator(...) -> tuple[StateEstimator, ISam2GraphHandle], AND the CONCRETE ISam2GraphHandle implementation extending the AZ-355 Protocol stub with add_factor/update/compute_marginals/last_anchor_age_ms methods. The handle is constructed alongside the iSAM2 graph (initially empty here; populated by AZ-382 iSAM2 wiring task) and passed by reference to C4 via the runtime root. Strategy resolution per ADR-002 with BUILD_STATE_<variant> gating. Shared helpers (ImuPreintegrator AZ-276, SE3Utils AZ-277, WgsConverter AZ-279) constructor-injected. Config schema extension for state.{strategy, keyframe_window_size, spoof_promotion_min_stable_s, spoof_promotion_visual_consistency_tol_m, no_estimate_fallback_s}. No iSAM2 graph internals or factor-add logic in scope here. Complexity: 3 points Dependencies: AZ-263, AZ-269, AZ-270, AZ-276 (ImuPreintegrator), AZ-277 (SE3Utils), AZ-279 (WgsConverter), AZ-273 (FdrClient), AZ-355 (C4's ISam2GraphHandle Protocol stub — extended here), AZ-266 Component: c5_state (epic AZ-260 / E-C5) Tracker: AZ-381 Epic: AZ-260 (E-C5)

Document Dependencies

• _docs/02_document/contracts/c5_state/state_estimator_protocol.md — the public contract this task implements.
• _docs/02_document/components/07_c5_state/description.md — § 1, § 2, § 5 error handling, § 9 logging.
• _docs/02_document/architecture.md — ADR-001, ADR-002, ADR-003, ADR-009.
• _docs/02_document/contracts/c4_pose/pose_estimator_protocol.md — ISam2GraphHandle Protocol stub source.
• _docs/02_document/module-layout.md — c5_state Per-Component Mapping.

Problem

Without this task, C4 has no concrete ISam2GraphHandle to inject (only the Protocol stub from AZ-355) — meaning the runtime root cannot wire C4 + C5 together. The DTO surface (EstimatorOutput, EstimatorHealth) is also consumed by C8, C13, and the orthorectifier — defining it once in _types/state.py prevents drift. The eight downstream consumer tasks (iSAM2 wiring, factor adds, marginals, spoof gate, ESKF, smoothed history, AC-5.2, orthorectifier) depend on the Protocol surface + the handle being available.

Outcome

• src/gps_denied_onboard/components/c5_state/interface.py — StateEstimator Protocol with all 6 methods.
• src/gps_denied_onboard/components/c5_state/__init__.py — re-exports StateEstimator, EstimatorOutput, EstimatorHealth.
• src/gps_denied_onboard/_types/state.py — EstimatorOutput, EstimatorHealth, IsamState enum (frozen + slots).
• src/gps_denied_onboard/components/c5_state/errors.py — error hierarchy.
• src/gps_denied_onboard/components/c5_state/_isam2_handle.py — concrete ISam2GraphHandleImpl(ISam2GraphHandle) class with all four methods. Body: empty stubs that raise NotImplementedError("iSAM2 wiring task owns this body") until AZ-382 lands. Each method's NotImplementedError message names the responsible task ID for traceability.
• src/gps_denied_onboard/runtime_root/state_factory.py — build_state_estimator(...) returning the tuple. Lazy-import per ADR-002.
• Composition-root extension: invoke build_state_estimator AFTER the shared helpers; pass the returned ISam2GraphHandle to build_pose_estimator (C4); bind C4 + C5 to the SAME ingest thread.
• Config schema extension for the five state.* fields.
• INFO log on successful build: kind="c5.state.strategy_loaded".

Scope

Included

• StateEstimator Protocol with 6 methods.
• DTOs (EstimatorOutput, EstimatorHealth, IsamState) in _types/state.py.
• Error hierarchy.
• Concrete ISam2GraphHandleImpl skeleton (body owned by AZ-382 iSAM2 wiring task).
• Composition-root factory + thread binding.
• Config schema extension.
• Unit tests: Protocol conformance, DTO immutability + slots, factory rejection on unknown strategy + missing build flag, ISam2GraphHandleImpl methods exist (return NotImplementedError), thread binding.

Excluded

• iSAM2 + IncrementalFixedLagSmoother body — owned by AZ-382 (next task).
• Factor adds (VIO + Pose + IMU) — owned by AZ-383.
• Marginals + outputs — owned by AZ-384.
• Source-label state machine + spoof gate — owned by AZ-385.
• ESKF baseline — owned by AZ-386.
• Smoothed-history → FDR — owned by AZ-387.
• AC-5.2 fallback — owned by AZ-388.
• Orthorectifier sub-path — owned by AZ-389.
• Component-internal acceptance tests C5-IT-01..07 + C5-PT-01 + C5-ST-01 — deferred to E-BBT (AZ-262).

Acceptance Criteria

AC-1: Protocol conformance — runtime_checkable isinstance returns True for a fake with all 6 methods.

AC-2: DTOs frozen + slots — FrozenInstanceError on mutation; __slots__ non-empty.

AC-3: IsamState enum has 4 values — INIT, TRACKING, DEGRADED, LOST.

AC-4: Factory rejects missing build flag — config.state.strategy = "nonexistent" → StateEstimatorConfigError("BUILD_STATE_NONEXISTENT is OFF...").

AC-5: Factory rejects unknown strategy at config-load — config.state.strategy = "garbage" → StateEstimatorConfigError at config load.

AC-6: Factory returns the tuple — both StateEstimator AND ISam2GraphHandle are returned from a successful build; INFO log with {strategy, keyframe_window_size}.

AC-7: Thread binding — composition root binds C5 to ONE ingest thread (the same as C4); second binding raises RuntimeError.

AC-8: ISam2GraphHandleImpl skeleton — instance is isinstance(handle, ISam2GraphHandle); calling add_factor, update, compute_marginals, last_anchor_age_ms each raises NotImplementedError(f"Body owned by ...") with the correct task ID in the message.

AC-9: Public API re-exports — from gps_denied_onboard.components.c5_state import StateEstimator, EstimatorOutput, EstimatorHealth resolves; internals not in __all__.

AC-10: Error hierarchy catchability — every error caught by except StateEstimatorError.

Non-Functional Requirements

• build_state_estimator p99 ≤ 50 ms.

Constraints

• @runtime_checkable on Protocol; DTOs frozen=True, slots=True.
• Lazy-import per ADR-002.
• Single-thread binding enforced (AC-7).
• The ISam2GraphHandleImpl skeleton's NotImplementedError messages MUST name the responsible task ID — AZ-382 iSAM2 wiring is the receiver.

Risks & Mitigation

• Risk: AZ-382 iSAM2 task lands before this task → cycle. Mitigation: this task ships first; AZ-382 imports ISam2GraphHandleImpl and replaces method bodies.
• Risk: AZ-355 stub Protocol may differ slightly from AZ-358's extension. Mitigation: this task verifies isinstance against the FINAL Protocol shape (post-AZ-358 extension) — both AZ-358 and this task update the Protocol stub in lockstep.

Runtime Completeness

• Named capability: StateEstimator Protocol + DTOs + factory + concrete ISam2GraphHandle skeleton.
• Production code: real Protocol, real DTOs, real error hierarchy, real factory, real ISam2GraphHandleImpl skeleton with NotImplementedError bodies, real composition wiring.
• Allowed external stubs: test fakes only.
• Unacceptable substitutes: hardcoding the C5 strategy class in C4's factory (defeats ADR-009); skipping the concrete ISam2GraphHandleImpl (would force AZ-382 iSAM2 wiring to also reshape Protocol).

Contract

Implements _docs/02_document/contracts/c5_state/state_estimator_protocol.md.