gps-denied-onboard/_docs/03_implementation/batch_17_cycle1_report.md

Batch 17 — Cycle 1 Implementation Report

Batch: 17 of N Tasks landed: AZ-385 (SourceLabelStateMachine + AC-NEW-2 / AC-NEW-8 spoof-promotion gate) Cycle: 1 Date: 2026-05-11

Scope

Task	Component	Purpose
AZ-385	C5 state estimator	Implements Invariant 5 (source_label reflects gate state) + Invariant 8 (spoof-rejection always lands in FDR + GCS STATUSTEXT, unsilenceable) + AC-NEW-2 / AC-NEW-8 (gate opens only when BOTH ≥10 s STABLE_NON_SPOOFED AND next anchor within tol_m). Adds a new SourceLabelStateMachine helper module owned by C5; the estimator constructs one eagerly per instance and exposes two new public surfaces — notify_gps_health(GpsHealth, now_ns=None) (forwarded from C8 inbound; transitions the gate latch + the stable-dwell timer) and subscribe_spoof_rejection(cb) -> RejectionSubscription (composition root wires C8's QgcTelemetryAdapter.send_statustext here so STATUSTEXT mirrors fire on the C8 outbound thread). health_snapshot.spoof_promotion_blocked is now backed by the live state machine; current_estimate.source_label likewise reflects the live label rather than the AZ-384-era hard-coded default. Every reject emits a c5.state.spoof_rejected FDR record AND a subscriber callback in the same call — both paths bypass the standard logger so silencing logs cannot suppress the spoof trail (R07 / AC-6).

Files added / modified

Added (prod)

• src/gps_denied_onboard/components/c5_state/_source_label_sm.py — new SourceLabelStateMachine class. Public read API: current_label(), is_spoof_promotion_blocked(). Public write API: notify_gps_health(gps_health, now_ns=None) (transitions _promotion_blocked on first SPOOFED, starts the dwell timer on transition to STABLE_NON_SPOOFED, clears it on any other status), notify_satellite_anchor(now_ns, gps_consistency_delta_m) (updates _last_anchored_frame_ns; while blocked, tries to lift the gate using the BOTH-conditions test, otherwise emits a c5.state.spoof_rejected FDR record + subscriber fan-out). Subscription API: subscribe_rejection(cb) -> RejectionSubscription with cancellable handle. Internal label rules: DEAD_RECKONED until first anchor → SATELLITE_ANCHORED if gate open AND anchor < 1 s old → VISUAL_PROPAGATED otherwise. Threading: explicit threading.Lock around every state mutation; subscriber callbacks dispatched OUTSIDE the lock so a slow subscriber doesn't block writers.

Modified (prod)

• src/gps_denied_onboard/components/c5_state/gtsam_isam2_estimator.py — three changes: (1) the constructor now eagerly builds a SourceLabelStateMachine from C5StateConfig.spoof_promotion_min_stable_s and spoof_promotion_visual_consistency_tol_m and the injected fdr_client; (2) add_pose_anchor on the MARGINALS path now calls a new internal helper _notify_source_label_anchor(pose) that forwards the anchor to the SM with gps_consistency_delta_m=None (the visual-vs-GPS delta will be supplied by AZ-389 orthorectifier or the composition root once that wiring lands); (3) new public methods notify_gps_health(gps_health, now_ns=None) (delegates to the SM) and subscribe_spoof_rejection(callback) -> RejectionSubscription (delegates; raises StateEstimatorConfigError if attach_source_label_state_machine was used with a stub that lacks the subscription surface). The pre-existing attach_source_label_state_machine injection point is preserved and re-documented as a test-only override (production code uses the eagerly-built instance).

Added (tests)

• tests/unit/c5_state/test_az385_source_label_spoof_gate.py — 25 tests across all 12 ACs plus subscription cancellation, subscriber-exception isolation, and three estimator-wire-up integration tests. Uses a deterministic synthetic _Clock (no real wall-clock dependence). Mocks the SM's logger via mock.patch.object to prove AC-6 — FDR and subscriber paths fire even when every logger.* call is a no-op. The estimator integration tests use the same _seed_prior helper pattern from AZ-388 to seed a minimal iSAM2 prior so current_estimate returns without raising.

Modified (tests)

• tests/unit/c5_state/test_az384_marginals_outputs.py — test_ac9_default_source_label_is_visual_propagated renamed to test_ac9_default_source_label_is_dead_reckoned_before_any_anchor and updated to expect DEAD_RECKONED. The previous behaviour (no SM attached → VISUAL_PROPAGATED) was an AZ-384-era placeholder; AZ-385 supersedes it by attaching the real SM eagerly. Inline comment cites AC-1 of AZ-385 + Invariant 5 for traceability.

Architectural notes

• Eager construction over lazy injection — AZ-384 left _source_label_machine as Any | None with attach_source_label_state_machine as the wiring seam, on the theory that AZ-385 would own the actual machine instance. With the SM now landed, eagerly constructing it in __init__ removes the "is it attached yet?" branch from every read path AND lets health_snapshot.spoof_promotion_blocked return a meaningful answer from the very first call. attach_source_label_state_machine stays available as a test-only override (one test exercises it; see test_estimator_subscribe_after_attach_with_stub_raises).
• Subscriber pattern over direct GCS dependency — same shape as AZ-388's FallbackWatcher.subscribe_engaged. The C5 estimator does NOT take a GcsAdapter in its constructor; instead C8's QgcTelemetryAdapter registers itself via subscribe_spoof_rejection at composition time. This keeps the C5 module's import graph free of C8 dependencies and matches the contract's "C8 owns the STATUSTEXT broadcast wire" phrasing.
• Unsilenceable logging path (R07 / AC-6) — both the FDR record and the subscriber fan-out go through dedicated methods (FdrClient.enqueue, direct callback invocation) that do NOT touch the logging module's filter chain. The informational c5.state.spoof_rejected WARN log is emitted AFTER both side-effects, so even if every logger.* call is monkey-patched to a no-op, the FDR + STATUSTEXT trail still lands. Verified by test_ac6_silenced_logger_does_not_suppress_fdr_or_subscriber.
• BOTH-conditions promotion (AC-NEW-2 / AC-NEW-8) — the gate is lifted ONLY when (now - _gps_health_stable_since_ns) >= min_stable_ns AND gps_consistency_delta_m is not None AND <= consistency_tol_m. Each condition is tested in isolation (test_ac5_only_stable_dwell_does_not_lift_block, test_ac5_only_consistency_does_not_lift_block) — the AND semantics are not paraphrased into OR by accident.
• Default gps_consistency_delta_m=None from the estimator — the production wire-up cannot compute the visual-vs-GPS delta yet (AZ-389 orthorectifier supplies the rectified ENU position for cross-check; the composition root will own the comparison once that task lands). Until then, ALL in-block anchor attempts emit a reject for no_gps_observation — which is the conservative + correct behaviour (you can't unblock until you have evidence). When AZ-389 lands, the composition root will replace the gps_consistency_delta_m=None call with the real delta and the dwell+consistency AND-test will be exercised end-to-end.
• Anchor-staleness threshold = 1 s — encoded as a module-level constant _ANCHOR_STALENESS_THRESHOLD_MS = 1000 rather than a new config field. The C5 contract's "Config schema additions" section already enumerates the fields the operator may tune; adding a sixth field for an internal SM-only decision would be over-configuration. Documented in the module docstring.
• STATUSTEXT cap at 50 chars (AC-12) — the formatter pre-caps the message to 50 chars in _format_statustext; reason tokens (gps_spoofed, dwell_short, consistency, no_gps_obs) are intentionally short so the full "GPS spoof rejected: <reason>" fits without truncation in the common case.
• Reject-reason classification ladder — the four reasons cover the four possible failure modes of the AND-test: GPS still SPOOFED (highest-priority — never check anything else), no GPS observation at all (gps_consistency_delta_m is None), dwell insufficient, consistency violation. The ladder is deterministic; tests assert on the reason string per case.

Test counts

Suite	Before (B16)	After (B17)	Delta
Total passing	607	632	+25
Skipped	2	2	0
AZ-385 (new)	0	25	+25
AZ-384 (preserved)	27	27	0 (test renamed + flipped expectation; count unchanged)

Run command: PYTHONPATH=src pytest tests/ -q → 632 passed, 2 skipped in ~32s.

Lint / type

• ruff check src/gps_denied_onboard/components/c5_state/ tests/unit/c5_state/ — clean after one auto-fix (import order in gtsam_isam2_estimator.py).
• ruff format — 1 file reformatted, 3 already formatted; second pass clean.
• ReadLints on touched files — 0 errors.

Acceptance evidence

AC	Test(s)	Status
AC-1 Initial label DEAD_RECKONED	test_ac1_initial_label_is_dead_reckoned, test_ac1_initial_label_remains_dead_reckoned_after_gps_only	PASS
AC-2 First anchor → SATELLITE_ANCHORED	test_ac2_first_anchor_promotes_to_satellite_anchored, test_ac2_first_anchor_when_blocked_emits_reject	PASS
AC-3 Stale anchor → VISUAL_PROPAGATED	test_ac3_stale_anchor_falls_back_to_visual_propagated	PASS
AC-4 Spoof detection latches + emits reject	test_ac4_spoofed_status_latches_gate_closed, test_ac4_reject_fires_subscriber_callback, test_ac4_reject_fires_fdr_record	PASS
AC-5 BOTH conditions required	test_ac5_only_stable_dwell_does_not_lift_block, test_ac5_only_consistency_does_not_lift_block, test_ac5_both_conditions_lift_block	PASS
AC-6 Logging cannot be silenced	test_ac6_silenced_logger_does_not_suppress_fdr_or_subscriber	PASS
AC-7 is_spoof_promotion_blocked()	test_ac7_block_query_reflects_latch	PASS
AC-8 health_snapshot.spoof_promotion_blocked wired	test_ac8_health_snapshot_reflects_spoof_block	PASS
AC-9 Configurable thresholds	test_ac9_min_stable_30s_shifts_dwell_window, test_ac9_consistency_tol_5m_rejects_15m_delta	PASS
AC-10 Label-change INFO log	test_ac10_label_change_emits_info_log	PASS
AC-11 Reject FDR record shape	test_ac11_reject_fdr_record_shape	PASS
AC-12 STATUSTEXT severity + 50-char cap	test_ac12_statustext_severity_is_warning, test_ac12_statustext_max_50_chars	PASS
Subscription cancellation	test_subscription_cancel_stops_callbacks	PASS
Subscriber exception isolation	test_subscriber_exception_does_not_break_state_machine	PASS
Estimator wire-up — label flows	test_estimator_current_estimate_label_reflects_sm	PASS
Estimator wire-up — subscription delegates	test_estimator_subscribe_spoof_rejection_returns_handle	PASS
Stub injection raises on subscribe	test_estimator_subscribe_after_attach_with_stub_raises	PASS

Known gaps / followups

• Visual-vs-GPS consistency delta — currently the estimator passes None on every anchor notification. AZ-389 (orthorectifier → C6) will supply the rectified ENU position; the composition root will then compute the delta against the FC GPS WGS84 → ENU position and pass it in via a new method (likely notify_visual_consistency on the SM). Until that lands the BOTH-conditions test always falls into the no_gps_observation reject reason, which is the conservative + safe default.
• ESKF wire-up — EskfStateEstimator (AZ-386) needs the same SM wire-up (one constructor line + the add_pose_anchor hook). Per the AZ-385 contract "both estimators participate"; the AZ-386 wire-up cost will be a single line each.
• C5-IT-06 / C5-IT-07 / C5-ST-01 — scoped out per AZ-385 § Excluded; live in E-BBT.
• C8 outbound STATUSTEXT subscription — AZ-261 will register the C8 QgcTelemetryAdapter via subscribe_spoof_rejection at composition time. AZ-385 only exposes the subscription point.

Risks accepted

• SM lock contention under high anchor rate — anchor cadence is bounded by D-C5-3 (~3 Hz worst case); lock-acquire is microseconds. Verified informally; if profiling reveals contention later we can swap to a CAS pattern or split into a state-machine-per-input.
• gps_consistency_delta_m=None always rejecting under spoof — by design until AZ-389 lands. The conservative behaviour is "stay blocked until evidence proves otherwise", which is exactly what R07 wants.