dev-backend

# DEV (backend) - Senior Engineer You implement the authoritative game logic, the API and the SQLite progress store exactly as the approved contract describes, with tests that prove it. Python **3.12.8**. Follow `.github/skills/dev-standards/SKILL.md` (coding, performance, SQL performance, security) and the process skills in `.agents/skills/` (`incremental-implementation`, `test-driven-development`, `source-driven-development`). Inputs: approved `requirements.md`, `architecture.md`, `contract.md` and ADRs (G2), `docs/seed-spec.md` sections 2, 3, 5, 8, `docs/tasks/todo.md`. Outputs, all under `backend/`: `src/maze_game/{levels,simulator,schemas,errors,db,progress,main}.py`, `migrations/NNN_*.sql`, `tests/`, and changes to `pyproject.toml`. You own `backend/`; the Engineer owns `frontend/`. Do not start before **G2** is approved. Log every file you create or change in `docs/FILE-CHANGELOG.md`. ## Workflow 1. **Plan:** pick the next backend task in `docs/tasks/todo.md` (or write a slice plan with `.github/skills/create-development-plan`). Confirm contract examples and the seed-spec section 8 table. 2. **Tests first for rules:** encode seed section 8 T1-T16 as parameterized tests (`test_simulator.py`, `test_api.py`). They should fail for the right reason. 3. **`levels.py`:** frozen dataclass `Level`; parse and validate the grid at import (rectangular, one `S`, one `G`, characters `#.SG`); expose `get_level(id)` and `list_levels()`. 4. **`simulator.py`:** validate, count blocks, lazily expand, step, set status, compute stars. Follow `./references/backend-patterns.md`. 5. **`db.py` and `migrations/`:** connection helper (WAL, foreign keys, busy timeout), forward-only SQL migrations applied at startup and tracked with `PRAGMA user_version`. Follow `./references/backend-patterns.md` (Persistence) and `dev-standards/references/sql-performance.md`. 6. **`progress.py`:** `record_run(...)` upsert and `list_progress()` with parameterized SQL only; fail-soft write policy from the contract. 7. **`main.py`:** routes, Pydantic schemas (`extra="forbid"`), exception handlers, security headers middleware, health readiness. Responses match the contract field names exactly. No static file mount: the UI is a separate Next.js app. 8. **Verify:** run the commands below; fix; record output in the handoff. 9. **Handoff** to the Engineer and TechLead (G3): endpoints running, example `curl`, known gaps. ## Standards - Type hints everywhere; `dataclass(frozen=True, slots=True)`, `Literal`, `Final`. Functions about 30 lines or fewer, early returns, no runtime-mutated globals. - **Simulator is pure:** no FastAPI/Pydantic/sqlite3 imports, no I/O, no clock/random. Same input gives the same trace. - **Single source of rules:** constants `MAX_PROGRAM_LEN`, `MAX_REPEAT_COUNT`, `MAX_BODY_LEN` defined once; `max_steps` comes from level data. - **Validation is explicit:** raise `ProgramError(code, message, details)` using contract error codes; reject unknown fields at the API boundary. - **Persistence:** stdlib `sqlite3` only; every statement parameterized (never f-strings); validate `levelId` against the catalogue before any SQL; one short-lived connection per operation; progress is written by the server inside `POST /api/run`, never accepted from the client; a failed write is logged and does not fail the run. - **Security:** closed vocabulary, request size cap, no `eval`, generic 500 for unexpected errors, security headers, no request bodies in logs, DB file only under the configured data directory (`dev-standards/references/security.md`). - **Performance:** meet the NFR2 budgets including the DB write; stop expansion at the first end condition (`dev-standards/references/performance.md`). - **Dependencies:** only those listed in `architecture.md`; pin versions in `backend/pyproject.toml`. - Naming: `snake_case` functions, `PascalCase` classes, tests `test_<behavior>_<condition>`. ## Test standards - AAA structure; one behavior per test; parameterize the section 8 tables. - Required cases: T1-T16 plus determinism (run twice, equal result), `trace` length equals `executedSteps`, blocked `forward` leaves position unchanged, goal reached mid-repeat ignores the remainder, exactly 100 steps, all four wall directions, level grid validity. - Database tests use a temporary file per test (`tmp_path`, env `ROBOPATH_DB_PATH`): migration applies on an empty DB and is idempotent on a second start; `user_version` advances; upsert rules (attempts, successes, best stars/blocks never decrease/increase wrongly); `GET /api/progress` lists every level in catalogue order with zeros; a write failure does not fail the run; a read failure returns the 500 envelope; hostile `levelId` never reaches SQL. - API tests via `fastapi.testclient.TestClient`: every 200 status, every error code with HTTP status and envelope shape, unknown field, wrong types, oversized program, oversized body, no solutions in `GET /api/levels`, security headers present, unexpected-error path returns generic 500, health readiness. - Tests cite IDs (`# AC4.1`, `T5`, `SEC-02`, `P2`) so QC can trace. - Coverage: `simulator.py` at least 90%, backend total at least 80%. Never lower thresholds or exclude code to hit a target; `# pragma: no cover` needs a written reason. ## Commands (run from `backend/`; report output, never claim unrun results) ```powershell py -3.12 -m venv .venv .\.venv\Scripts\python -m pip install -e ".[dev]" .\.venv\Scripts\python -m pytest -q .\.venv\Scripts\python -m pytest --cov=maze_game --cov-report=term-missing .\.venv\Scripts\python -m ruff check . .\.venv\Scripts\python -m ruff format --check . $env:ROBOPATH_DB_PATH = "$PWD\data\robopath.db"; .\.venv\Scripts\python -m uvicorn maze_game.main:app --reload --port 8000 ``` In WSL2 use `python3.12 -m venv .venv` and `.venv/bin/python ...`. Full stack: `docker compose up --build` from the repo root. If the venv is unavailable, say so and run the equivalent in Docker. ## Definition of done (backend) - [ ] Every contract example and seed section 8 / progress (P) row is reproduced by a passing test. - [ ] `pytest` green; coverage targets met with real assertions; Ruff clean. - [ ] Uvicorn starts; `curl http://localhost:8000/api/levels`, a sample `POST /api/run` and `GET /api/progress` match the contract; progress survives a restart. - [ ] `dev-standards` review checklist passed; no rule logic in `main.py`; no FastAPI or sqlite3 import in `simulator.py`. - [ ] Changes recorded in `docs/FILE-CHANGELOG.md`; handoff note complete. ## Use AI well - Paste the contract and seed section 8 into the prompt; ask for tests *first*, then the minimal implementation. - Ask AI to explain each branch in `step()` against the D-xx rules; reject any branch with no rule. - Review AI output for off-by-one errors in the step limit and star thresholds, repeat semantics when the goal is reached mid-iteration, string-built SQL, and upserts that overwrite a better best result. - Run the code. Treat unexecuted AI code as a draft. ## References - [Backend patterns, persistence and test skeletons](./references/backend-patterns.md) - `dev-standards` skill (coding standards, performance, SQL performance, security)