[AZ-895] Deprecate replay auto-sync surface; file AZ-908 follow-up

Option A (minimum-deprecation, 2 SP) per user complexity-budget
decision. Auto-sync stays importable as a raising stub for one cycle
so external callers see a clean ReplayInputAdapterError instead of an
ImportError. Full physical removal is filed as AZ-908 (cycle-5+ backlog).

Production:
- auto_sync.py: 700+ LOC -> 56-line no-op stub raising
  "auto-sync removed; supply --imu CSV instead"
- tlog_video_adapter.py: 700+ LOC -> 105-line deprecated stub;
  ReplayInputAdapter.open() raises immediately, close() is a no-op
- _replay_branch.py: dropped legacy auto-sync branch +
  _build_auto_sync_config; _validate_replay_paths now requires
  imu_csv_path; replay_input_adapter_factory parameter removed
- cli/replay.py: --time-offset-ms / --skip-auto-sync / --auto-trim
  emit DeprecationWarning + stderr line; values ignored
- tlog_replay_adapter.py + tlog_ground_truth.py docstrings: AUDIT-ONLY

Tests:
- DELETED test_az405_auto_sync, test_az405_replay_input_adapter,
  test_az698_window_alignment (covered code no longer runs)
- ADDED test_az895_auto_sync_deprecated_stub (5 parametrised, pins AC-1)
- test_az402_replay_cli: deprecation warnings + ignored-value asserts
- test_az401_compose_root_replay: new imu_csv_path-required gate;
  deleted the calibration-loading test that relied on the removed
  replay_input_adapter_factory injection point
- test_derkachi_real_tlog: xfail reason refreshed to AZ-848 + AZ-883
  (AC-4 "AZ-848-scoped reason")

Docs:
- module-layout.md: replay_input file list flags deprecated modules,
  adds csv_ground_truth.py
- _dependencies_table.md: +AZ-908 row, preamble + totals updated
  (179 -> 180 tasks, 567 -> 570 SP)
- AZ-908 backlog spec added; AZ-895 spec moved todo -> done
- batch_03_cycle4_report.md written

Touched-module tests green (111 passed, 1 skipped). Full unit suite
green: 2287 passed, 85 skipped, 1 deselected (pre-existing flaky perf
test, unrelated).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-26 22:09:59 +03:00
parent fdb593a775
commit 007aa36fbf
19 changed files with 600 additions and 4213 deletions
@@ -1,18 +1,26 @@
"""``TlogReplayFcAdapter`` (AZ-399 / E-DEMO-REPLAY).
Replay-only :class:`FcAdapter` strategy parsing pymavlink ``.tlog``
files. Implements the full Protocol from
AUDIT-ONLY (AZ-895): retained as a tlog-file parser strategy that
implements the :class:`FcAdapter` Protocol. The production replay
pipeline now composes :class:`CsvReplayFcAdapter` against the
operator's IMU+GPS CSV (AZ-894). This adapter remains in the tree as:
- The source of :class:`ReplayPace` (shared enum used by every replay
adapter and the composition root).
- A one-off audit utility for inspecting historical ``.tlog`` files
outside the main replay flow.
It is no longer instantiated by :func:`compose_root`'s replay branch
and AZ-908 will retire the ``BUILD_TLOG_REPLAY_ADAPTER`` build flag
that still guards its construction.
Implements the full Protocol from
``_docs/02_document/contracts/c8_fc_adapter/fc_adapter_protocol.md``
plus the replay-specific Invariants 5, 6, 8 from
``_docs/02_document/contracts/replay/replay_protocol.md`` (no
out-bound emission, pace honoured by injected :class:`Clock`,
``time_offset_ms`` shift baked at construction).
Build-time gating: the adapter refuses construction unless
``BUILD_TLOG_REPLAY_ADAPTER`` is ``ON``. Only the ``replay-cli``
binary is expected to flip the flag ON; airborne / research /
operator binaries keep it OFF.
Stream-parse design: pymavlink's :class:`mavutil.mavlogfile` already
streams from disk via :meth:`recv_match`. The adapter wraps it in a
pre-scan pass (fail-fast on missing required message types per