diff --git a/docs/adr/ADR001-deterministic_runtime_policy.md b/docs/adr/ADR001-deterministic_runtime_policy.md new file mode 100644 index 0000000..295f83c --- /dev/null +++ b/docs/adr/ADR001-deterministic_runtime_policy.md @@ -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 diff --git a/docs/adr/ADR002-cicd_base_image_tagging.md b/docs/adr/ADR002-cicd_base_image_tagging.md new file mode 100644 index 0000000..d0fe428 --- /dev/null +++ b/docs/adr/ADR002-cicd_base_image_tagging.md @@ -0,0 +1,42 @@ +# ADR002: CICD Base Image Tagging + +- Status: Accepted +- Date: 2026-05-16 + +## Context + +CICD builds depend on a shared base image containing stable system dependencies. +To optimize build times while preserving correctness, the pipeline uses cache-aware +image reuse and fallback behavior. + +This branch reinforced the workflow by ensuring hash-driven base tags are always +computed and non-empty before tagging/pushing, preventing invalid image references. + +## Decision + +Adopt hash-based tagging for the CICD base image with latest fallback: + +1. Compute a deterministic hash from Dockerfile.cicd-base content. +2. Publish base image as both: + - hash-specific tag: cicd-base: + - rolling tag: cicd-base:latest +3. Prefer pulling hash-specific image; fallback to latest when needed. +4. Validate/fallback hash propagation in workflow to avoid empty tag references. + +## Consequences + +Positive: +- Faster CI via stable base-layer reuse +- Better traceability from base image to Dockerfile content +- Reduced risk of malformed image references in workflow execution + +Negative: +- Slightly more workflow complexity +- Registry stores additional hash-tagged images + +## Alternatives Considered + +- Latest-only base image strategy + - Rejected due to reduced traceability and cache precision +- Build base image every run + - Rejected due to slower pipelines and wasted compute