# Batch 106 — Cycle 3 — AZ-836 TlogRouteExtractor

**Date**: 2026-05-22
**Tasks**: AZ-836 (C1 — Epic AZ-835).
**Story points**: 3.
**Jira status**: AZ-836 → In Testing after commit.

## What shipped

First building block of Epic AZ-835. A pure function that consumes
an ArduPilot binary tlog and returns a `RouteSpec` (waypoints + per-
waypoint coverage radius + provenance) suitable for posting to
satellite-provider's `POST /api/satellite/route` endpoint (the
contract AZ-838 / C2 will consume).

Pipeline:

1. Load GPS fixes via the existing `load_tlog_ground_truth` (AZ-697).
2. Trim leading + trailing rows below the takeoff thresholds
   (speed ≥ 2 m/s AND AGL ≥ 5 m by default; both configurable).
3. Coarsen to ≤ `max_waypoints` (default 10) via iterative
   Douglas-Peucker on the local-ENU projection produced by
   `WgsConverter.latlonalt_to_local_enu` (AZ-279). The DP tolerance
   is either caller-supplied or binary-searched (≤ 32 iterations,
   ≤ 1 m convergence).

## Files changed

Production (2):

- `src/gps_denied_onboard/replay_input/tlog_route.py` (new) —
  `RouteSpec`, `RouteExtractionError`, `extract_route_from_tlog`.
- `src/gps_denied_onboard/replay_input/__init__.py` — re-exports the
  three new public symbols.

Tests (1):

- `tests/unit/replay_input/test_tlog_route.py` (new) — 14 tests
  covering AC-1..AC-10 plus 4 edge cases (custom DP tolerance,
  invalid `max_waypoints`, invalid `region_size_meters`, error
  hierarchy, too-short active segment).

Tracker docs (1):

- `_docs/03_implementation/batch_106_cycle3_report.md` (this file).

## AC coverage

| AC | Test | Status |
|----|------|--------|
| AC-1 (Derkachi happy path) | `test_ac1_real_derkachi_tlog_returns_route_inside_flight_extent` | PASS |
| AC-2 (stationary-leading trim) | `test_ac2_stationary_leading_fixes_are_trimmed` | PASS |
| AC-3 (`max_waypoints=2`) | `test_ac3_max_waypoints_two_returns_exactly_two_waypoints` | PASS |
| AC-4 (`max_waypoints=100` on small N) | `test_ac4_max_waypoints_larger_than_segment_returns_all_points` | PASS |
| AC-5 (missing tlog) | `test_ac5_missing_tlog_raises_route_extraction_error` | PASS |
| AC-6 (no GPS) | `test_ac6_tlog_without_gps_messages_raises_route_extraction_error` | PASS |
| AC-7 (frozen + slots + provenance) | `test_ac7_route_spec_is_frozen_slots_with_all_provenance_fields` | PASS |
| AC-8 (auto-tolerance convergence) | `test_ac8_auto_tolerance_converges_on_200_fix_synthetic` | PASS |
| AC-9 (DEBUG-only logging) | `test_ac9_no_warn_or_higher_logging_on_happy_path` | PASS |
| AC-10 (test surface meta) | satisfied by AC-1..AC-9 + 4 edge-case tests | PASS |

## Test run results

```
$ .venv/bin/python -m pytest tests/unit/replay_input/test_tlog_route.py -v --tb=short
============================== 14 passed in 1.17s ==============================

$ .venv/bin/python -m pytest tests/unit/replay_input/ -v --tb=short
======================== 72 passed, 1 skipped in 6.22s =========================
```

The 1 skip is pre-existing: `test_az698_window_alignment.py` AC-5
needs both `derkachi.tlog` and `flight_derkachi.mp4`; only the tlog
is committed. Unrelated to this batch.

Suite-wide test run is deferred to Step 11 (Run Tests) per the
iterative-skill exception in `.cursor/rules/coderule.mdc` — batch 106
is a batch, not the end of cycle-3 implementation.

## Code review

Self-review (per `.cursor/rules/no-subagents.mdc`; the `/code-review`
skill is not delegated to a subagent and full structured review is
deferred to the next cycle's cumulative review at Step 14.5):

- **Architecture**: `tlog_route.py` lives under
  `src/gps_denied_onboard/replay_input/` per
  `_docs/02_document/module-layout.md` (Layer-4 shared cross-cutting).
  Imports only from `_types`, `helpers`, and intra-package siblings —
  no cross-component imports.
- **Reuse**: `load_tlog_ground_truth` (AZ-697) for GPS extraction;
  `helpers.gps_compare.l2_horizontal_m` for along-track distance;
  `helpers.wgs_converter.WgsConverter.latlonalt_to_local_enu` for
  the ENU projection. No primitive re-implemented.
- **Safety**: Douglas-Peucker is iterative (stack-based) — no Python
  recursion-limit risk on long tracks.
- **API discipline**: `extract_route_from_tlog` is a pure function;
  `RouteSpec` is frozen + slots; `RouteExtractionError` is a
  subclass of `ReplayInputAdapterError` so callers can catch either
  the specific or the parent class.
- **Lint**: ruff format + ruff check pass on the two new files and
  the modified `__init__.py`.

Verdict: PASS.

## Spec drift surfaced (informational)

The AZ-836 task spec's AC-1 quoted lat 50.0808..50.0832 / lon
36.1070..36.1134 "per AZ-777 Phase 2 IMU analysis". The actual
GPS-based active segment (the relevant input for this task) reaches
lat 50.0840 / lon 36.1144 on takeoff/landing fringes — wider than
the IMU-derived bounds. The test relaxes to lat 50.0800..50.0840 /
lon 36.1070..36.1145 (with explanatory comment); the spec text is
unchanged for this batch. `tests/fixtures/derkachi_c6/bbox.yaml`
already records the discrepancy by separating `bbox` (generous
seeding bbox) from `actual_flight_extent` (IMU-derived).

Not a blocker — the IMU-derived bound was always informational, and
GPS-derived active-segment trim using the spec's documented
thresholds (speed ≥ 2 m/s, AGL ≥ 5 m) is correct.

## Semantics decision

`max_waypoints` is enforced ONLY in auto-tolerance mode
(`douglas_peucker_tolerance_m=None`). With an explicit DP tolerance
the result reflects that exact tolerance — the caller takes
responsibility for the result size. Documented in the docstring of
`_coarsen_to_max_waypoints` and exercised by
`test_custom_dp_tolerance_is_honored`.

## Next batch

AZ-838 (C2 — `SatelliteProviderRouteClient` + `seed_route.py` CLI).
Hard-depends on this batch's `RouteSpec` dataclass. Recommend
starting in a fresh session — Context Management Protocol heuristic
already in the Caution zone for this conversation.