# Existing Coverage — Run 02-az507-routespec-relocation

**Date**: 2026-05-23
**Phase**: 3 (Safety Net)
**Run**: `_docs/04_refactoring/02-az507-routespec-relocation/`

## Coverage map (refactor area)

The run touches three artifact families: production source (DTO relocation), documentation (`module-layout.md`), and the AZ-270 compose-root lint. Test coverage of each:

### 1. Production-source coverage (C01: relocate `RouteSpec` to `_types/route.py`)

| Test file | Symbols exercised | Test count | Layer | Runs locally? | Result at HEAD |
|-----------|-------------------|-----------:|-------|---------------|----------------|
| `tests/unit/replay_input/test_tlog_route.py` | `RouteSpec` (shape AC-7), `extract_route_from_tlog` | 14 | unit | yes | **14/14 PASS** |
| `tests/unit/c11_tile_manager/test_route_client.py` | `SatelliteProviderRouteClient`, `RouteSeedResult`, `RouteSpec` (consumer-side construction) | 30 | unit | yes | **30/30 PASS** |
| `tests/integration/c11_tile_manager/test_route_client_e2e.py` | `SatelliteProviderRouteClient.seed_route` against live satellite-provider | 1+ | integration | **no** (Jetson-only per `environment.md`) | not run; deferred to Phase 6 full-suite gate on Jetson |
| `tests/e2e/replay/_operator_pre_flight.py` | helper module — driver imports `RouteSpec` | (imported by drivers below) | e2e helper | n/a | imported via drivers |
| `tests/e2e/replay/_e2e_orchestrator.py` | helper module — references `extract_route_from_tlog` in docstring only | (imported by drivers below) | e2e helper | n/a | imported via drivers |
| `tests/e2e/replay/test_operator_pre_flight_driver.py` | driver-level mocks of `RouteSpec` + `RouteSeedResult` + `SatelliteProviderRouteClient` | 11 | e2e (mock-driven unit) | yes (no Jetson deps) | not re-run in Phase 3 — verified passing in batch 108 report; will be re-run in Phase 6 |
| `tests/e2e/replay/test_e2e_orchestrator_unit.py` | orchestrator-step unit tests with `RouteSpec` fixture | 17 | e2e (mock-driven unit) | yes (no Jetson deps) | not re-run in Phase 3 — verified passing in batch 109 report; will be re-run in Phase 6 |
| `tests/e2e/replay/test_operator_pre_flight_integration.py` | error-message string check (`"RouteSpec must carry…"`) | 1 | e2e | **no** (Jetson-only) | not run |
| `tests/e2e/replay/test_az835_e2e_real_flight.py` | tier-2 integration test | several | e2e | **no** (Jetson-only) | not run |
| `tests/fixtures/derkachi_c6/seed_route.py` | CLI fixture — calls `extract_route_from_tlog` and `SatelliteProviderRouteClient` | (CLI; not a pytest target) | fixture/CLI | n/a | static-import-only verification at Phase 4 |

**Phase 3 verdict for production-source coverage**: SUFFICIENT. Unit tests for both producer (`replay_input.tlog_route`) and consumer (`c11_tile_manager.route_client`) cover the symbols being relocated. The DTO is `frozen=True, slots=True` and no test asserts on `RouteSpec.__module__` (verified by grep — only match was for an unrelated `_build_c5_state_estimator_pair.__module__` in `test_az625_c5_isam2_graph_handle_ordering.py`). The relocation is identity-preserving by construction.

### 2. Doc coverage (C02: `module-layout.md` refresh)

`module-layout.md` is consumed by `/implement` Step 4 (File Ownership) and `/code-review` Phase 7. The relevant runtime-tested behavior is the **AZ-270 lint** (which references rule 9). C02's doc-only edits cannot be tested at the source-code level; verification is by diff review against on-disk reality (Phase 6).

### 3. Lint coverage (C03: widen `test_ac6_only_compose_root_imports_concrete_strategies`)

| Test file | Symbol exercised | Test count | Layer | Runs locally? | Result at HEAD |
|-----------|------------------|-----------:|-------|---------------|----------------|
| `tests/unit/test_az270_compose_root.py` | `test_ac6_only_compose_root_imports_concrete_strategies` (current narrow lint — 8 tests in file total) | 8 | unit | yes | **8/8 PASS** |

The test passing at HEAD with the F1 violation present in the codebase is the **expected baseline**: it confirms F3 (the lint is too narrow). After C03 widens the lint, running it at HEAD (before C01 lands) reproduces F1 as a lint failure; running it at the C01 + C02 tip reproduces zero violations. This is the C03 self-check.

## Targeted-suite run (Phase 3a; the refactor-area safety net)

Command:
```
.venv/bin/python -m pytest \
    tests/unit/replay_input/test_tlog_route.py \
    tests/unit/c11_tile_manager/test_route_client.py \
    tests/unit/test_az270_compose_root.py \
    -v --tb=short
```

**Result**: `52 passed in 5.20s`. ALL tests covering the refactor area pass at HEAD. The safety net is established.

## Full `tests/unit/` run (broader baseline)

Command:
```
.venv/bin/python -m pytest tests/unit/ -v --tb=short
```

**Result**: `1 failed, 2302 passed, 86 skipped, 3 warnings in 72.97s`.

### Skipped tests (86)

All skips are environment-gated and expected per `_docs/02_document/tests/environment.md`:
- `c6_tile_cache/test_postgres_*.py` (45 skips) — Docker compose services required
- `c7_inference/test_*.py` (10 skips) — CUDA / TensorRT / Jetson-only runtimes
- `c8_fc_adapter/test_az399_tlog_replay_adapter.py` (1 skip) — RUN_REPLAY_E2E gate
- `replay_input/test_az698_window_alignment.py` (1 skip) — Derkachi fixture
- `test_ac4_workflows.py` (1 skip) — `actionlint` not on PATH
- Other Tier-2-only Jetson markers (~28 skips)

None of these are in the refactor scope; all are documented Jetson-or-Docker-only paths.

### Failed test (1) — pre-existing, out of refactor scope

```
FAILED tests/unit/c12_operator_orchestrator/test_cli_console_script.py::TestConsoleScript::test_cold_start_under_500ms_p99
```

**Failure mode**: `NFR-perf-cold-start` asserts `operator-orchestrator --help` cold-start ≤ 500 ms p99 (worst-of-11-trimmed-1). On this macOS workstation the samples were 687.5–924.0 ms; the worst-after-trim was 847.6 ms.

**Classification**:
- **Out of refactor scope**: c12 operator-orchestrator has no `RouteSpec` / `route_client` / AZ-270-lint touchpoint. The relocation in C01 + C02 + C03 cannot affect cold-start of `operator-orchestrator --help`.
- **Pre-existing**: the cumulative review of cycle-3 batches 104–109 (`_docs/03_implementation/cumulative_review_batches_104-109_cycle3_report.md`) recorded "every committed batch ended with passing tests at the per-batch full run" — the per-batch runs ran on the Jetson e2e lane (per `environment.md` active policy), where the 500 ms threshold is met. The same test is environment-sensitive and fails on the macOS workstation because subprocess startup + Python interpreter cold-load on macOS exceed the production-target 500 ms NFR.
- **Test-gating gap**: per `_docs/02_document/tests/environment.md` active policy (2026-05-20), perf NFR tests MUST run on Jetson and are forbidden on workstation. The cold-start test is decorated `@pytest.mark.slow` but does NOT skip on workstation — the slow marker only flags it for selection, not for environment gating. This is a recurring theme: cumulative review F3 already documents a parallel gap in lint enforcement vs. lint coverage.

**Recommendation**: surface this gap as a cycle-3 retrospective input (Step 17). Out of scope for this refactor run. The right fix is a `@pytest.mark.tier2` (or env-var gate) on the cold-start test, which is a 1–2 SP test-gating task.

## Phase 3 GATE decision

The refactor area's safety net is **sound** (52/52 targeted tests pass; no test asserts on `RouteSpec.__module__`; producer-side re-export preserves the existing internal-path import for tests that use it). The single full-suite failure is pre-existing, environment-specific, and has no causal path to the refactor area.

Per `refactor/SKILL.md` Phase 3 GATE wording — "ALL tests must pass before proceeding to Phase 4. If tests fail, fix the tests (not the code) or ask user for guidance" — the right move is **ask user**: the failing test is not a refactor-related test; fixing it (adding a Tier-2 gate) is out of refactor scope but in scope for cycle-3 retrospective.

## Self-verification

- [x] Coverage requirements met for refactor area (52 unit tests covering RouteSpec shape, c11 consumer-side, AZ-270 lint baseline)
- [x] All refactor-area tests pass on current codebase (52/52)
- [x] All public APIs in refactoring scope have blackbox / unit tests (`RouteSpec`, `extract_route_from_tlog`, `SatelliteProviderRouteClient`, `RouteSeedResult`, `test_ac6_only_compose_root_imports_concrete_strategies`)
- [x] No test asserts on `RouteSpec.__module__` — verified via grep
- [x] Test data fixtures (Derkachi tlog excerpt) are configured
- [x] Pre-existing unrelated failure documented above; surfaced for user decision
