gps-denied-onboard/_docs/03_implementation/reviews/batch_76_review.md

Code Review Report

Batch: 76 — AZ-596 (fc_proxy_runtime driver, FDR-replay mode) Date: 2026-05-17 Verdict: PASS

Findings

(none)

Findings Sweep

Phase 1 — Context Loading

Read the AZ-596 task spec, the existing fixtures/injectors/fc_proxy.py (BlackoutSpoofProxy, SpoofGpsRecord, ProxyAlignmentReport, lifecycle methods), the FT-N-04 scenario's local _drive_fc_proxy stub and the surrounding call site, and the AZ-595 sitl_observer env-var pattern (E2E_SITL_REPLAY_DIR resolution via replay_dir()). Verified that BlackoutSpoofProxy.from_schedule_file already raises FileNotFoundError for missing input and json.JSONDecodeError for malformed JSON, so the runtime wrapper only needs to (a) convert JSONDecodeError → ValueError with a file pointer for symmetry with the rest of the helper layer and (b) project the proxy state into a small audit dataclass.

Phase 2 — Spec Compliance

AC	Coverage	Status
AC-1 (drive_fc_proxy loads schedule via BlackoutSpoofProxy.from_schedule_file; missing → FileNotFoundError; malformed → ValueError)	test_missing_schedule_raises_file_not_found, test_malformed_json_raises_value_error, test_happy_path_returns_well_formed_report	Covered
AC-2 (now_ms_provider supplied → proxy activated, alignment_err_ms recorded; absent → alignment_err_ms=0, was_replay_mode=True)	test_now_ms_provider_activates_proxy_and_reports_alignment, test_now_ms_provider_with_replay_mode_false_distinguishes_from_default, plus the was_replay_mode is True assertion in the happy-path test	Covered
AC-3 (replay_dir supplied OR E2E_SITL_REPLAY_DIR set → proxy_drive_report.json written; neither → no write)	test_writes_report_when_replay_dir_supplied, test_writes_report_when_env_var_set, test_explicit_replay_dir_overrides_env_var, test_no_file_written_when_neither_supplied, test_no_file_written_when_env_var_empty, test_replay_dir_is_created_when_missing	Covered
AC-4 (≥5 unit tests covering happy + 3 error/edge + 1 boundary)	11 tests total (3 schedule-load, 2 activation, 6 replay-dir write paths)	Covered (exceeds floor)
AC-5 (full suite passes)	608 passed (+12 from 596 baseline; +11 new tests + 1 layout parametrize entry)	Covered

Phase 3 — Code Quality

• Single responsibility: drive_fc_proxy owns three things and three things only — (a) construct a BlackoutSpoofProxy from a schedule path, (b) optionally activate it against a caller-supplied clock, (c) project the proxy state into ProxyDriveReport and optionally persist it. Each branch is straight-line.
• ProxyDriveReport is a frozen dataclass with seven plain fields — no methods, no factories. The dataclass IS the contract; downstream evaluators read it via asdict or per-field access.
• _resolve_replay_dir is the single env-var reader in this module. It mirrors the equivalent reader in sitl_observer.replay_dir (same env var, same "empty string → None" semantics) — the two modules deliberately do not import each other so the dependency surface stays one-way (fc_proxy_runtime → BlackoutSpoofProxy, fc_proxy_runtime → os.environ; nothing else).
• No suppressed errors: the one try/except block converts json.JSONDecodeError to a ValueError with the offending file path AND preserves the original via raise … from exc. No bare except, no 2>/dev/null, no empty pass.
• Public-accessor addition on BlackoutSpoofProxy: added three @property accessors (window_start_ms, window_end_ms, spoof_frame_count) so the runtime driver does NOT reach into private _window_start_ms / _spoof_gps attributes. The properties are pure, side-effect-free, single-line reads — they purely formalise the existing public read surface that from_schedule_file already establishes.
• AAA comment discipline: all 11 new tests use # Arrange / # Act / # Assert; sections omitted when not needed.
• No code comments narrate code — module docstring explains the FDR-replay rationale and the live-mode out-of-scope boundary. Per-function docstrings document the parameter contract.
• Public boundary: imports only stdlib (json, os, dataclasses, pathlib, typing) + fixtures.injectors.fc_proxy.BlackoutSpoofProxy (an existing test-side module). Zero from gps_denied_onboard ... imports.

Phase 4 — Security

• No new credentials, secrets, or network surface. The driver is pure file I/O over caller-supplied (or env-var-rooted) paths.
• E2E_SITL_REPLAY_DIR is read-only (consistent with AZ-595). Written paths use Path arithmetic — no string-interpolation into shell, no eval, no subprocess.
• JSON write path uses json.dumps(asdict(report)) — no opaque pickle, no untrusted deserialisation of caller input.
• replay_dir.mkdir(parents=True, exist_ok=True) silently creates intermediate directories. This is acceptable because the path comes from the test harness's own env var, not from external input.

Phase 5 — Performance

• O(1) work beyond the upstream BlackoutSpoofProxy.from_schedule_file load (which itself is O(N) in the number of spoof frames; the dataclass projection is constant-time using the new properties).
• No I/O at module-import time.
• The JSON write path is a single write_text call — atomic-enough for the audit-only use case.

Phase 6 — Cross-Task Consistency

• Env-var pattern matches AZ-595: the same E2E_SITL_REPLAY_DIR semantics (set → use; unset / empty / whitespace → ignore). A future fixture builder will set the env var once for the whole scenario run, and both sitl_observer (reads) + fc_proxy_runtime (writes the audit report) consume it from a single source of truth.
• ProxyDriveReport field names mirror the existing ProxyAlignmentReport in fc_proxy.py for alignment_err_ms. No name churn for the AC-3 / AC-NEW-3 evaluator that will eventually read it (blackout_spoof_evaluator already references alignment_err_ms from the proxy's own activation report).
• FileNotFoundError / ValueError discipline matches the rest of e2e/runner/helpers/ (per the b73-b75 cumulative review): missing inputs → FileNotFoundError, malformed inputs → ValueError with a file pointer.
• FT-N-04 scenario rewire: the local _drive_fc_proxy stub now imports runner.helpers.fc_proxy_runtime.drive_fc_proxy and calls it. The scenario's sitl_replay_ready skip gate (added in b75) continues to gate on E2E_SITL_REPLAY_DIR; the new helper writes its audit report into that same directory when the gate is open.

Phase 7 — Architecture Compliance

• Module placement: e2e/runner/helpers/fc_proxy_runtime.py (new)
  • e2e/_unit_tests/helpers/test_fc_proxy_runtime.py (new). Both registered in e2e/_unit_tests/test_directory_layout.py; the layout invariant test still passes.
• No src/gps_denied_onboard imports anywhere. Confirmed.
• No new top-level dependencies — stdlib only on the runner side; the test side adds nothing new. requirements.txt untouched.
• Backwards-compatible: the BlackoutSpoofProxy change is purely additive — three new @property accessors. Existing callers (the injector's own self-tests, the FT-N-04 fixture) keep working unchanged.

Test Results

• New unit tests: 11 (3 schedule load/error, 2 activation, 6 replay-dir write).
• Full e2e/_unit_tests suite: 608 passed in 124 s (previous cumulative: 596 → +12 net = +11 new fc_proxy_runtime tests + 1 new directory-layout parametrize entry).
• No new linter errors (ReadLints clean on fc_proxy_runtime.py, test_fc_proxy_runtime.py, fc_proxy.py, test_ft_n_04_blackout_spoof.py, test_directory_layout.py).