---
phase: 8
slug: stack-upgrade-backend-decomposition
status: draft
nyquist_compliant: false
wave_0_complete: false
created: 2026-06-07
---

# Phase 8 — Validation Strategy

> Per-phase validation contract for feedback sampling during execution.

---

## Test Infrastructure

| Property | Value |
|----------|-------|
| **Backend framework** | pytest with pytest-asyncio (asyncio_mode = auto) |
| **Backend config file** | `backend/pytest.ini` |
| **Backend quick run** | `cd backend && pytest tests/test_auth.py -x -v` |
| **Backend full suite** | `cd backend && pytest -v` |
| **Frontend framework** | Vitest 4.1.7 |
| **Frontend config** | `frontend/vitest.config.js` |
| **Frontend quick run** | `cd frontend && npm test` |
| **Estimated runtime** | ~30 seconds (backend), ~10 seconds (frontend) |

---

## Sampling Rate

- **After every task commit:** Run `cd backend && pytest -x -v` (backend changes) or `cd frontend && npm test` (frontend changes)
- **After Wave 0 (test stubs):** Confirm all new stubs are xfail — `pytest --tb=no -q`
- **After decomposition plans:** Full suite `cd backend && pytest -v` — zero failures before advancing

---

## Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| CR-01 | `change_password` revokes other sessions, keeps current | unit/integration | `pytest tests/test_auth.py::test_change_password_revokes_other_sessions -x` | ❌ Wave 0 |
| CR-02 | `enable_totp` revokes other sessions, keeps current | unit/integration | `pytest tests/test_auth.py::test_enable_totp_revokes_other_sessions -x` | ❌ Wave 0 |
| CR-03 | `disable_totp` revokes other sessions, keeps current | unit/integration | `pytest tests/test_auth.py::test_disable_totp_revokes_other_sessions -x` | ❌ Wave 0 |
| CODE-01 | All admin URLs still respond on same paths after split | integration | `pytest tests/test_admin.py -x` | ✅ |
| CODE-02 | All document URLs still respond on same paths after split | integration | `pytest tests/test_documents.py -x` | ✅ |
| CODE-03 | All auth URLs still respond on same paths after split | integration | `pytest tests/test_auth.py -x` | ✅ |
| CODE-04 | All existing consumer imports resolve; no 35+ files changed | smoke | `cd frontend && npm test` | ✅ |
| CODE-08 | No model defined twice across packages | static/grep | `grep -rn "class CloudConnectionOut" backend/` | N/A |
| PERF-01 | npm list confirms all packages present | install verification | `cd frontend && npm list` | N/A |

---

## Wave 0 Gaps

New tests to write before decomposition work begins:

- [ ] `backend/tests/test_auth.py` — add 3 xfail stubs promoted to real tests for CR-01/02/03:
  - `test_change_password_revokes_other_sessions`
  - `test_enable_totp_revokes_other_sessions`
  - `test_disable_totp_revokes_other_sessions`
- [ ] Frontend: verify `useToastStore` mock wiring in `SettingsAccountTab.test.js` and `TotpEnrollment.test.js` after stub creation

---

## Critical Test Gates

| Gate | Command | Must pass before |
|------|---------|-----------------|
| Wave 0 stubs xfail | `pytest --tb=no -q` | Any decomposition work |
| Admin split | `pytest tests/test_admin.py -x -v` | Advancing past CODE-01 |
| Documents split | `pytest tests/test_documents.py -x -v` | Advancing past CODE-02 |
| Auth split | `pytest tests/test_auth.py -x -v` | Advancing past CODE-03 |
| Full backend suite | `pytest -v` | Phase gate |
| Frontend smoke | `npm test` | Phase gate |
| URL regression | `pytest tests/test_admin.py tests/test_documents.py tests/test_auth.py -v` | Phase complete |

---

## Security Validation

| Threat | Test | Evidence |
|--------|------|---------|
| Router prefix doubling | `pytest -v` — all existing route tests pass | URL paths unchanged |
| Admin endpoint auth leakage | `pytest tests/test_admin.py -k "not_admin"` | 403 on all admin routes for non-admin |
| Circular import crash | App starts cleanly: `uvicorn main:app --reload` exits 0 | No ImportError |
| CloudConnectionOut import break | `pytest tests/test_cloud.py -x` | cloud.py imports succeed |