[AZ-777] Phase 1: wire e2e-runner to real satellite-provider + C11 contract adapt

Adapt C11 HttpTileDownloader to the AZ-505 v1.0.0 tile-inventory
contract (POST /api/satellite/tiles/inventory + GET /tiles/{z}/{x}/{y})
and wire the Jetson e2e harness against the real parent-suite
satellite-provider service. Closes Phase 1 of 5 for AZ-777; STOP
gate before Phase 2 (Derkachi catalog seed).

C11 changes:
- _LIST_PATH / _GET_PATH replaced with _INVENTORY_PATH + _TILES_PATH.
- _do_enumerate enumerates bbox tile coords client-side and posts
  chunked inventory requests (5000-entry cap per the contract).
- _download_one_tile parses tile_id_str into (z,x,y) and fetches
  the slippy-map URL.
- Common GET / POST retry+auth ladder consolidated into _send_request.
- New module helpers: _enumerate_bbox_tile_coords,
  _tile_center_latlon, _tile_size_meters_at, _format_tile_id_str,
  _parse_tile_id_str, _chunk_iter.
- _DEFAULT_ESTIMATED_TILE_BYTES (50 KiB) replaces the inventory-side
  estimatedBytes field the v1.0.0 contract dropped.

Tests:
- 14/14 unit tests in tests/unit/c11_tile_manager/test_tile_downloader.py
  rewritten for the new POST inventory + slippy-map GET handler.
  _StubTileWriter rekeyed by call-index (the downloader now derives
  lat/lon from the slippy-map coord, so fixtures can't fabricate
  arbitrary positions).
- New Tier-2 smoke at tests/e2e/satellite_provider/test_smoke.py:
  validates inventory POST schema + drives HttpTileDownloader against
  the real service. Gated by RUN_REPLAY_E2E=1 + tier2.

Compose / env:
- e2e-runner SATELLITE_PROVIDER_URL switched from mock-sat:5100 to
  https://satellite-provider:8080; TLS_INSECURE + Bearer JWT env +
  depends_on satellite-provider added.
- .env.test.example documents SATELLITE_PROVIDER_API_KEY + dev TLS
  bypass security note.
- scripts/mint_dev_jwt.py mints HS256 dev JWTs from env / .env.test.
- pyjwt added to dev extras.

Tracker hygiene:
- AZ-777 row in _dependencies_table.md bumped 5pt -> 8pt to match
  the 2026-05-21 override decision log.

Code review: PASS_WITH_WARNINGS (3 medium/low findings, all deferred
to later AZ-777 phases) -- see batch_104_review.md. Batch report at
batch_104_cycle3_report.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-21 14:52:39 +03:00
parent 544b37fdc9
commit 811b04e605
12 changed files with 1328 additions and 190 deletions
@@ -0,0 +1,120 @@
# Batch 104 — Cycle 3 — AZ-777 Phase 1
**Date**: 2026-05-21
**Tasks**: AZ-777 Phase 1 (e2e-runner wire + C11 contract adapt + smoke test).
**Story points**: 8 (explicit override; see decision log).
**Jira status**: AZ-777 → still `In Progress` — Phase 1 of 5 done; STOP gate before Phase 2.
## What shipped
The Jetson e2e harness now consumes the **real** parent-suite
`satellite-provider` .NET service over its compose-DNS name +
self-signed dev TLS cert + Bearer JWT auth. C11's
`HttpTileDownloader` has been adapted to the AZ-505 v1.0.0
`tile-inventory.md` contract — bulk POST inventory lookup keyed by
slippy-map (z,x,y) coords, plus per-tile GET via
`/tiles/{z}/{x}/{y}`. A Tier-2 smoke test exercises the wire
end-to-end against the running service.
This batch closes the first of AZ-777's five explicit STOP-gated
phases. Phases 25 remain on the to-do queue:
- Phase 2 — Derkachi tile catalog seed via
`POST /api/satellite/request` (CC-BY basemap source, license
attribution baked in).
- Phase 3 — replace the placeholder `operator_pre_flight_setup`
fixture with a real C10 + C11 driver that yields a
`PopulatedC6Cache`.
- Phase 4 — un-xfail the Tier-2 Derkachi AC-3 + AZ-699 verdict
tests.
- Phase 5 — extend the replay-protocol / architecture / Derkachi
README docs.
## Files changed
Production (1):
- `src/gps_denied_onboard/components/c11_tile_manager/tile_downloader.py`
Tests (3):
- `tests/unit/c11_tile_manager/test_tile_downloader.py` (rewritten;
14 AC tests; all PASS)
- `tests/e2e/satellite_provider/__init__.py` (new)
- `tests/e2e/satellite_provider/test_smoke.py` (new; 2 tier2 tests)
Compose / env (2):
- `docker-compose.test.jetson.yml`
- `.env.test.example`
Tooling (2):
- `scripts/mint_dev_jwt.py` (new)
- `pyproject.toml` (added `pyjwt>=2.8,<3.0` to dev extras)
Tracker docs (3):
- `_docs/02_tasks/_dependencies_table.md` (AZ-777 5→8pt)
- `_docs/03_implementation/reviews/batch_104_review.md` (new)
- `_docs/03_implementation/batch_104_cycle3_report.md` (this file)
## AC coverage
| AC | Phase 1 portion satisfied? | Evidence |
|----|----------------------------|----------|
| AC-1 (compose lints; depends_on satellite-provider) | ✅ | `docker compose -f docker-compose.test.jetson.yml config` exits 0 with the new env block. |
| AC-2 unit (`_do_enumerate` POST inventory + `_download_one_tile` slippy-map GET) | ✅ | `tests/unit/c11_tile_manager/test_tile_downloader.py` 14/14 PASS. |
| AC-2 live (Bearer-authenticated round-trip vs. running service) | ⏸ | `tests/e2e/satellite_provider/test_smoke.py` is in place; runs next time the Jetson harness fires. |
| AC-3..6 | ⏳ | Out of scope (Phases 25). |
## Test run results
```
$ python -m pytest tests/unit/c11_tile_manager/ -v --tb=short
============================== 58 passed in 3.99s ==============================
$ python -m pytest tests/unit/runtime_root/ tests/unit/c11_tile_manager/ -v --tb=short
============================= 113 passed in 3.68s ==============================
$ python -m pytest tests/e2e/satellite_provider/test_smoke.py -v --tb=short
============================== 2 skipped in 0.68s ==============================
(skip reason: AZ-777 satellite-provider smoke gated by RUN_REPLAY_E2E=1)
```
Suite-wide test run is deferred to the end of the AZ-777
implementation phase per the iterative-skill exception in
`.cursor/rules/coderule.mdc` — Phase 1 is a batch, not the end of
implementation. The two test trees that depend on the modified code
(`tests/unit/c11_tile_manager/` and `tests/unit/runtime_root/`) are
green.
## Code review
See `_docs/03_implementation/reviews/batch_104_review.md`
**verdict: PASS_WITH_WARNINGS**. Three findings (1 Medium
Architecture, 1 Medium Maintainability, 1 Low Maintainability); all
deferred to later AZ-777 phases or future tuning with clear
ownership. No Critical or High findings.
## Risks acknowledged on this batch
- **TLS_INSECURE not in production code path yet** — only the smoke
test honours `SATELLITE_PROVIDER_TLS_INSECURE`. Phase 3 (the real
`operator_pre_flight_setup` fixture) is the first production-ish
consumer of `HttpTileDownloader`; it MUST plumb the flag through.
Flagged as F1 in the batch review.
- **`_DEFAULT_ESTIMATED_TILE_BYTES = 50 KiB`** — conservative for
CARTO Voyager basemap; may under-reserve for UAV-uploaded tiles.
Acceptable for Phase 1; revisit in Phase 5. Flagged as F2.
- **Smoke test passes when catalog is empty** — by design;
exercises the wire pre-Phase-2 and tightens automatically once
Phase 2 seeds tiles. Flagged as F3.
## STOP gate
This batch closes Phase 1 of AZ-777's 5-phase plan. The next phase
(Derkachi tile catalog seed) needs operator alignment on the
imagery source (CARTO Voyager Basemap proposed in the spec) and on
the bbox / zoom-range envelope. Pause for user decision before
Phase 2.