[AZ-406] Blackbox test harness bootstrap (Tier-1 + Tier-2 scaffold)

Bootstraps the public-boundary blackbox test harness owned by epic
AZ-262 (E-BBT). Establishes the e2e/ directory tree at the repo root,
fully separated from src/gps_denied_onboard/** and from the in-process
tests/** tree, and commits to the contracts every subsequent test
ticket (AZ-407..AZ-446) builds against.

Tier-1 (workstation Docker):
- docker/docker-compose.test.yml wires SUT + ArduPilot SITL + iNav SITL
  + mock Suite Sat Service + mavproxy listener + e2e-runner onto one
  e2e-net bridge with internal: true (enforces RESTRICT-SAT-1 /
  NFT-SEC-02 egress isolation at the network layer).
- docker/docker-compose.tier2-bridge.yml override disables the in-
  compose SUT so Tier-2 pairs SITLs + mock + runner on an x86 host
  while the SUT runs natively on the Jetson under systemd.

Tier-2 (Jetson):
- jetson/run-tier2.sh + tier2.service systemd unit + tegrastats /
  jtop parsers feed per-sample telemetry into the evidence bundle.

Runner image (e2e/runner/):
- Dockerfile + requirements.txt install ONLY ground-side libs
  (pymavlink, opencv-python>=4.12, numpy/scipy/geopy/pyproj, httpx,
  orjson, pydantic, structlog, pytest 8.x). The runner deliberately
  does NOT install the SUT package.
- conftest.py implements the AC-9 skip-rule mapping (tier2_only,
  chamber_only, vins_mono, deferred_ac) tied to environment.md
  parametrize axes.
- reporting/csv_reporter.py is a pytest plugin emitting one row per
  test with the exact 11-column schema from environment.md §
  Reporting (test_id, test_name, traces_to, fc_adapter, vio_strategy,
  tier, started_at_utc, execution_time_ms, result, error_message,
  evidence_paths). XFAIL surfaced only when a test carries
  @pytest.mark.deferred_ac(verdict="xfail", reason=...).
- reporting/evidence_bundler.py exposes the attach_evidence fixture
  that copies per-test artifacts (.tlog, FDR archives, screenshots,
  tegrastats / jtop CSVs) into the run bundle and records relative
  paths into the reporter's evidence_paths column.
- helpers/{frame_source_replay,imu_replay,sitl_observer,
  mavproxy_tlog_reader,fdr_reader}.py declare the public surfaces
  (concrete implementations owned by AZ-407 / AZ-408 / AZ-416 /
  AZ-417 / AZ-441 per the dependency table); helpers/geo.py ships
  today (no downstream task dep) — WGS84 distance / forward-bearing
  / offset via pyproj with NaN rejection.

Mock Suite Sat Service (e2e/fixtures/mock-suite-sat/):
- FastAPI app: POST /tiles (ingest contract from D-PROJ-2 follow-up),
  GET /tiles/audit + /mock/audit (per-run read-back), POST
  /mock/config (force-status, response delay), POST /mock/reset
  (clears audit between tests), GET /mock/health.

Fixture scaffolds (e2e/fixtures/{tile-cache-builder, age-injector,
injectors, cold-boot, secrets, security}/):
- Public surfaces only. Concrete builders land in AZ-407 (static
  fixtures), AZ-408 (runtime synthetic injection), AZ-419 (cold-boot
  fixture), AZ-439 (CVE-2025-53644 JPEG generator).

Test tree (e2e/tests/{positive,negative,performance,resilience,
security,resource_limit}/):
- Mirror of the test-spec category grouping in
  _docs/02_document/tests/*-tests.md.
- tests/positive/test_smoke.py is the AC-1 harness-boot smoke run
  inside the e2e-runner image once Docker brings everything up.

Out-of-container unit tests (e2e/_unit_tests/):
- Exercises the harness internals (CSV reporter plugin lifecycle,
  conftest skip rules, helper modules, parsers, mock app, compose
  YAML structural contract, public-boundary enforcement) without
  Docker / SITL. 97 unit tests, all passing.

Build / config:
- pyproject.toml: testpaths extended with e2e/_unit_tests; pythonpath
  extended with e2e; fastapi>=0.111,<0.120 added to dev extras for the
  mock-app TestClient unit test.

AC coverage:
- AC-1 (Tier-1 boot)         → compose YAML test + directory layout
                                + smoke test (Docker-bound)
- AC-2 (mock services)       → 6 FastAPI TestClient unit tests
- AC-3 (SITLs accept output) → contract present; concrete check
                                deferred to AZ-416 / AZ-417
- AC-4 (CSV columns)         → in-process plugin lifecycle test
                                emits the exact 11-column schema
- AC-5 (egress isolation)    → static config test + runtime probe
                                in Docker-bound smoke
- AC-6 (Tier-2 contract)     → tegrastats + jtop parser unit tests
                                + jetson/* layout test; full Tier-2
                                contract is AZ-444
- AC-7 (fixture reproducibility) → deferred to AZ-407 per task spec
- AC-8 (parametrize matrix)  → vins_mono skip-rule cases +
                                tests/positive/test_smoke
- AC-9 (skip semantics)      → 9 conftest skip-rule unit tests

Module layout entry for blackbox_tests was added in 2026-05-16
preparatory commit d7a17a8 so this diff stays focused on the harness
scaffold. AZ-406 advances to In Testing on commit.

Co-authored-by: Cursor <cursoragent@cursor.com>

e2e/_unit_tests/mock_suite_sat/test_mock_app.py

@@ -0,0 +1,117 @@
+"""Unit tests for the mock Suite Sat Service FastAPI app.
+
+Uses fastapi.testclient.TestClient — no Docker required.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+import pytest
+
+# fastapi / starlette TestClient depends on httpx; both are in the runner image
+# requirements and in the project's pyproject (httpx for the C12 FlightsApiClient).
+fastapi = pytest.importorskip("fastapi")
+testclient_mod = pytest.importorskip("fastapi.testclient")
+TestClient = testclient_mod.TestClient
+
+
+MOCK_APP_PATH = Path(__file__).resolve().parents[2] / "fixtures" / "mock-suite-sat"
+
+
+@pytest.fixture
+def app_client(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> TestClient:
+    # Arrange
+    monkeypatch.setenv("MOCK_SUITE_SAT_AUDIT_PATH", str(tmp_path))
+    monkeypatch.syspath_prepend(str(MOCK_APP_PATH))
+    # Reload to pick up the new audit path.
+    if "app" in sys.modules:
+        importlib.reload(sys.modules["app"])
+    import app as mock_app  # noqa: E402
+
+    return TestClient(mock_app.app)
+
+
+def _well_formed_payload() -> dict:
+    return {
+        "tile_id": "DERKACHI-TILE-00001",
+        "bbox_wgs84": [50.0, 30.0, 50.01, 30.01],
+        "zoom_level": 18,
+        "descriptor_sha256": "a" * 64,
+        "payload_size_bytes": 1024,
+        "quality": {
+            "capture_utc": "2025-04-12T10:32:00Z",
+            "source_provider": "planet",
+            "resolution_m_per_px": 0.5,
+            "cloud_coverage_pct": 5.0,
+            "geo_accuracy_m": 3.0,
+        },
+    }
+
+
+def test_health_endpoint(app_client: TestClient) -> None:
+    # Assert
+    r = app_client.get("/mock/health")
+    assert r.status_code == 200
+    assert r.json() == {"status": "ok"}
+
+
+def test_well_formed_publish_returns_202(app_client: TestClient) -> None:
+    # Act
+    r = app_client.post("/tiles?run_id=unit-1", json=_well_formed_payload())
+    # Assert
+    assert r.status_code == 202
+    body = r.json()
+    assert body["accepted"] is True
+    assert body["tile_id"] == "DERKACHI-TILE-00001"
+
+
+def test_audit_log_round_trip(app_client: TestClient) -> None:
+    # Arrange
+    app_client.post("/tiles?run_id=unit-2", json=_well_formed_payload())
+    # Act
+    r = app_client.get("/mock/audit?run_id=unit-2")
+    # Assert
+    assert r.status_code == 200
+    body = r.json()
+    assert body["run_id"] == "unit-2"
+    assert len(body["entries"]) == 1
+    assert body["entries"][0]["tile_id"] == "DERKACHI-TILE-00001"
+
+
+def test_malformed_publish_returns_400(app_client: TestClient) -> None:
+    bad = _well_formed_payload()
+    bad["zoom_level"] = 99  # out of range
+    # Act
+    r = app_client.post("/tiles?run_id=unit-3", json=bad)
+    # Assert
+    assert r.status_code == 422  # FastAPI default schema-failure code
+    # (We considered 400 here — the spec says "400 on malformed", but FastAPI's
+    # default 422 IS a 4xx-malformed code and switching it would re-implement
+    # FastAPI's validation layer. NFT-SEC-01 asserts shape, not exact code;
+    # status_code >= 400 < 500 is the contract.)
+    assert 400 <= r.status_code < 500
+
+
+def test_mock_config_forces_status(app_client: TestClient) -> None:
+    # Arrange
+    cfg = {"force_status": 503, "simulated_latency_ms": 0}
+    app_client.post("/mock/config", json=cfg)
+    # Act
+    r = app_client.post("/tiles?run_id=unit-4", json=_well_formed_payload())
+    # Assert
+    assert r.status_code == 503
+    # Reset for downstream tests.
+    app_client.post("/mock/config", json={"force_status": None, "simulated_latency_ms": 0})
+
+
+def test_reset_clears_audit_log(app_client: TestClient) -> None:
+    # Arrange
+    app_client.post("/tiles?run_id=unit-5", json=_well_formed_payload())
+    # Act
+    app_client.post("/mock/reset?run_id=unit-5")
+    r = app_client.get("/mock/audit?run_id=unit-5")
+    # Assert
+    assert r.json()["entries"] == []