Initial public ModelForge release

2026-09-01 21:30:16 +02:00
commit 7082ab955a
490 changed files with 104252 additions and 0 deletions
@@ -0,0 +1,114 @@
+# Compatibility matrix — v1.2.1 plus unreleased RC hardening
+
+Nothing here is implied. The executable contract lives in
+`backend/src/modelforge_api/domain/release.py`; startup and release tests enforce it.
+
+> RC development note: the unreleased product branch now targets additive schema
+> `20260830_0024`, accepts `20260828_0022` and auth-only `20260830_0023` as upgrade sources, and refuses to serve until the
+> audit-chain migration completes. Deployed stable v1.2.1 remains frozen on `20260828_0022`; the
+> released matrix below continues to describe that production artifact until the RC is tagged.
+> Selecting and stamping the post-0024 product version is an explicit pending release tranche; the
+> temporary repository `1.2.1` constant must not be presented as a released schema-0024 artifact.
+
+## Product and database
+
+| Contract | Value |
+| --- | --- |
+| Version | `1.2.1` |
+| Channel | `stable` |
+| Version source | repository `VERSION` |
+| Runtime schema | `20260830_0023` |
+| Direct upgrade-source schema | `20260827_0021`, `20260828_0022` |
+| Minimum direct upgrade | `v1.0.0` |
+| PostgreSQL | 16+; Compose ships 17 |
+| SQLite | unit tests only; **NOT SUPPORTED FOR PRODUCTION** |
+
+The hardened candidate serves only on schema 0023. The upgrade tool accepts 0021 or the production
+0022 head, applies the intervening revisions, validates all existing node credential scopes, and
+reaches 0023 before the API starts. PostgreSQL is the only production database contract; SQLite is
+used only to exercise DDL mechanics in isolated tests.
+
+Compatibility answers remain typed and fail closed:
+
+| Answer | Meaning | Operator action |
+| --- | --- | --- |
+| `COMPATIBLE` | This component understands the observed version | none |
+| `TOO_OLD` | The observed version predates the supported range | upgrade it |
+| `TOO_NEW` | The observed version belongs to a newer release | upgrade this component |
+| `UNKNOWN` | Identity could not be established | investigate; it is refused |
+
+## Agent protocol
+
+| Contract | Value |
+| --- | --- |
+| Current protocol | 1 |
+| Accepted protocols | 1 |
+
+The Node Agent and Runtime Worker remain protocol-compatible with v1.0.0. Release images should
+still be upgraded together so their product and provenance identity is v1.2.1.
+
+## Upgrade matrix
+
+| From | Schema | To | Supported |
+| --- | --- | --- | --- |
+| `v1.0.0` | `20260827_0021` | current candidate / `20260830_0023` | yes; backup and rehearsal required |
+| `v1.1.0` | `20260828_0022` | current candidate / `20260830_0023` | yes; scope validation migration |
+| `v1.1.1` | `20260828_0022` | current candidate / `20260830_0023` | yes; scope validation migration |
+| `v1.2.0` | `20260828_0022` | current candidate / `20260830_0023` | yes; scope validation migration |
+| `v1.2.1` | `20260828_0022` | current candidate / `20260830_0023` | yes; scope validation migration |
+| current candidate | `20260830_0023` | current candidate | yes; already current |
+| older than `v1.0.0` | any | `v1.2.1` | no direct upgrade |
+
+Because 0022 introduces terminal node and decommission-operation state, application-only rollback
+to v1.0.0 is unsupported. Restore the verified pre-upgrade backup. Alembic downgrade may be used in
+isolated verification to prove DDL mechanics, but it is not the production recovery promise.
+
+## Runtime dependencies
+
+| Component | Version |
+| --- | --- |
+| PostgreSQL | >= 16 |
+| Redis | >= 7 |
+| Docker Engine | >= 24 |
+| Docker Compose | >= 2 |
+| Python host tooling | >= 3.12 |
+| NVIDIA container runtime | required on GPU nodes |
+
+The Node Agent image requires a glibc-compatible NVIDIA Container Toolkit/driver injection path.
+GPU Compose projections explicitly fail closed when NVML inventory or telemetry is unavailable.
+CPU-only agents do not require NVML.
+
+## Why this is a MINOR release
+
+Node Decommission adds operator APIs, a Console workflow and an additive schema revision while
+preserving existing capability routes and agent protocol 1. That is a backward-compatible feature
+addition and therefore v1.1.0 under SemVer, not v1.0.1 and not v2.0.0.
+
+## Why v1.2.1 is a PATCH release
+
+v1.2.1 changes no contract, no schema, no protocol and no behaviour an application can observe. It
+corrects how release artifacts are built and stamped: the console's API origin becomes a required
+release input rather than an accidental default, and the Node Agent projection stamps the release
+identity it was already expected to carry. Correcting packaging without changing the product is a
+PATCH under SemVer.
+
+The console image is the one artifact whose *behaviour* differs, because the previous images could
+not reach a non-localhost API at all. That is a defect being repaired, not a capability being added.
+
+## Why v1.2.0 is a MINOR release
+
+v1.2.0 adds substantive, backward-compatible product capability at the console layer: a command
+center, a domain-oriented information architecture, a design system, a responsive mobile console and
+a consistent guarded-action and accessibility vocabulary. No API contract, domain model, runtime
+behavior or schema changed, and no existing route was removed or moved. Adding capability without
+breaking a contract is a MINOR release under SemVer — not a patch, and not a major.
+
+The minimum direct upgrade stays `v1.0.0`. v1.2.0 changes nothing about the upgrade surface, so
+narrowing the supported source range would withdraw a working, tested path for no engineering
+reason.
+
+## Why v1.1.1 is a PATCH release
+
+v1.1.1 changes only the Node Agent runtime packaging and local startup validation needed to restore
+the existing NVIDIA-node contract. It adds no API, database migration, agent protocol field,
+scheduler contract, or operator capability.