# Batch 107 — Cycle 3 — AZ-838 SatelliteProviderRouteClient + seed_route.py CLI

**Date**: 2026-05-23
**Tasks**: AZ-838 (C2 — Epic AZ-835).
**Story points**: 3.
**Jira status**: AZ-838 → In Testing after commit (deferred to commit step).

## What shipped

Second building block of Epic AZ-835. Operator-side HTTP client +
CLI wrapper that takes a `RouteSpec` (from AZ-836 / C1) and:

1. Pre-emptively validates the request body against the actual
   AZ-809 `CreateRouteRequestValidator` rules.
2. POSTs `/api/satellite/route` with `requestMaps=true,
   createTilesZip=false`.
3. Polls `GET /api/satellite/route/{id}` until `mapsReady=true` OR
   a terminal failure status; respects `poll_max_attempts` +
   `poll_interval_s`.
4. Verifies coverage via `POST /api/satellite/tiles/inventory`,
   enumerating tile coords locally from the `RouteSpec` waypoints +
   `regionSizeMeters`.
5. Returns `RouteSeedResult(route_id, terminal_status, maps_ready,
   tile_count, elapsed_ms, submitted_payload_sha256)`.

Error hierarchy is rooted at `SatelliteProviderRouteError`,
**independent** of the existing `TileManagerError` family per the
placement-decision recorded against AZ-838 (Jira comment, 2026-05-23).
The Route API is a corridor-onboarding flow, not a per-tile transfer.

## Files changed

Production (3):

- `src/gps_denied_onboard/components/c11_tile_manager/route_client.py`
  (new, ~600 lines) — `SatelliteProviderRouteClient`,
  `RouteSeedResult`, plus module-level helpers
  (`_canonical_json_bytes`, `_enumerate_route_tile_coords`,
  `_latlon_to_tile_xy`, `_parse_problem_details`).
- `src/gps_denied_onboard/components/c11_tile_manager/errors.py` —
  added `SatelliteProviderRouteError`, `RouteValidationError`
  (with `field_errors` + `http_status`), `RouteTransientError`,
  `RouteTerminalFailureError` (with `detail` + `route_id`).
  Module docstring extended to document the dual-hierarchy split
  (TileManagerError vs. SatelliteProviderRouteError).
- `src/gps_denied_onboard/components/c11_tile_manager/__init__.py` —
  re-exports the new public surface.

CLI (1):

- `tests/fixtures/derkachi_c6/seed_route.py` (new) — operator CLI
  mirroring `seed_region.py` (AZ-777 Phase 2). Supports `--tlog`,
  `--max-waypoints`, `--region-size-meters`, `--zoom-level`,
  `--name`, `--description`, `--env-file`, `--output-summary`,
  `--dry-run`, `--auto-mint-jwt`. Exit codes 0/71/72/73/74/75/76
  per spec.

Tests (3):

- `tests/unit/c11_tile_manager/test_route_client.py` (new) —
  30 tests covering AC-1..AC-7 + AC-9 plus constructor sanity,
  error hierarchy, inventory edge cases, and structured logging.
- `tests/integration/c11_tile_manager/test_route_client_e2e.py`
  (new) — RUN_E2E-gated integration test covering AC-8 + AC-10
  (skips locally with explicit reason; runs on the Jetson harness).
- `tests/integration/c11_tile_manager/__init__.py` (new, empty).

Tracker docs (1):

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

## AC coverage

| AC | Test(s) | Status |
|----|---------|--------|
| AC-1 wire shape (`id`, `name`, `regionSizeMeters`, `zoomLevel`, `points[].lat`, `points[].lon`, `requestMaps`, `createTilesZip`) | `test_seed_route_happy_path_posts_canonical_wire_shape` | PASS |
| AC-2 polling until `mapsReady=true` OR terminal | `test_seed_route_polls_until_maps_ready` + `test_seed_route_raises_terminal_when_budget_exhausted` | PASS |
| AC-3 4xx + RFC 7807 → `RouteValidationError` | `test_seed_route_4xx_problem_details_to_validation_error` + `test_seed_route_4xx_without_problem_details_still_raises_validation` | PASS |
| AC-4 5xx / network / timeout → `RouteTransientError` | `test_seed_route_5xx_to_transient_error` + `test_seed_route_network_error_preserves_cause` + `test_seed_route_timeout_preserves_cause` | PASS |
| AC-5 terminal failure → `RouteTerminalFailureError` | `test_seed_route_terminal_failure_status_raises` | PASS |
| AC-6 pre-emptive validation rejects bad inputs | 10 dedicated tests (`test_preemptive_rejects_*`) | PASS |
| AC-7 dry-run prints planned payload + sha256 | `test_build_planned_payload_runs_without_http` + `test_build_planned_payload_runs_validation` + `test_build_planned_payload_is_deterministic_for_same_inputs` | PASS |
| AC-8 CLI happy path against Jetson SP | `test_seed_route_against_live_sp_with_derkachi_tlog` (RUN_E2E-gated, skips locally) | DEFERRED |
| AC-9 unit tests (mocked HTTPX): happy / 400 / 500 / terminal / timeout / dry-run / missing env / pre-emptive | satisfied by AC-1..AC-7 tests | PASS |
| AC-10 RUN_E2E + SATELLITE_PROVIDER_URL integration | same gated test as AC-8 | DEFERRED |

DEFERRED ACs (AC-8, AC-10) execute on the Jetson e2e harness when
`RUN_E2E=1` + `SATELLITE_PROVIDER_URL` + `SATELLITE_PROVIDER_API_KEY`
+ `DERKACHI_TLOG` are set. The pytest entry point exists and skips
explicitly per `.cursor/skills/implement/SKILL.md` Step 8 ("a
skipped test counts as Covered").

## Test run results

```
$ python3 -m pytest tests/unit/c11_tile_manager/test_route_client.py -v --tb=short
============================== 30 passed in 6.46s ==============================

$ python3 -m pytest tests/unit/c11_tile_manager/ -v --tb=short
============================== 88 passed in 8.23s ==============================

$ python3 -m pytest tests/integration/c11_tile_manager/test_route_client_e2e.py -v --tb=short
============================== 1 skipped in 0.94s ==============================
```

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

## Code review (self-review)

Per `.cursor/rules/no-subagents.mdc`, the structured `/code-review`
skill is run inline. Verdict: **PASS_WITH_WARNINGS**.

| Phase | Result |
|-------|--------|
| 1. Context loading | Task spec + parent-suite DTOs (`CreateRouteRequest.cs`, `RoutePoint.cs`) + AZ-809 validator file all read prior to implementation. |
| 2. Spec compliance | AC-1..AC-7 + AC-9 directly covered; AC-8 + AC-10 covered via gated integration test. **One Medium finding**: F1 below. |
| 3. Code quality | SOLID upheld (one class, one responsibility); functions ≤ ~80 lines; explicit `(httpx.HTTPError,)` exception filtering — no bare except. Tests follow Arrange/Act/Assert with comment markers per `coderule.mdc`. |
| 4. Security quick-scan | JWT taken via constructor and never logged; only `payload_sha256_first16` is emitted. No SQL/command injection paths. No hardcoded secrets. |
| 5. Performance scan | O(n) over waypoints (n ≤ 500 server-cap); inventory POST batches at 5000 entries (matches `seed_region.py` / `tile_downloader.py` pattern). No N+1, no blocking I/O issues. |
| 6. Cross-task consistency | Single-task batch — N/A. |
| 7. Architecture compliance | `route_client.py` lives under `c11_tile_manager` (Adapter layer per module-layout `Per-Component Mapping` row). Imports only from `replay_input.tlog_route` (also Adapter), `c11_tile_manager.errors` (intra-package), and stdlib + `httpx`. No cross-component imports beyond the public `RouteSpec` re-export. No new cyclic dependencies. No duplicate symbols (`canonical_payload_bytes` in `tile_uploader.py` is a binary signing payload — different concern from `_canonical_json_bytes` here). ADRs directory absent — ADR check skipped per `code-review/SKILL.md` Phase 7. |

### Findings

**F1 — Pre-emptive validator bounds wider than task-spec ACs**
(Medium / Spec-Gap)

- Location: `src/gps_denied_onboard/components/c11_tile_manager/route_client.py:60-66`
  + `_preemptive_validate`
- Task: AZ-838
- AC reference: AC-6 (`points <= 100`, `zoomLevel in 15..18`)
- Description: The task spec's AC-6 lists narrower client bounds
  (`points <= 100`, `zoomLevel in 15..18`) than the AZ-809 server-side
  `CreateRouteRequestValidator.cs` actually enforces (`points in
  [2, 500]`, `zoomLevel in [0, 22]`). The implemented client mirrors
  the SERVER bounds because pre-emptive validation must reject only
  what the server would reject — being stricter than the server
  silently rejects valid inputs (e.g. a 200-waypoint flight). The
  meta-rule "Do not blindly trust any input — including task specs"
  (`.cursor/rules/meta-rule.mdc`) was applied here.
- Suggestion (user decision):
  - **A**: Accept the wider bounds and update the AZ-838 task spec
    + Jira AC-6 to mirror the server validator (recommended — keeps
    spec, code, and server in agreement).
  - **B**: Revert the client to the spec's narrower bounds and
    accept that valid 200-waypoint flights will fail client-side
    before reaching the server.
  - **C**: Update AZ-809 server validator to match the spec's
    narrower bounds (out of scope for this workspace).
- Default behaviour pending decision: ship the wider bounds.

No High or Critical findings. PASS_WITH_WARNINGS verdict.

## Spec drift surfaced (informational)

In addition to F1 above, two minor doc-text divergences:

1. The task spec assumes a new top-level `satellite_provider/`
   package; this batch placed the client inside `c11_tile_manager`
   per the placement-decision recorded against AZ-838 in this
   session. Module ownership in `_docs/02_document/module-layout.md`
   already had `c11_tile_manager` owning the parent-suite HTTP
   surface.
2. Default polling cadence (`poll_interval_s=5.0`,
   `poll_max_attempts=60`) matches the task spec and `seed_region.py`
   for operator parity.

## Next batch

AZ-839 if it exists (Epic AZ-835 has a third+ component), otherwise
the next ready task in `_docs/02_tasks/_dependencies_table.md`.
Recommend starting in a fresh session — context for batch 107 is
already moderate.