Cliff Hill
d02039a22e
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>
1.6 KiB
1.6 KiB
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:
- Backend runtime is pinned to Python major/minor 3.14.
- Runtime dependencies are exact pinned versions.
- Application startup performs runtime policy validation and fails fast on mismatch.
- Compatibility status is exposed through an API endpoint for diagnostics.
- 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