Backend runtime upgraded to Python 3.14 with exact dependency pinning (#57)

Signed-off-by: Cliff Hill <xlorep@darkhelm.org>

## Summary

Upgrades backend runtime baseline and dependency management for issue #10.

### Changes

1. **Python Baseline**: Updated from 3.13 to 3.14
   - Updated `backend/pyproject.toml` requires-python constraint
   - Updated `backend/pyrightconfig.json` pythonVersion
   - Updated all Dockerfile and CI references

2. **Dependency Pinning**: Switched to exact version pins in `backend/pyproject.toml`
   - All dev and runtime dependencies now use `==` instead of `>=`
   - `fastapi==0.120.2`, `uvicorn==0.38.0`
   - ruff, pyright, pytest suite pinned to current resolved versions
   - Regenerated `backend/uv.lock` under Python 3.14

3. **Startup Compatibility Guard** (TDD via RED→GREEN)
   - New `compatibility_status()` function evaluates runtime and pinned deps
   - Startup raises `RuntimeError` if policy fails
   - Implemented via FastAPI lifespan (non-deprecated) handler

4. **Compatibility Status Endpoint**
   - New `GET /compatibility` returns policy status, runtime version, and package checks
   - Shares single source of truth with startup validation

5. **Integration Tests**
   - Added failing-then-passing tests for startup guard and endpoint behavior
   - 100% coverage maintained

6. **Direnv Configuration**
   - Added `UV_PYTHON="3.14"` pin to repo `.envrc`
   - Ensures direnv creates/recreates venv with correct Python version

### Validation

- ✅ ruff format/check
- ✅ pyright strict (0 errors)
- ✅ pytest: 8 passed, 100% coverage (>=95 gate)
- ✅ pydoclint: pass
- ✅ xdoctest: pass

### Notes

- SQLAlchemy/SQLModel introduction deferred to next pass per scope
- Compatibility logic currently validates fastapi/uvicorn pins (runtime deps)
- Ready for container build validation and Renovate bot testing

Co-authored-by: copilotcoder <copilotcoder@darkhelm.org>
Reviewed-on: #57
Co-authored-by: Cliff Hill <xlorep@darkhelm.org>
Co-committed-by: Cliff Hill <xlorep@darkhelm.org>

docs/GITEA_ACTIONS_TROUBLESHOOTING.md

@@ -20,7 +20,7 @@ jobs:
   setup:
     runs-on: ubuntu-latest:docker://ubuntu:22.04
   backend:
-    runs-on: python-latest:docker://python:3.13-slim
+    runs-on: python-latest:docker://python:3.14-slim
   frontend:
     runs-on: node-latest:docker://node:20-bookworm-slim
 ```
@@ -39,7 +39,7 @@ jobs:
 ### Why This Works
 The runners are configured with Docker images in their labels:
 ```bash
-GITEA_RUNNER_LABELS=ubuntu-latest:docker://ubuntu:22.04,node-latest:docker://node:20-bookworm-slim,python-latest:docker://python:3.13-slim
+GITEA_RUNNER_LABELS=ubuntu-latest:docker://ubuntu:22.04,node-latest:docker://node:20-bookworm-slim,python-latest:docker://python:3.14-slim
 ```
 
 So jobs still run in the correct Docker containers, but Gitea can properly parse and dispatch them.
@@ -127,10 +127,42 @@ If runners show "unregistered runner" errors:
 ### Runner Configuration
 Each runner supports multiple Docker environments:
 - `ubuntu-latest` → `ubuntu:22.04`
-- `python-latest` → `python:3.13-slim`
+- `python-latest` → `python:3.14-slim`
 - `node-latest` → `node:20-bookworm-slim`
 - `ubuntu-act` → `catthehacker/ubuntu:act-latest`
 
+### Mirroring the `ubuntu-act` Runner Image
+If GHCR pulls are flaky, mirror the runner image into your local registry and point the label at that mirror instead of the upstream tag.
+
+Example mirror flow:
+```bash
+docker pull ghcr.io/catthehacker/ubuntu:act-latest
+docker tag ghcr.io/catthehacker/ubuntu:act-latest kankali.darkhelm.lan:3001/darkhelm.org/act-ubuntu:act-latest
+docker push kankali.darkhelm.lan:3001/darkhelm.org/act-ubuntu:act-latest
+```
+
+Recommended runner label once mirrored:
+```bash
+GITEA_RUNNER_LABELS=ubuntu-latest:docker://ubuntu:22.04,node-latest:docker://node:20-bookworm-slim,python-latest:docker://python:3.14-slim,ubuntu-act:docker://kankali.darkhelm.lan:3001/darkhelm.org/act-ubuntu:act-latest
+```
+
+If you want a failover strategy, keep the cached image tagged in the local registry and only refresh it when the upstream digest changes. That way the runner never depends on GHCR at job start.
+
+Automation scripts for this workflow live in `scripts/gitea-actions/`:
+
+- `scripts/gitea-actions/repair_runner_mirror.xsh`
+  Repairs the mirror by pulling from GHCR, tagging/pushing to local registry, and verifying tag presence on each runner host.
+
+- `scripts/gitea-actions/check_runner_images.xsh`
+  Verifies host-by-host image presence for both upstream (`GHCR`) and mirrored (`MIRROR`) tags.
+
+Run from repository root (xonsh):
+
+```sh
+source scripts/gitea-actions/repair_runner_mirror.xsh
+source scripts/gitea-actions/check_runner_images.xsh
+```
+
 ### Workflow Design
 Multi-stage pipeline with artifact passing:
 1. **Setup**: Checkout code, create artifacts
@@ -147,5 +179,5 @@ Multi-stage pipeline with artifact passing:
 
 ---
 
-*Last updated: October 25, 2025*
+*Last updated: June 2, 2026*
 *Issue resolved after extensive database-level debugging and syntax isolation*