Execute aiohttp-first test migration plan

.github/aiohttp-performance-matrix.md

@@ -0,0 +1,38 @@
+# Aiohttp Performance Evaluation Matrix
+
+## Context
+
+- Date: 2026-04-29
+- Branch: feature/aiohttp-test-migration
+- Runtime: Python 3.14.2 via `uv run`
+- Host: local development machine (macOS)
+
+## Method
+
+Each suite was executed 3 times with `pytest --no-cov` to reduce coverage overhead and
+capture relative runtime consistency.
+
+Commands:
+
+1. `uv run pytest --no-cov tests/test_http_client_compat.py`
+2. `uv run pytest --no-cov tests/test_vapix.py tests/test_ptz.py tests/test_view_areas.py tests/test_light_control.py`
+3. `uv run pytest --no-cov tests/test_vapix.py tests/test_ptz.py tests/test_view_areas.py tests/test_light_control.py tests/test_mqtt.py tests/test_pwdgrp_cgi.py tests/test_stream_profiles.py tests/test_user_groups.py tests/test_event_instances.py tests/test_port_management.py tests/test_pir_sensor_configuration.py`
+
+## Results
+
+| Matrix Group | Passed Tests | Run 1 (s) | Run 2 (s) | Run 3 (s) | Avg (s) | Min (s) | Max (s) |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| compat | 10 | 0.03 | 0.03 | 0.02 | 0.03 | 0.02 | 0.03 |
+| handlers | 113 | 0.42 | 0.47 | 0.46 | 0.45 | 0.42 | 0.47 |
+| phase6plus | 154 | 0.58 | 0.54 | 0.55 | 0.56 | 0.54 | 0.58 |
+
+## Interpretation
+
+1. Aiohttp-focused integration suites remain stable and low-latency on repeated runs.
+2. Runtime spread is narrow for all groups, indicating no obvious regression drift.
+3. The broader migrated suite (`phase6plus`) stays under one second across all samples.
+
+## Exit Decision
+
+Phase 9 acceptance is met: the aiohttp performance matrix has been executed and
+recorded with repeatable timing data for representative migrated suites.

.github/final-architecture-signoff.md

@@ -0,0 +1,78 @@
+# Final Architecture Sign-Off And Rollback Gates
+
+## Decision Summary
+
+The aiohttp-first migration architecture is approved for completion based on:
+
+1. Test-layer migration from respx/httpx coupling to aiohttp_server parity coverage.
+2. Consolidated shared shim utilities for migrated suites.
+3. Runtime httpx-removal implementation plan documented and scoped.
+4. Performance matrix confirming stable runtime behavior on representative suites.
+
+## Signed-Off Architecture State
+
+1. Initialization model remains phase-driven:
+- API_DISCOVERY
+- PARAM_CGI_FALLBACK
+- APPLICATION
+
+2. Handler registration and grouped initialization behavior are preserved.
+
+3. Request/response behavior parity is maintained across migrated tests:
+- status-code error translation,
+- auth fallback behavior,
+- namespace-aware/event parsing expectations.
+
+4. Planned runtime simplification is constrained and reversible:
+- move to aiohttp-only runtime sessions,
+- preserve existing request error semantics,
+- preserve auth retry behavior for AUTO mode.
+
+## Release Gates
+
+All gates must be green before rollout:
+
+1. Linting: `uv run ruff check .`
+2. Formatting: `uv run ruff format --check .`
+3. Typing: `uv run mypy axis`
+4. Tests: `uv run pytest`
+5. Migration docs current:
+- `.github/httpx-removal-implementation-plan.md`
+- `.github/aiohttp-performance-matrix.md`
+
+## Rollback Gates And Triggers
+
+Rollback to pre-change baseline is required if any trigger occurs after runtime
+httpx removal implementation begins:
+
+1. Functional trigger:
+- auth negotiation failures or increased 401/403 responses in supported devices.
+
+2. Reliability trigger:
+- sustained request timeout/connection-error regression outside historical bounds.
+
+3. Compatibility trigger:
+- regressions in API discovery, param.cgi fallback, or application handler
+  initialization ordering.
+
+4. Quality trigger:
+- failure to satisfy lint/type/test release gates.
+
+## Rollback Procedure
+
+1. Revert runtime-removal commits from the feature branch.
+2. Restore last green commit set with full test migration and green CI.
+3. Re-run full validation matrix.
+4. Publish incident note in PR with root-cause and adjusted rollout plan.
+
+## Operational Notes
+
+1. Keep `uv.lock` updates isolated from migration intent unless dependency inputs
+   changed intentionally.
+2. Preserve incremental commit discipline for any follow-up runtime changes.
+3. Maintain PR checklist and commit ledger updates per increment.
+
+## Phase 10 Exit Criteria
+
+Phase 10 is complete when this sign-off is present in-repo and PR tracking marks
+the final architecture sign-off and rollback gates as complete.

.github/httpx-removal-implementation-plan.md

@@ -0,0 +1,108 @@
+# Runtime HTTPX Removal Implementation Plan
+
+## Scope
+
+This plan defines how runtime support for `httpx` will be removed while preserving
+existing behavior for Axis request handling, auth fallback, and error semantics.
+
+The test migration has already moved request/response test behavior to
+`aiohttp_server`-backed flows. Remaining Phase 8 work is runtime-only.
+
+## Current Runtime Coupling (Inventory)
+
+1. `axis/interfaces/vapix.py`
+- Imports `httpx` and supports two request engines (`httpx` and `aiohttp`).
+- Constructs `httpx.BasicAuth` and `httpx.DigestAuth` for non-`aiohttp` sessions.
+- Routes requests through `_perform_httpx_request` when session is not `aiohttp`.
+- Maps `httpx.TimeoutException`, `httpx.TransportError`, and
+  `httpx.RequestError` to `RequestError`.
+- Uses `httpx.DigestAuth` type checks for AUTO fallback behavior.
+
+2. `axis/models/configuration.py`
+- `Configuration.session` is typed as `AsyncClient | ClientSession`.
+- Type-checking import references `httpx.AsyncClient`.
+
+3. `pyproject.toml`
+- Runtime dependency list includes `httpx>=0.26`.
+- Optional pinned requirements include `httpx==0.28.1`.
+
+4. Tests
+- `tests/test_configuration.py` still validates `httpx.AsyncClient` acceptance in
+  `Configuration`.
+- `tests/test_vapix.py` and `tests/respx_shim.py` reference `httpx` exceptions to
+  assert request-error translation behavior.
+- `tests/test_http_client_compat.py` already validates `aiohttp` runtime behavior.
+
+## Target Runtime Contract
+
+1. Runtime session type is `aiohttp.ClientSession` only.
+2. Runtime auth types are `aiohttp.BasicAuth` or digest handled by
+   `AiohttpDigestAuth` / `DigestAuthMiddleware` when available.
+3. Request execution path is single-engine (`aiohttp`) only.
+4. Public behavior remains unchanged:
+- same `RequestError` mapping for timeout/connection/general request failures,
+- same status-code-to-Axis-error mapping,
+- same AUTO auth fallback semantics.
+
+## Ordered Execution Plan
+
+1. Narrow configuration typing to `aiohttp.ClientSession`
+- Update `axis/models/configuration.py` to remove `httpx.AsyncClient` references
+  and define `HTTPSession = ClientSession`.
+- Update tests that currently expect mixed-session acceptance.
+
+2. Remove dual-engine request logic from `Vapix`
+- Delete `_perform_httpx_request`, `_httpx_session`, `_httpx_auth`, and
+  `_client_name` branching.
+- Remove `httpx.BasicAuth`/`httpx.DigestAuth` construction paths.
+- Keep `_perform_aiohttp_request` as the single request engine.
+
+3. Preserve exception mapping semantics without `httpx`
+- Replace explicit `httpx` exception branches with `aiohttp` and generic timeout
+  handling while preserving current `RequestError` messages:
+  - timeout -> `RequestError("Timeout")`
+  - connection issues -> `RequestError("Connection error: ...")`
+  - other client errors -> `RequestError("Unknown error: ...")`
+
+4. Adjust AUTO auth fallback checks
+- Replace `httpx.DigestAuth`-specific checks in `_should_retry_with_basic` with
+  client-agnostic state checks that still enforce one retry.
+
+5. Update dependency metadata
+- Remove `httpx` from runtime dependencies in `pyproject.toml`.
+- Remove pinned `httpx` entry from `project.optional-dependencies.requirements`.
+
+6. Update tests to reflect aiohttp-only runtime
+- Replace or remove tests that assert `httpx.AsyncClient` compatibility in
+  `tests/test_configuration.py`.
+- Keep and extend `tests/test_http_client_compat.py` for auth and request parity.
+- Update `tests/test_vapix.py` and `tests/respx_shim.py` to avoid direct `httpx`
+  exception dependencies while preserving equivalent behavior assertions.
+
+7. Validation gates
+- `uv run ruff check axis tests`
+- `uv run ruff format --check axis tests`
+- `uv run mypy axis`
+- targeted pytest for touched suites first
+- `uv run pytest`
+
+## Risks And Mitigations
+
+1. Risk: subtle auth regression in AUTO mode.
+- Mitigation: retain and expand fallback tests around `WWW-Authenticate` handling.
+
+2. Risk: changed exception text breaks downstream consumers/tests.
+- Mitigation: preserve existing `RequestError` message strings verbatim.
+
+3. Risk: digest middleware availability differs by aiohttp version.
+- Mitigation: keep current middleware availability guard and digest helper fallback.
+
+## Exit Criteria
+
+Phase 8 is complete when all are true:
+
+1. Runtime package no longer depends on `httpx`.
+2. Production code under `axis/` has no `import httpx` references.
+3. `Configuration` and `Vapix` are aiohttp-only at runtime.
+4. Existing request/auth/error behavior is preserved by tests.
+5. Full lint/type/test matrix passes.