# 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