Backend runtime upgraded to Python 3.14 with exact dependency pinning (#57)
Some checks failed
CICD Start / Sanity and Base Decision (push) Successful in 18s
Runner Canary / Canary Heavy (ubuntu-act-8gb) (push) Has been skipped
Runner Canary / Canary Heavy (ubuntu-act-4gb) (push) Has been skipped
Runner Canary / Canary Burst (ubuntu-act (push) Failing after 11m10s
Runner Canary / Canary (ubuntu-latest) (push) Failing after 12m39s
Runner Canary / Canary (ubuntu-act) (push) Failing after 12m42s

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>
This commit was merged in pull request #57.
This commit is contained in:
2026-06-18 11:19:24 -04:00
committed by Xlorep DarkHelm
parent 5d74dd8d8f
commit d02039a22e
52 changed files with 4480 additions and 966 deletions

View File

@@ -0,0 +1,44 @@
# ADR001: Deterministic Runtime Policy
- Status: Accepted
- Date: 2026-05-16
## Context
The backend must behave consistently across local development, CI, and production.
Historically, floating dependency constraints and non-enforced runtime assumptions can
introduce drift and hard-to-diagnose failures.
This branch introduced:
- Python 3.14 as the required runtime baseline
- Exact dependency pinning for backend runtime and development tooling
- Startup compatibility checks that fail fast when runtime policy is violated
- A compatibility endpoint for operational visibility
## Decision
Adopt a deterministic backend runtime policy:
1. Backend runtime is pinned to Python major/minor 3.14.
2. Runtime dependencies are exact pinned versions.
3. Application startup performs runtime policy validation and fails fast on mismatch.
4. Compatibility status is exposed through an API endpoint for diagnostics.
5. The lockfile is treated as the source of truth for reproducible dependency resolution.
## Consequences
Positive:
- Reduced environment drift across dev/CI/prod
- Earlier and clearer failure mode for runtime mismatches
- Improved reproducibility and troubleshooting
Negative:
- More frequent explicit dependency maintenance updates
- Stricter upgrade process for Python/runtime packages
## Alternatives Considered
- Floating dependency constraints with periodic updates
- Rejected due to non-deterministic installs and regression risk
- Runtime checks only in CI, not application startup
- Rejected because deployment/runtime drift can still bypass CI assumptions